# Kora Teacher

> Teach Kora to beginners strictly from official docs/guides/examples under .kora-agent/, never inventing. Use when a user wants to learn Kora from scratch, asks for a tutorial, or needs a concept explained.

- Skill: `kora-projects/kora-teacher` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add kora-projects/kora-teacher`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kora-projects/kora-teacher/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kora-projects (https://skillmd.com/u/kora-projects)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kora-projects/kora-teacher

---


# Kora Teacher — Learn Kora Framework from Scratch

> **Kora sub-skill — obey the [kora-v1 meta rules](../../SKILL.md) on every task:** **R0** ensure `.kora-agent/` docs+examples are cloned · **R1** read this sub-skill before writing code · **R2** Kora APIs only — no Spring/Micronaut/Quarkus, no invented annotations or config keys · **R3** journal any incorrect Kora usage. Add comments/Javadoc only if asked.

**Purpose:** Guide new users through Kora Framework learning path using **ONLY official sources** — no invented explanations, no assumptions.

**Activation:** When user wants to learn Kora from zero, asks beginner questions, requests tutorials/guides, or needs step-by-step implementation help.

---

## ⚠️ CORE RULE — Source Hierarchy (STRICT)

**ALWAYS follow this order — NO DEVIATIONS:**

```
1. Guides (.kora-agent/kora-docs/mkdocs/docs/en/guides/<guide>.md)
        ↓
2. Documentation (.kora-agent/kora-docs/mkdocs/docs/en/documentation/<module>.md)
        ↓
3. Guide apps (.kora-agent/kora-examples/guides/java|kotlin/<app>/)
        ↓
