Run and Evaluate

The instructions are ready for a first run.

Evaluate the skill by the documentation it produces. A first run reveals instructions that seemed clear to you but left room for Claude to interpret them differently.

Outcome

Invoke the API docs generator skill in Claude Code and evaluate the generated documentation against the quality checklist.

Fast Track

1. Trigger the skill in Claude Code with "generate docs for my API"
2. Watch Claude discover routes, analyze them, and generate the docs
3. Run the quality checklist and test the generated curl examples

Hands-on exercise

Invoking the skill

Open Claude Code in your project directory. The skill should be discoverable because the api-docs-generator/ folder is in the project root.

Try triggering it with one of the phrases from the description field:

Generate docs for my API

Claude should load the skill and start working through the steps. Watch what happens:

1. Does it find all four route files?
2. Does it list them and ask you to confirm?
3. Does it analyze each route correctly?
4. Does it create the app/api/docs/route.ts file?

The starter's /api/docs route contains placeholder content. The skill should read the route handlers, generate the Markdown, and replace that stub with a working documentation route.

Evaluating the output

Once Claude generates the docs, run through the quality checklist from the SKILL.md:

• Every endpoint has at least one example request (curl) and response (JSON)
• Every error case is documented with its status code
• Query parameters and request body fields list their types and whether they are required
• The schema section matches the actual TypeScript types
• The markdown renders correctly (no broken tables or unclosed code blocks)

Also check against what you built by hand in Section 2:

• Are the curl examples using real seed data values?
• Do the error messages match what the code actually returns?
• Is the schema complete with all seven fields?

Use the first run to identify which requirements Claude followed and where the output drifted.

Testing the generated docs

Start your dev server and hit the generated endpoint:

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

The output should be structured markdown with all four endpoints documented. Now pick a few curl examples from the generated docs and run them:

# From the docs: list feedback filtered by course
curl "http://localhost:3000/api/feedback?courseSlug=knife-skills"
 
# From the docs: 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"
  }'
 
# From the docs: get summary
curl "http://localhost:3000/api/feedback/summary"

Every example should produce output that matches the documented response shapes. If an example fails or returns something unexpected, make a note. We'll fix it in the next lesson.

Common issues

The skill doesn't trigger. The description field might not include the phrase you used. Add more trigger phrases to the SKILL.md frontmatter. The more natural language variations you include, the more reliably it activates.

Claude skips an endpoint. Step 1 might not be finding all the route files. Check the glob pattern. Make sure it covers nested routes like app/api/feedback/[id]/route.ts.

Examples use placeholder data. The instructions in Step 4 might not be specific enough about using real values. Add explicit guidance: "Use realistic values from the project's seed data, not placeholders like 'string' or 'example'."

Error cases are missing. Step 2 might not be specific enough about what to extract. Make sure it mentions looking for non-200 status codes and conditionals that return error responses.

Schema doesn't match the types. Step 3 might not be pointing Claude to the right file. Be explicit: "Look for TypeScript interfaces imported by the route handlers, typically in lib/types.ts."

Commit

git add -A && git commit -m "feat(skill): first invocation of API docs generator skill"

Done-When

• The skill triggers when you say "generate docs" in Claude Code
• Claude discovers all four route files
• The skill creates app/api/docs/route.ts (you didn't write it by hand)
• curl http://localhost:3000/api/docs returns structured markdown
• You've run the quality checklist and noted any gaps
• You've tested at least three curl examples from the generated docs