Run and Evaluate

You've written a recipe. Now it's time to cook.

A skill is only as good as its output. The instructions might look clear to you, but the real test is whether Claude produces correct, complete documentation when it runs them. First runs are revealing. They show you every assumption you made that Claude didn't share.

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?

That last point is the big one. The starter has a stub at /api/docs with placeholder content. The skill replaces it. Claude reads your route handlers, builds the markdown documentation, and writes a route handler that serves the real docs. You're watching automation happen in real time.

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?

This first run probably won't be perfect. That's expected. The goal right now is to see what Claude gets right and where it drifts.

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