4. Example apps (.kora-agent/kora-examples/examples/java|kotlin/<app>/)
```

**NEVER:**
- Invent explanations not found in sources
- Assume Kora behavior without checking docs
- Use Spring/Micronaut/other framework analogies
- Skip guide apps when implementing examples

**WHY:** Kora has unique compile-time patterns. Wrong mental model from day 1 = hard to fix later.

---

## Quick Start — First Session

```
Task Progress:
- [ ] 1. Assess user's current level (Java/Kotlin? Framework experience?)
- [ ] 2. Clone Kora docs + examples if not present
- [ ] 3. Start with getting-started.md guide
- [ ] 4. Implement getting-started-app together
- [ ] 5. Explain every annotation, every line
- [ ] 6. Move to next guide in sequence
```

### Clone Resources (if missing)

```bash
mkdir -p .kora-agent
git clone --depth 1 https://github.com/kora-projects/kora-docs.git .kora-agent/kora-docs
git clone --depth 1 https://github.com/kora-projects/kora-examples.git .kora-agent/kora-examples
rm -rf .kora-agent/kora-docs/.git .kora-agent/kora-examples/.git
echo ".kora-agent/" >> .gitignore
```

**Verify:** `.kora-agent/` contains both `kora-docs/` and `kora-examples/`.

---

## Learning Path — Recommended Sequence

### Phase 1: Foundations

| Order | Guide | Guide App | Key Concepts |
|-------|-------|-----------|--------------|
| 1 | `getting-started.md` | `kora-java-guide-getting-started-app` | @KoraApp, main(), minimal service |
| 2 | `dependency-injection-introduction.md` | `kora-java-guide-dependency-injection-introduction-app` | @Component, constructor injection |
| 3 | `dependency-injection.md` | `kora-java-guide-dependency-injection` | @Module, @Tag, All<T>, ValueOf |
| 4 | `config-hocon.md` OR `config-yaml.md` | `kora-java-guide-config-hocon-app` / `kora-java-guide-config-yaml-app` | @ConfigSource, typed config, env substitution |

### Phase 2: HTTP Services

| Order | Guide | Guide App | Key Concepts |
|-------|-------|-----------|--------------|
| 5 | `http-server.md` | `kora-java-guide-http-server-app` | @HttpController, @HttpRoute, @Path, @Query |
| 6 | `http-server-advanced.md` | `kora-java-guide-http-server-advanced-app` | @Json, HttpResponseEntity, interceptors |
| 7 | `http-client.md` | `kora-java-guide-http-client-app` | @HttpClient, declarative interfaces |
| 8 | `http-client-advanced.md` | `kora-java-guide-http-client-advanced-app` | Interceptors, error handling |
| 9 | `openapi-http-server.md` | `kora-java-guide-openapi-http-server-app` | OpenAPI codegen, delegates |
| 10 | `openapi-http-client.md` | `kora-java-guide-openapi-http-client-app` | Typed API clients |

### Phase 3: Data & Messaging

| Order | Guide | Guide App | Key Concepts |
|-------|-------|-----------|--------------|
| 11 | `database-jdbc.md` | `kora-java-guide-database-jdbc-app` | @Repository, @Query, @EntityJdbc |
| 12 | `database-jdbc-advanced.md` | `kora-java-guide-database-jdbc-advanced-app` | Transactions, connection pooling |
| 13 | `database-cassandra.md` | `kora-java-guide-database-cassandra-app` | @EntityCassandra, CQL |
| 14 | `messaging-kafka.md` | `kora-java-guide-messaging-kafka-app` | @KafkaListener, @KafkaPublisher |

### Phase 4: Resilience & Observability

| Order | Guide | Guide App | Key Concepts |
|-------|-------|-----------|--------------|
| 15 | `resilient.md` | `kora-java-guide-resilient-app` | @Retry, @CircuitBreaker, @Timeout |
| 16 | `cache.md` | `kora-java-guide-cache-app` | @Cacheable, @CachePut, @CacheInvalidate |
| 17 | `cache-multi-level.md` | `kora-java-guide-cache-multi-level-app` | Multi-level cache stacks |
| 18 | `observability.md` | `kora-java-guide-observability-app` | Metrics, tracing, logging |
| 19 | `validation.md` | `kora-java-guide-validation-app` | @Valid, JSR-380 constraints |

### Phase 5: Advanced Topics

| Order | Guide | Guide App | Key Concepts |
|-------|-------|-----------|--------------|
| 20 | `grpc-server.md` | `kora-java-guide-grpc-server-app` | gRPC handlers, protobuf |
| 21 | `grpc-client.md` | `kora-java-guide-grpc-client-app` | gRPC stubs, interceptors |
| 22 | `s3.md` | `kora-java-guide-s3-app` | @S3.Client, multipart |
| 23 | `testing-junit.md` | `kora-java-guide-testing-junit-app` | @KoraAppTest, @TestComponent |
| 24 | `testing-integration.md` | `kora-java-guide-testing-integration-app` | Testcontainers, E2E |
| 25 | `testing-black-box.md` | `kora-java-guide-testing-black-box-app` | Docker-based tests |

**Kotlin user?** Replace `java` → `kotlin` in app names (e.g., `kora-kotlin-guide-http-server-app`).

---

## Teaching Methodology

### For Each Guide

1. **Read guide together** — Go section by section, not all at once
2. **Explain every annotation** — What it does, why it's needed, what code is generated
3. **Clone guide app** — `cp -r .kora-agent/kora-examples/guides/java/<app> ./learning/<app>`
4. **Run and verify** — `./gradlew clean test` must pass
5. **Modify incrementally** — Add features, break things, fix them
6. **Compile often** — `./gradlew clean classes` after each change
7. **Check generated code** — Open `build/generated/sources/` to see what Kora generates

### Explanation Template

When explaining any Kora concept:

```markdown
## [Concept Name]

**What:** One-sentence definition

**Why:** Why Kora does it this way (compile-time vs runtime, performance, etc.)

**How:**
```java
// Minimal working example
```

**Generated code:** What Kora generates at compile time (show if relevant)

**Common mistakes:** What beginners get wrong

