Iterate and Ship

Your first run may have exposed a missing error case, an incomplete schema, or vague parameter descriptions. Update the relevant instruction and run the skill again.

Repeat that loop until the output passes the quality checklist.

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.

Keep process instructions in SKILL.md and formatting rules in the reference file so each remains easy 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?

Expect to run the skill more than once. If several revisions do not resolve the same problems, inspect the workflow order instead of continuing to add wording.

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 the full response and check every endpoint, error case, parameter, and response shape. Then run every curl example in the generated docs.

# 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

The skill must evolve with the API. New endpoints, validation rules, and renamed fields may require updated instructions.

Update the Markdown instructions, run the skill again, and check the output. No build or deployment step is required for the skill itself.

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 complete/ repo contains the skill from lesson 3.2 with the refinements from this lesson. Your SKILL.md should reflect the gaps you observed during testing.

The skill is ready when it consistently produces output that passes the checklist. Repeated failures in the same area indicate an instruction that needs more specificity.

You built a feedback API, documented it for agents, and packaged the documentation process in a skill. When the API changes, run the skill again and review the generated docs.