Build the Generator

Recipes have two parts: the ingredient list and the instructions. Knowing you need flour and water doesn't help unless you also know to mix them, let the dough rest, and bake at 450. Skills work the same way. The frontmatter tells Claude what the skill is. The body tells Claude what to do.

Let's write the instructions.

Outcome

Write the SKILL.md body and the references/doc-patterns.md file for the API docs generator skill.

Fast Track

Write step-by-step instructions in SKILL.md
Write formatting rules in references/doc-patterns.md
Add a quality checklist to SKILL.md

Hands-on exercise

The starter already has api-docs-generator/SKILL.md and api-docs-generator/references/doc-patterns.md with TODO stubs. Open them up and fill in the real content.

SKILL.md instructions

The body of SKILL.md should walk Claude through a five-step process:

Step 1: Discover API routes. Tell Claude to search the project for route handler files. Be specific about the glob pattern:

Search the project for all route handler files:
Glob for **/api/**/route.ts and **/api/**/route.js

Tell Claude to list the discovered routes and confirm with the user before proceeding. This is a good pattern for any skill that modifies files. Let the user verify before the skill does its work.

Step 2: Analyze each route. For each route file, tell Claude what to extract:

HTTP methods exported (GET, POST, etc.)
URL path (derived from the file path)
Query parameters (look for searchParams.get() calls)
Request body shape (look for request.json() destructuring)
Response shapes (look for NextResponse.json() calls)
Error responses (look for non-200 status codes)
Validation rules (conditionals that return errors)

Be specific about what to look for in the code. The more precise your instructions, the more reliable the output.

Step 3: Read the types. Tell Claude to find the TypeScript types referenced by the route handlers and use them to build the schema table.

Step 4: Generate the markdown. Provide the document structure as a template. Reference the formatting rules:

Consult `references/doc-patterns.md` for the formatting rules.

Step 5: Write the file. Tell Claude where to save the output (app/api/docs/route.ts) and to confirm with the user first. The starter already has this file with a placeholder stub. When you run this skill in the next lesson, Claude will replace that stub with a fully working route handler that serves the real markdown documentation. The whole point of the skill is that you never have to author that file yourself.

The quality checklist

End the SKILL.md with a checklist that Claude should verify before finishing:

## Quality checklist
 
- [ ] 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)

This is what makes the skill self-correcting. Claude will check its own output against these criteria.

references/doc-patterns.md

This file contains the formatting rules we established in Section 2. Write it as guidance that Claude can follow when generating docs:

Why agents need structured docs (not prose)
Endpoint signatures in code blocks, not inline
Parameters as tables with name, type, required, description
Curl examples with real values
Complete JSON responses (no truncation)
Every error case documented separately
Schema tables at the end
Workflow examples showing how endpoints chain together

Include anti-patterns too. Tell Claude what not to do: no prose-only endpoint descriptions, no ... in responses, no placeholder values.

Vague instructions produce vague output

Compare these two instructions:

Too vague: "Document the endpoints."

Specific enough to work: "For each endpoint, write a curl example using real values from the seed data. Include the full URL, all required headers, and the request body for POST requests."

If Claude produces sloppy output, the fix is almost always tightening the instruction, not adding more of them.

Don't put everything in SKILL.md

The formatting rules belong in references/ because they're supporting detail. If you put everything in the main file, the skill loads all of it into context immediately. Progressive disclosure keeps the initial load light.

Troubleshooting: Claude skips a step

If Claude skips Step 3 (reading the types) or any other step, the instruction for that step isn't specific enough. "Read the types" is easy to gloss over. "Find the TypeScript file imported by the route handler, extract every exported interface, and list each field with its type" gives Claude no room to skip ahead. When a step gets skipped, make its instruction more concrete.

Try It

After writing both files, verify the structure:

ls api-docs-generator/

SKILL.md
references/

ls api-docs-generator/references/

doc-patterns.md

Open SKILL.md and read through it. Does each step tell Claude exactly what to do? Could you follow the instructions yourself and produce correct docs? If not, the instructions need more detail.

Commit

git add -A && git commit -m "feat(skill): write SKILL.md instructions and doc-patterns reference"