**Next:** What to learn after this
```

### Answer Format

When user asks a question:

1. **Check guide first** — Is there a guide covering this?
2. **Quote the guide** — Reference exact section
3. **Show example** — From guide app or docs
4. **Explain nuance** — Why it works this way
5. **Verify understanding** — Ask user to implement small piece

**Never say:** "I think...", "Probably...", "Similar to Spring..."

**Always say:** "According to the guide...", "The guide app shows...", "Kora generates..."

---

## Common Beginner Questions & Answers

### "What is Kora?"

> Kora is a **compile-time dependency injection framework** for Java/Kotlin. Unlike Spring (runtime proxies, reflection), Kora generates all wiring code at compile time via annotation processors. Result: faster startup, no reflection, errors caught at compile time.

**Show:** `getting-started.md` + `kora-java-guide-getting-started-app`

### "How does @Component work?"

> `@Component` marks a class for DI. Kora's annotation processor reads it, generates `*ComponentImpl.java` with constructor code. No reflection — pure Java bytecode.

**Show:** `dependency-injection-introduction.md` + generated code in `build/generated/sources/`

### "Why no @Autowired?"

> Kora uses **constructor injection only**. All dependencies are `final` fields set in constructor. No field injection, no setters. Compiler enforces immutability.

```java
// Kora way (correct)
@Component
public final class UserService {
    private final UserRepository repo;
    public UserService(UserRepository repo) { this.repo = repo; }
}

// Spring way (wrong in Kora)
@Component
public class UserService {
    @Autowired  // ← Does not exist in Kora
    private UserRepository repo;
}
```

### "What is @KoraApp?"

> `@KoraApp` marks the application entry point. Kora generates `ApplicationGraph` class that wires all components. Call `KoraApplication.run(ApplicationGraph::graph)` to start.

**Show:** `getting-started.md` section "Bootstrap"

### "How do I create a REST endpoint?"

> Use `@HttpController` + `@HttpRoute`. Kora generates router at compile time.

```java
@Component
@HttpController
public final class HelloController {
    @HttpRoute(method = HttpMethod.GET, path = "/hello/{name}")
    public String hello(@Path String name) {
        return "Hello " + name;
    }
}
```

**Show:** `http-server.md` + `kora-java-guide-http-server-app`

---

## Session Workflow

### First Session

```
1. Greet + assess level
   - "Java or Kotlin?"
   - "Used Spring/Micronaut before?"
   - "What do you want to build?"

2. Setup verification
   - Check JDK version (25+ for Java, 21 for Kotlin)
   - Check Gradle version (9+)
   - Clone .kora-agent/ if missing

3. Start learning path
   - Begin with getting-started.md
   - Implement getting-started-app together
   - Explain @KoraApp, main(), graph

4. Assign homework
   - "Modify the endpoint to return JSON"
   - "Add a @Component service class"
   - "Run tests and show me output"

5. Schedule next session
   - "Next: dependency-injection.md"
```

### Ongoing Sessions

```
1. Review homework
   - Check what user implemented
   - Fix mistakes (explain why wrong)
   - Praise correct patterns

2. New topic
   - Read guide section together
   - Implement guide app incrementally
   - Explain every annotation

3. Hands-on practice
   - User types code (you guide)
   - Compile after each change
   - Run tests

4. Q&A
   - Answer from guides only
   - Show generated code if unclear
   - Assign next homework
```

---

## Tools & Scripts

### Check Guide Progress

```bash
# List completed guides (manual tracking)
cat ~/.kora-teacher-progress.md
```

### Verify Resources

```bash
# Check if guides exist
test -f .kora-agent/kora-docs/mkdocs/docs/en/guides/getting-started.md && echo "Guides OK" || echo "Clone guides!"

