Iterate and Ship

Your first run told you a lot. Maybe Claude nailed the curl examples but missed an error case. Maybe the schema table was perfect but the parameter descriptions were vague. Whatever the gaps, the fix is the same: tighten the instructions and run it again.

This is the iteration loop. It's where a decent skill becomes a reliable one.

Outcome

Refine the skill instructions based on evaluation results, re-run the skill, and verify the final documentation end-to-end.

Fast Track

1. Update SKILL.md or references/doc-patterns.md based on issues found in 3.3
2. Re-run the skill and compare output
3. Verify the final /api/docs endpoint with curl

Hands-on exercise

Fixing the instructions

Go back to the notes you took in the last lesson. For each issue, decide where the fix belongs:

Fix it in SKILL.md if the problem is about what Claude does or what order it does it in. Skipped a step? Make the instruction more specific. Wrong glob pattern? Update the path. Forgot to confirm with the user? Add that check.

Fix it in references/doc-patterns.md if the problem is about formatting. Tables missing a column? Add the column to the formatting rules. Curl examples using localhost instead of the full URL? Add that as an explicit requirement. Responses truncated with ...? Call it out in the anti-patterns section.

The distinction matters. SKILL.md controls the process. The reference doc controls the format. Mixing them up makes both harder to maintain.

Re-running the skill

After updating the files, invoke the skill again:

Generate docs for my API

Claude will re-read the updated SKILL.md and reference files. Compare this output to the first run:

• Did the issues you noted get fixed?
• Did the fixes introduce any new problems?
• Does the quality checklist pass now?

Most skills need 2-3 rounds. The first run reveals what you thought was clear but wasn't. The second run usually gets close. The third is polish. If you're still fixing things after four or five runs, the problem is likely structural, not wording. Step back and ask whether the steps themselves are in the right order.

Verifying end-to-end

Once the output looks solid, verify the full pipeline. Start with the docs endpoint:

curl http://localhost:3000/api/docs

Read through the full response. Check for completeness: all four endpoints, all error cases, all parameters, all response shapes. Then run every curl example from the generated docs. Not three of them. All of them.

# List all feedback
curl "http://localhost:3000/api/feedback"
 
# Filter by course
curl "http://localhost:3000/api/feedback?courseSlug=knife-skills"
 
# Submit new feedback
curl -X POST "http://localhost:3000/api/feedback" \
  -H "Content-Type: application/json" \
  -d '{
    "courseSlug": "bread-baking",
    "lessonSlug": "scoring-dough",
    "rating": 5,
    "comment": "The lame technique demo was incredibly helpful.",
    "author": "Alex Turner"
  }'
 
# Get a single entry
curl "http://localhost:3000/api/feedback/fb-001"
 
# Get summary stats
curl "http://localhost:3000/api/feedback/summary"

Every example should produce output that matches the documented response shapes. If any example fails or returns an unexpected shape, either the docs or the API has a bug. Fix it and re-run.

Skills are living documents

This skill isn't finished just because the output is correct today. APIs change. You'll add new endpoints, change validation rules, rename fields. When that happens, the skill needs to keep up.

The good news is that updating a skill is the same loop you practiced here: change the instructions, re-run, check the output. There's no build step, no deployment, no versioning headache. You edit a markdown file and Claude reads the new version immediately.

Treat your skill like you'd treat a good test suite. When the code changes, the skill should change with it.

The final project

Here's what the complete project looks like:

your-project/
├── api-docs-generator/          # The skill
│   ├── SKILL.md                 # Refined instructions
│   └── references/
│       └── doc-patterns.md      # Formatting rules
├── app/
│   ├── llms.txt/route.ts        # llms.txt index
│   ├── llms-full.txt/route.ts   # Complete docs in one response
│   └── api/
│       ├── docs/route.ts        # Generated by the skill
│       ├── docs.md/route.ts     # Markdown docs endpoint
│       └── feedback/
│           ├── route.ts         # GET (list + filter) and POST
│           ├── [id]/route.ts    # GET single entry
│           └── summary/route.ts # GET aggregate stats
├── data/
│   └── feedback.json            # Seed data
└── lib/
    ├── data.ts                  # Read/write utility
    └── types.ts                 # Feedback interface

Commit

git add -A && git commit -m "feat(skill): finalize and test API docs generator skill"

Done-When

• SKILL.md or references/doc-patterns.md has been updated based on evaluation results
• The skill has been re-run at least once after updates
• Generated docs pass all five items on the quality checklist
• Every curl example from the generated docs produces matching output
• curl http://localhost:3000/api/docs returns complete, structured markdown
• The skill folder is committed to the repo

Solution

The solution for this lesson is the complete skill from the complete/ repo, which you built in lesson 3.2 and refined here. The key difference is specificity: your SKILL.md instructions should now be tighter based on what you observed during testing.

If your skill consistently produces correct output on the first or second try, you're done. If it needs more than three rounds, the instructions need more specificity, not more steps.

You built an API. You documented it for agents. Then you built a skill that automates the documentation. The next time this API changes, you won't update the docs by hand. You'll say "generate docs" and let the skill handle it.