Done-When

SKILL.md has valid frontmatter with name and description (including trigger phrases)
SKILL.md body has 5 clear steps: discover, analyze, read types, generate, write
Step 2 specifies exactly what to extract from each route file
Step 4 references references/doc-patterns.md
Quality checklist has at least 5 verification items
references/doc-patterns.md covers formatting rules and anti-patterns

Solution

api-docs-generator/SKILL.md

---
name: api-docs-generator
description: Generates agent-friendly markdown documentation for API routes. Use when user says "generate docs", "document this API", "create API documentation", or "make docs for my endpoints".
---
 
# API Docs Generator
 
Generate comprehensive, agent-friendly markdown documentation for API route handlers in a Next.js App Router project.
 
## Instructions
 
### Step 1: Discover API routes
 
Search the project for all route handler files:
 
Glob for **/api/**/route.ts and **/api/**/route.js
 
List all discovered routes and confirm with the user before proceeding.
 
### Step 2: Analyze each route
 
For each route file, extract:
 
- HTTP methods exported (GET, POST, PUT, DELETE, PATCH)
- URL path (derived from the file path)
- Query parameters (look for `searchParams.get()` calls)
- Request body shape (look for `request.json()` destructuring)
- Response shapes (look for `NextResponse.json()` calls)
- Error responses (look for non-200 status codes)
- Validation rules (look for conditionals that return error responses)
 
### Step 3: Read the types
 
Look for a types file referenced by the route handlers. Extract the TypeScript interfaces and use them to build the schema table in the docs.
 
### Step 4: Generate the markdown
 
Produce a single markdown document following this structure. Consult `references/doc-patterns.md` for the formatting rules.
 
### Step 5: Write the file
 
Save the generated markdown to `app/api/docs/route.ts` as a route handler that returns the markdown string with `Content-Type: text/markdown; charset=utf-8`.
 
Ask the user to confirm the output location before writing.
 
## Quality checklist
 
Before finishing, verify the generated docs include:
 
- [ ] 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)
- [ ] At least 2 workflow examples showing how endpoints chain together for real tasks

api-docs-generator/references/doc-patterns.md

# Documentation Patterns for Agent-Friendly APIs
 
These patterns make API documentation easy for AI agents to parse and use correctly.
 
## Why agents need different docs
 
Human developers skim docs, infer patterns, and fill in gaps from experience. Agents read docs literally. If the docs are ambiguous, the agent will guess wrong. If an error case is undocumented, the agent won't know how to recover.
 
Agent-friendly docs are explicit, structured, and example-heavy.
 
## Formatting rules
 
### Endpoints
 
Always include the HTTP method and full path on their own line in a code block. Not inline. Agents parse the code block reliably. Prose descriptions of URLs are error-prone.
 
### Parameters as tables
 
Use markdown tables for query parameters and request body fields. Always include: parameter name, type, whether it's required or optional, and a short description. Agents parse tables into structured data. Bullet lists of parameters are harder to extract reliably.
 
### Example requests with curl
 
Use curl for all example requests. Include the full URL, all required headers, and the request body for POST/PUT/PATCH. Agents can execute curl commands directly.
 
### Example responses as JSON blocks
 
Show the complete response body, not a truncated version. Include all fields, realistic values, and the correct JSON structure.
 
### Every error case gets its own block
 
Document each error response separately with the HTTP status code, the condition that triggers it, and the exact response body.
 
### Schema section
 
End the docs with a schema section that lists every data type as a table with field name, type, and description.
 
### Workflow examples
 
End the docs with a Workflows section after the schema. Each workflow is a numbered sequence of API calls that accomplish a real task. Include a descriptive name, numbered steps with method + path in inline code, and a short explanation of why each call is made. Include at least 2 workflows covering common multi-step tasks.
 
## Anti-patterns to avoid
 
- Prose-only descriptions of endpoints (no code blocks with method + path)
- Truncated responses with "..." or "and so on"
- Missing error cases (agents will not know how to recover)
- Generic placeholder data in examples ("string", "number" instead of real values)
- Undocumented query parameters (agents won't discover them by experimentation)