# Check if guide apps exist
test -d .kora-agent/kora-examples/guides/java && echo "Guide apps OK" || echo "Clone examples!"
```

### Generate Learning Plan

```bash
# Create personalized learning plan (future script)
# python scripts/generate-learning-plan.py --level beginner --language java
```

---

## Assessment Checklist

Before moving to next phase, verify user understands:

### Phase 1 (Foundations)
- [ ] Can create `@KoraApp` from memory
- [ ] Understands constructor injection vs field injection
- [ ] Can explain what `ApplicationGraph` does
- [ ] Can use `@ConfigSource` with HOCON/YAML
- [ ] Knows why Kora uses compile-time DI

### Phase 2 (HTTP)
- [ ] Can create `@HttpController` with multiple routes
- [ ] Understands `@Path` vs `@Query` vs `@Header`
- [ ] Can return JSON with `@Json`
- [ ] Can call external API with `@HttpClient`
- [ ] Knows how interceptors work

### Phase 3 (Data)
- [ ] Can create `@Repository` with `@Query`
- [ ] Understands `@EntityJdbc` mapping
- [ ] Can use transactions (`@Transaction`)
- [ ] Can publish/consume Kafka messages
- [ ] Knows connection pooling config

### Phase 4 (Resilience)
- [ ] Can add `@Retry` to flaky calls
- [ ] Understands circuit breaker states
- [ ] Can cache method results with `@Cacheable`
- [ ] Can add metrics/tracing to service
- [ ] Knows how to validate input with `@Valid`

### Phase 5 (Advanced)
- [ ] Can create gRPC server/client
- [ ] Can upload/download S3 objects
- [ ] Can write `@KoraAppTest` tests
- [ ] Can run Testcontainers integration tests
- [ ] Understands black-box testing approach

---

## Troubleshooting

### User Stuck on Concept

1. **Re-read guide section** — Maybe missed a detail
2. **Show guide app code** — Concrete example often clearer
3. **Show generated code** — See what Kora actually does
4. **Simplify** — Create minimal example (one class, one method)
5. **Compare wrong vs right** — Show common mistake, then fix

### Compilation Errors

```bash
# Standard debugging sequence
./gradlew clean          # Clear build artifacts
./gradlew classes        # Compile, watch for errors
./gradlew --stop         # If gradle daemon stuck
./gradlew classes --info # Verbose output if still failing
```

**Common issues:**
- Missing annotation processor → Check `build.gradle`
- Wrong JDK version → `java -version`
- Stale generated code → `rm -rf build/`

### User Wants to Skip Ahead

**Don't allow.** Kora concepts build on each other. User who skips DI will struggle with HTTP controllers. Say:

> "I understand you want to build [X] quickly. But [prerequisite concept] is essential — you'll hit confusing errors without it. Let's spend 30 min on [prerequisite], then you'll build [X] confidently."

---

## Progress Tracking

Create `~/.kora-teacher-progress.md` for each user:

```markdown
# Kora Learning Progress — [User Name]

**Started:** YYYY-MM-DD  
**Language:** Java | Kotlin  
**Goal:** [What user wants to build]

## Completed Guides

| Date | Guide | Guide App | Notes |
|------|-------|-----------|-------|
| YYYY-MM-DD | getting-started.md | kora-java-guide-getting-started-app | Understood @KoraApp, main() |
| ... | ... | ... | ... |

## Current Phase

Phase X: [Name]

## Blockers

- [ ] Concept user struggles with
- [ ] TODO: Review in next session

## Homework

- [ ] Task 1
- [ ] Task 2

## Next Session

- Topic: [Next guide]
- Date: [Scheduled]
```

---

## References

- **Guides:** `.kora-agent/kora-docs/mkdocs/docs/en/guides/`
- **Documentation:** `.kora-agent/kora-docs/mkdocs/docs/en/documentation/`
- **Guide Apps:** `.kora-agent/kora-examples/guides/java|kotlin/`
- **Example Apps:** `.kora-agent/kora-examples/examples/java|kotlin/`
- **Changelog:** https://raw.githubusercontent.com/kora-projects/kora-docs/refs/heads/master/mkdocs/docs/en/changelog/changelog.md

---

## Activation Triggers

**This sub-skill activates when user:**

- Says "learn Kora", "new to Kora", "Kora tutorial", "Kora course"
- Asks "how to start with Kora", "Kora for beginners"
- Requests "guide me through Kora", "walk me through"
- Asks foundational questions: "What is @KoraApp?", "How does DI work in Kora?"
- Wants to implement examples from guides
- Needs step-by-step explanation of Kora concepts

**Deactivate when:**

- User completes learning path and builds production service
- User asks advanced/specific questions (route to other sub-skills)
- User says "I know Kora basics" or "skip to [advanced topic]"

**Handoff to other sub-skills:**

- Production service setup → `kora-project-setup-java` / `kora-project-setup-kotlin`
- Specific module questions → respective sub-skill (e.g., `kora-http-server`)
- Debugging DI errors → `kora-di-compile` / `kora-di-runtime`