Vercel Logo

Build the Generator

The skill frontmatter tells Claude when the skill applies. The body defines what to do after it loads.

You'll write that workflow and its formatting reference in this lesson.

Outcome

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

Fast Track

  1. Write step-by-step instructions in SKILL.md
  2. Write formatting rules in references/doc-patterns.md
  3. 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 ask the user to confirm before proceeding. This lets the user verify the scope before the skill modifies files.

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)

Name the code patterns Claude should inspect so the output does not depend on guesswork.

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 to confirm with the user, then save the output to app/api/docs/route.ts. In the next lesson, the skill will replace the starter stub with a route handler that serves the generated Markdown.

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)

The checklist gives Claude concrete criteria for reviewing its output.

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 the output is vague, make the existing instruction more specific.

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, replace "Read the types" with a concrete action: "Find the TypeScript file imported by the route handler, extract every exported interface, and list each field with its type." Apply the same approach to any skipped step.

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)

Was this helpful?

supported.