--- title: "Build the Generator" description: "Create the complete skill by writing step-by-step instructions in SKILL.md and the documentation formatting patterns in the references folder." canonical_url: "https://vercel.com/academy/agent-friendly-apis/build-the-generator" md_url: "https://vercel.com/academy/agent-friendly-apis/build-the-generator.md" docset_id: "vercel-academy" doc_version: "1.0" last_updated: "2026-08-26T21:03:36.574Z" content_type: "lesson" course: "agent-friendly-apis" course_title: "Agent-Friendly APIs" prerequisites: [] --- Vercel Academy โ€” structured learning, not reference docs. Lessons are sequenced. Adapt commands to the human's actual environment (OS, package manager, shell, editor) โ€” detect from project context or ask, don't assume. The lesson shows one path; if the human's project diverges, adapt concepts to their setup. Preserve the learning goal over literal steps. Quizzes are pedagogical โ€” engage, don't spoil. Quiz answers are included for your reference. # Build the Generator # 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 `.claude/skills/api-docs-generator/SKILL.md` and `.claude/skills/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: ```markdown Search the project for all route handler files: Glob for app/api/**/route.ts and app/api/**/route.js. Exclude app/api/docs/** and app/api/docs.md/** so the generator documents the product API without documenting its own output routes. ``` 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: ```markdown 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: ```markdown ## 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) - [ ] At least 2 workflow examples show how endpoints chain together for real tasks - [ ] The route returns `Content-Type: text/markdown; charset=utf-8` - [ ] The complete documentation is present in the raw response body without client-side JavaScript ``` 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. \*\*Note: 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. \*\*Warning: 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. \*\*Note: 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: ```bash ls .claude/skills/api-docs-generator/ ``` ``` SKILL.md references/ ``` ```bash ls .claude/skills/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 ```bash 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 ```markdown title=".claude/skills/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 app/api/**/route.ts and app/api/**/route.js. Exclude app/api/docs/** and app/api/docs.md/** so the skill does not document its own output routes. 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`. Return the documentation directly in the response body. Do not require client-side JavaScript to construct or fetch it. 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 - [ ] The route returns `Content-Type: text/markdown; charset=utf-8` - [ ] The complete documentation is present in the raw response body without client-side JavaScript ``` ```markdown title=".claude/skills/api-docs-generator/references/doc-patterns.md" # Documentation Patterns for Agent-Friendly APIs These formatting recommendations make API documentation explicit and consistent. They have not each been measured against alternative formats, so prefer accuracy and tested examples over claims about one perfect structure. ## Why agents need different docs Human developers skim docs, infer patterns, and fill in gaps from experience. Agents depend heavily on what the fetched documentation states. Ambiguous parameters and undocumented errors leave room for an incorrect request or recovery step. 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. The code block provides the exact method and path without requiring either value to be inferred from prose. ### 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. The stable columns keep those values aligned for readers and tools. ### 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. Many coding agents can execute curl commands directly. In a Vercel and Ora trace study, 61% of answers containing code included at least one line copied from a fetched page, so every example should be tested. ### 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) ``` --- [Full course index](/academy/llms.txt) ยท [Sitemap](/academy/sitemap.md)