Exercise Author

Exercise Author Skill

You generate missing exercise files from a module's README.md planning table.

When to Use This Skill

Invoke this skill when:

• A module README.md has an exercise planning table but missing exercise files
• User asks to "create missing exercises" or "generate exercise files"
• User points to a module directory and wants all planned exercises implemented

Example invocations:

• "@exercise-author create missing exercises for module 99"
• "Generate all exercise files for modules/10-agentic-sdlc/"
• "Look at module 5 and create any exercises that don't exist yet"

How It Works

Step 1: Read Module README.md

1. Locate the module directory (e.g., modules/99-agent-skills-vscode/)
2. Read the README.md file
3. Find the "📋 Exercise Planning Table" section
4. Parse each row to extract:
   • Exercise number (e.g., "99.1", "99.2")
   • Exercise filename from link (e.g., "exercise-01.md")
   • Exercise title
   • Lead persona
   • Support personas
   • Problem description with metrics
   • Solution description
   • Key metrics (before→after)
   • Artifacts created

Step 2: Check Which Files Exist

For each exercise in the planning table:

1. Check if the file exists in the module directory
2. If the file exists, skip it
3. If the file is missing, add to creation list

Step 3: Create Missing Exercise Files

For each missing exercise file:

1. Use the TEMPLATE.md structure from .github/skills/exercise-author/TEMPLATE.md

2. Fill in the template with data from the planning table:

   • Exercise number and title from table
   • Lead persona
   • Support personas
   • Problem metrics from "Problem" column
   • Solution approach from "Solution" column
   • Before/After metrics from "Key Metrics" column
   • Artifacts from "Artifacts" column

3. Generate realistic content:

   • 📖 The Challenge: 2-3 paragraphs showing the problem through persona lenses
   • 🔄 The Transformation: Table with Before/After scenarios using metrics from planning table
   • 🎯 Your Goal: Single sentence objective derived from solution
   • 📋 Steps: 3-4 detailed steps to implement the solution
   • ✅ Success Criteria: 3-4 checkboxes for verifiable outcomes
   • 📚 Official Docs: 2-3 relevant documentation links
   • 🔗 What You Built: List artifacts with purposes
   • ➡️ Next Up: Link to next exercise or module

4. Create the file at modules/[module-dir]/[exercise-filename]

Important Guidelines

Metrics Must Be Concrete

Every Before/After comparison must include:

• Time metrics (e.g., "45 minutes → 5 minutes")
• Count metrics (e.g., "12 violations → 0 violations")
• Round/cycle metrics (e.g., "3 review rounds → 1 round")

Use the metrics from the planning table's "Key Metrics" column.

Persona Voice Authenticity

Write in the persona's voice (see modules/00-orientation/PERSONAS.md):

• Sarah (Skeptical Senior): ROI-focused, validates with metrics, "I tested this by..."
• David (Seasoned Architect): Expertise validation, AI amplifies experience
• Marcus (DevOps Developer): Infrastructure focus, workflow friction removal
• Elena (Quality Champion): Quality validation, edge case coverage
• Rafael (Product Visionary): Business value, stakeholder communication

File Structure

Each exercise file must:

1. Start with # Exercise N.X: [Title]
2. Include all sections from TEMPLATE.md
3. Use proper emoji vocabulary (📖, ❌, ✨, 🎯, 📋, ✅, 📚, 🔗, ➡️)
4. Have horizontal rules (---) between major sections
5. Reference artifacts created (from planning table's "Artifacts" column)

Official Documentation Links

Prioritize documentation in this order:

1. VS Code Copilot docs (for editor features)
2. GitHub Docs (for Copilot concepts, best practices)
3. Microsoft Learn (for Azure/enterprise features if relevant)

Never use third-party blog posts as primary documentation.

Example File Generation

CRITICAL: Whenever an exercise asks users to create a file, automatically generate a reference implementation in examples/completed-config/ to provide copy-paste scaffolding and validation.

Detecting File Creation Instructions

Scan exercise content (especially Steps section) for patterns indicating file creation:

• "Create .github/instructions/frontend.instructions.md"
• "Add docs/ARCHITECTURE.md"
• "Create a new file at path/to/file.ext"
• "Set up .github/agents/feature-plan.agent.md"
• Artifacts listed in planning table's "Artifacts" column

Example File Location Mapping

Mirror the repository structure in examples/completed-config/:

Note: .github/ maps to examples/completed-config/.github/ but fanhub/docs/ maps to examples/completed-config/docs/ (no fanhub prefix).

Example Content Generation Guidelines

Create complete, realistic implementations that:

1. Match the exercise's learning objectives — Demonstrate the exact technique being taught
2. Use persona-specific scenarios — Reference FanHub domain (TV shows, characters, episodes)
3. Include inline explanations — Add comments/notes explaining key decisions
4. Show concrete patterns — No placeholders like [YOUR CODE HERE] or TODO: implement
5. Reflect module progression — Later modules build on earlier artifacts

Auto-Insert Compare Your Work Section

When exercises involve file creation, automatically add this to the Success Criteria section:

> 📂 **Compare Your Work**: [`examples/completed-config/{relative-path}`](../../examples/completed-config/{relative-path})

Path calculation rules:

• Use relative path from module directory to examples folder (typically ../../examples/)
• Include the full path within completed-config/
• Link text should show the path for clarity

Example File Metadata

Add frontmatter comments to generated example files linking back to source exercise:

<!-- Reference implementation for Module X, Exercise X.Y: [Title] -->
<!-- This example demonstrates: [brief description of what's being taught] -->

[Actual content starts here]

Example Workflow

User says: "@exercise-author create missing exercises for module 99"

You:

1. Read modules/99-agent-skills-vscode/README.md
2. Parse exercise planning table
3. Check which files exist:
   • exercise-01.md ✅ exists
   • exercise-02.md ❌ missing
   • exercise-03.md ❌ missing
4. Create modules/99-agent-skills-vscode/exercise-02.md using planning table data + TEMPLATE.md structure
5. Detect file creation instructions in exercise-02.md:
   • Step 2 says "Create .github/skills/bug-analyzer/SKILL.md"
   • Artifacts list includes .github/skills/bug-analyzer/examples/sample-bug.js
6. Generate example files:
   • Create examples/completed-config/.github/skills/bug-analyzer/SKILL.md with complete skill definition
   • Create examples/completed-config/.github/skills/bug-analyzer/examples/sample-bug.js with realistic bug example
   • Add metadata comments linking back to Module 99, Exercise 2
7. Add Compare Your Work section to exercise-02.md Success Criteria
8. Create modules/99-agent-skills-vscode/exercise-03.md (repeat steps 5-7)
9. Report: "Created 2 missing exercises and 3 example files"

Quality Checklist

Before creating each file, verify:

• All metrics from planning table are included
• Lead and support personas match the table
• Steps are actionable (commands, paths, expected results)
• Success criteria are verifiable checkboxes
• Artifacts listed in planning table appear in "What You Built"
• Official docs links are first-party (GitHub, VS Code, Microsoft)
• Persona voice is authentic to their background
• Before/After transformation shows measurable improvement
• Example files generated for all artifacts users create
• Compare Your Work sections added when files are created