chapter-generator

Files (2)

• SKILL.md
• voice-guide.md · references/

SKILL.md (first lines)

# Chapter Generator

Generate a single tutorial chapter from a structured specification. Produces Markdown files with MkDocs-compatible formatting (admonitions, fenced code blocks, mermaid diagrams).

## When to Use

- Generating a single tutorial chapter from a spec
- Creating MkDocs-compatible Markdown tutorials
- Producing educational content following aegir voice principles

## Trigger Phrases

- "Generate chapter [N] from the outline"
- "Create the tutorial for [chapter title]"
- "Write chapter [N] following the spec"
- "/chapter-gen [spec-path-or-inline]"

---

## Required Input

The skill expects a chapter specification with these fields:

```yaml
chapter:
  number: "N.M"
  title: "[Chapter Title]"
  depth: deep  # or light

  opening_hook: |
    [The war story or scenario]

  learning_objectives:
    - "[Objective 1]"
    - "[Objective 2]"

  aha_moments:
    - "[Aha 1]"

  key_queries:
    - description: "[What this demonstrates]"
      code: "[The code/query]"
      expected: "[Expected result]"

  closing_bridge: |
    [Transition to next chapter]

  visual_hooks:
    - type: "[mermaid|table|code_output|bar_chart]"
      description: "[What it shows]"

  falsifiable_claim:
    statement: "[Testable claim]"
    test: "[Verification method]"

  jargon_introduced:
    - term: "[Term]"
      earned_by: "[Intuition before naming]"
```

---

## Generation Process

### Phase 1: Structure

Create the file skeleton:

```markdown
---
title: "[Title]"
---

# [Title]

---
```

### Phase 2: Narrative Opening

Write the opening hook following story-first principles:

1. Drop the reader into a concrete scenario
2. Show something broken, surprising, or tension-creating
3. Include code if applicable (show the failing attempt)
4. Let the reader feel the wrongness before offering the fix

The opening must NOT start with "In this chapter..." or any abstract framing. It must start with a situation.

### Phase 3: Content Sections

For each learning objective, follow this pattern:

1. **Recap** (2-3 sentences): Where we are, what we have, what's next
2. **Scenario**: Concrete example motivating the concept
3. **Code block**: The query/code to try (fenced with language tag)
4. **Expected output**: What they should see (formatted as code output or table)
5. **Aha moment**: The insight that lands AFTER the buildup
6. **Bridge**: Transition to next concept

For `deep` chapters: give each objective full treatment with detailed scenarios and buildup.

For `light` chapters: compress the pattern. Faster transitions, less buildup, keep momentum.

### Phase 4: Exercises

**If `depth: deep`:**
- Include 2-3 exercises with:
  - Problem statement (what to figure out)
  - Hints (for early chapters)
  - Solution in a collapsible admonition
  - Verification (expected output)

**If `depth: light`:**
- Include 1 quick exercise or skip entirely

Exercise format for MkDocs:

```markdown

From Peleke/brunnr, MIT.

More from Peleke/brunnr