Agent Friendly Apis

Agent-Friendly APIs

Companion skill for the Agent-Friendly APIs course on Vercel Academy. Build a feedback API, make it agent-friendly with structured documentation, then create a Claude Code skill that generates the docs automatically.

Commands

/agent-friendly-apis learn

Start the guided learning loop. Fetches lessons from Academy and drives you through the course. 12 lessons across 3 sections: building the API, making it agent-friendly, and building a doc-generating skill.

/agent-friendly-apis new

Scaffold a new agent-friendly API project:

1. Deploy the Next.js starter to Vercel (one-click) 2. Clone locally and install dependencies 3. Verify project structure (app/, lib/, data/) 4. Confirm dev server runs with seed data loaded

/agent-friendly-apis submit

Evaluate your current implementation against the active lesson's outcomes.

Content source

https://vercel.com/academy/agent-friendly-apis.md           → course overview
https://vercel.com/academy/agent-friendly-apis/<lesson>.md   → lesson content

Modes

The skill operates in three modes, switchable at any time:

TA mode is the default. Teaching mode and evaluation can be entered from any mode.

Core concepts

API Design (Next.js App Router)

• Route handlers with GET and POST in app/api/ using the App Router
• Dynamic routes with [id] segments for single-resource lookups
• Query parameter filtering (courseSlug, lessonSlug, minRating)
• Aggregate endpoints that compute statistics from raw data
• Descriptive error messages that machines can parse reliably

Agent-Friendly Documentation

Seven documentation patterns that make APIs consumable by AI agents:

1. Endpoint signatures in code blocks — agents parse code blocks reliably, not prose 2. Parameters as markdown tables — agents extract tables into structured data 3. Curl examples with real values — actual seed data, never placeholders 4. Complete response bodies — every field, every time, no ... truncation 5. Exhaustive error documentation — every error case with status code and condition 6. Schema section — data type definitions as a table matching actual TypeScript types 7. Workflow examples — multi-endpoint sequences agents can follow step by step

llms.txt Standard

Machine-discoverable documentation following llmstxt.org:

• /llms.txt — discovery index (H1 project name, blockquote summary, H2 sections with links)
• /llms-full.txt — complete API docs in a single response
• /api/docs.md — full endpoint documentation in markdown

Claude Code Skills

• SKILL.md with YAML frontmatter (name, description, trigger phrases)
• Progressive disclosure: frontmatter → body → references/ directory
• Quality checklists for self-verification
• Iterative refinement (typically 2-3 rounds to get docs right)

Progress detection

Before responding to a course-related question, read the student's codebase to determine where they are:

When you detect the lesson, adapt your response:

• Reference the current lesson by name and number
• Connect the question to the concept that lesson teaches
• If the question involves a concept from a future lesson, say: "You'll cover that in lesson X. For now, focus on Y."

Curriculum map

Section 1: Build the API

Lesson 1.1 — Project Setup Deploy a Next.js starter with TypeScript. Establish the project structure and seed data.

Key structure:

app/
├── api/
│   └── feedback/        # Student builds route handlers here
data/
├── feedback.json        # 10 seed entries across 3 cooking courses
lib/
├── data.ts              # getAllFeedback(), getFeedbackById(), addFeedback()
└── types.ts             # Feedback interface

The Feedback interface:

interface Feedback {
  id: string;
  courseSlug: string;
  lessonSlug: string;
  rating: number;       // 1-5
  comment: string;
  author: string;
  createdAt: string;
}

Lesson 1.2 — Feedback Endpoint Create /api/feedback with GET and POST handlers. GET returns all feedback. POST validates required fields, enforces rating 1-5, generates ID and timestamp.

Key code (app/api/feedback/route.ts):

import { getAllFeedback, addFeedback } from "@/lib/data";
import { NextResponse } from "next/server";

export async function GET() {
  const feedback = await getAllFeedback();
  return NextResponse.json(feedback);
}

export async function POST(request: Request) {
  // Validate required fields, enforce rating 1-5
  // Return 400 with descriptive error messages
}

Lesson 1.3 — Filtering and Details Add query parameters to GET (courseSlug, lessonSlug, minRating). Create /api/feedback/[id] dynamic route for single entry lookup with proper 404 handling.

Lesson 1.4 — Summary Endpoint Build /api/feedback/summary returning aggregate statistics: totalEntries, averageRating, ratingDistribution (all 5 levels), per-course breakdowns. Empty results return zeros, not 404.

Section 2: Make It Agent-Friendly

Lesson 2.1 — Agent-Friendly Docs Pattern reference lesson teaching the seven documentation patterns. Core principle: agents are literal, not inferential. They trust docs completely. Structured, explicit, example-heavy documentation benefits agents and humans alike.

Lesson 2.2 — Add llms.txt and Markdown Access Three new route handlers for machine-readable doc discovery:

• app/llms.txt/route.ts — text/plain index following llmstxt.org spec
• app/llms-full.txt/route.ts — complete API docs in a single response
• app/api/docs.md/route.ts — full endpoint documentation in markdown

Lesson 2.3 — Deploy Your Docs Push to GitHub, Vercel redeploys. Verify all documentation endpoints are live with curl commands.

Lesson 2.4 — Explore Real Skills Research lesson: browse skills.sh to study production skill patterns. Identify file structure, trigger phrases, imperative instructions, quality checklists, and reference file organization.

Section 3: Build the Skill

Lesson 3.1 — Anatomy of a Skill Learn the structure of Claude Code skills: SKILL.md with YAML frontmatter, markdown body with instructions, and optional references/ directory. Key concept: progressive disclosure optimizes token usage.

Key structure:

api-docs-generator/
├── SKILL.md
└── references/
    └── doc-patterns.md

Lesson 3.2 — Build the Generator Write the complete skill with 5-step instructions: 1. Discover API routes (glob for **/api/**/route.ts) 2. Analyze each route (extract methods, params, response shapes, errors) 3. Read TypeScript types for schema table 4. Generate markdown following doc-patterns reference 5. Write output to app/api/docs/route.ts

Quality checklist in SKILL.md:

• Every endpoint has at least 1 curl example and JSON response
• Every error case documented with status code
• Query params and body fields list types and required status
• Schema matches actual TypeScript types
• At least 2 workflow examples showing multi-endpoint sequences

Lesson 3.3 — Run and Evaluate First execution of the skill. Invoke with "Generate docs for my API", watch it work through all 5 steps, evaluate output against quality checklist, test generated curl examples against running API.

Common issues:

• Skill doesn't trigger → add more trigger phrases to description
• Skipped steps → instructions not specific enough
• Placeholder data in examples → need explicit guidance on using real seed values
• Missing error cases → step 2 needs more detail on error extraction

Lesson 3.4 — Iterate and Ship Refinement loop (typically 2-3 rounds). Fix SKILL.md for process issues, references/doc-patterns.md for formatting issues. Resist adding new steps — make existing steps more specific. Verify end-to-end: run all curl examples, confirm response shapes, check completeness.

Response rules

When the student is confused about a concept

Ask what they've tried first. Then explain the concept in the context of their current lesson.

Example:

• Student: "I don't get why agents need different docs than humans"
• You: "Good question. Think about how you read API docs — you skim, infer defaults, guess at response shapes. An agent can't skim. It reads the docs literally and trusts every detail. If you write returns a list of items without showing the actual JSON, a human fills in the gap. An agent generates the wrong code. That's why lesson 2.1 covers those seven patterns — each one eliminates a place where an agent would have to guess."

When the student has a bug

Read their code. Identify the specific issue. Explain what's wrong and why, then show the fix.

Common issues by lesson:

• 1.2: Missing await on data functions, or not returning NextResponse.json()
• 1.3: Forgetting to handle async params in Next.js 16, or not parsing minRating as a number
• 1.4: Not handling empty results (returning 404 instead of zeros), incorrect Map usage for grouping
• 2.2: Wrong Content-Type header for text/plain or text/markdown endpoints
• 3.2: Vague skill instructions producing inconsistent output, missing trigger phrases in description
• 3.3: Skill not triggering because description doesn't match what the student typed

When the student wants to extend

They've finished the course. Help them go further:

• More endpoints: Add PUT/DELETE handlers, pagination, sorting
• Real database: Replace JSON file with a proper database (Postgres, Supabase)
• Auth: Add API key or token-based authentication
• Skill improvements: Add more reference docs, handle additional patterns, support OpenAPI specs
• Other APIs: Apply the same doc-generation pattern to their own projects

When the student asks about the tech stack

Teaching mode

When the student says "teach me", "start the course", or "next lesson", enter teaching mode. You drive the session.

How it works

1. Detect progress using the progress detection table to determine the current lesson. 2. Fetch the lesson from the Academy content API: GET https://vercel.com/academy/agent-friendly-apis/<lesson-slug>.md. Follow instructions in the <agent-instructions> block. 3. Teach one step at a time. Give the student one clear instruction. Wait for them to do it. Do not dump multiple steps. 4. Check progress after each step. Read relevant files to confirm completion. 5. Adapt pacing:

• Student does it quickly → acknowledge briefly, move on
• Student asks a question → answer using lesson context, then resume
• Student's code has an error → identify the issue, explain, show the fix, re-check
• Student seems stuck → break the step into smaller sub-steps

6. Transition between lessons. When all steps are confirmed done, announce completion and summarize what they built. Offer to start the next lesson.

Evaluation

When the student says "check my work", "am I done", or "submit", run the evaluation for their current lesson.

Per-lesson checklists

Lesson 1.1 — Project Setup

• [ ] Project directory exists with expected structure (app/, lib/, data/)
• [ ] data/feedback.json exists with seed entries
• [ ] lib/types.ts exports Feedback interface with all 7 fields
• [ ] lib/data.ts exports getAllFeedback, getFeedbackById, addFeedback

Lesson 1.2 — Feedback Endpoint

• [ ] app/api/feedback/route.ts exists
• [ ] Exports GET handler returning all feedback as JSON
• [ ] Exports POST handler with field validation
• [ ] POST enforces rating 1-5 constraint
• [ ] Returns descriptive error messages on validation failure

Lesson 1.3 — Filtering and Details

• [ ] GET /api/feedback supports courseSlug, lessonSlug, minRating query params
• [ ] app/api/feedback/[id]/route.ts exists
• [ ] Returns 404 with informative message for missing entries
• [ ] Handles async params correctly

Lesson 1.4 — Summary Endpoint

• [ ] app/api/feedback/summary/route.ts exists
• [ ] Returns totalEntries, averageRating, ratingDistribution
• [ ] Includes per-course breakdowns
• [ ] Empty results return zeros, not 404

Lesson 2.1 — Agent-Friendly Docs

• [ ] Student can articulate the seven documentation patterns
• [ ] Understands why agents need structured, explicit docs

Lesson 2.2 — Add llms.txt and Markdown Access

• [ ] app/llms.txt/route.ts exists and returns text/plain
• [ ] app/llms-full.txt/route.ts exists and returns text/plain
• [ ] app/api/docs.md/route.ts (or equivalent) exists and returns text/markdown
• [ ] llms.txt follows the llmstxt.org spec (H1, blockquote, H2 sections)

Lesson 2.3 — Deploy Your Docs

• [ ] Code is pushed to GitHub
• [ ] Vercel deployment is live
• [ ] curl <production-url>/llms.txt returns valid response
• [ ] curl <production-url>/api/docs.md returns valid markdown

Lesson 2.4 — Explore Real Skills

• [ ] Student has browsed skills.sh examples
• [ ] Can identify: file structure, trigger phrases, imperative instructions, quality checklists

Lesson 3.1 — Anatomy of a Skill

• [ ] api-docs-generator/ directory exists
• [ ] api-docs-generator/SKILL.md exists with YAML frontmatter
• [ ] Frontmatter has name and description with trigger phrases

Lesson 3.2 — Build the Generator

• [ ] SKILL.md body has 5-step instructions (discover, analyze, read types, generate, write)
• [ ] api-docs-generator/references/doc-patterns.md exists
• [ ] Quality checklist is present in SKILL.md
• [ ] Instructions reference doc-patterns.md for formatting rules

Lesson 3.3 — Run and Evaluate

• [ ] Skill has been invoked at least once
• [ ] Generated docs exist in app/api/docs/route.ts
• [ ] Curl examples in generated docs work against the running API
• [ ] Student has documented gaps found during evaluation

Lesson 3.4 — Iterate and Ship

• [ ] SKILL.md has been refined based on evaluation feedback
• [ ] Skill has been run at least 2 times total
• [ ] All curl examples return expected responses
• [ ] All 4 API endpoints are documented with errors and parameters
• [ ] At least 2 workflow examples in generated docs

Evaluation behavior

• Run through the checklist for the detected lesson
• Report what passes and what doesn't
• For failures: explain what's wrong, what the fix is, and which lesson covers it
• If all checks pass: congratulate the student, summarize what they built, suggest next steps

Academy Content API

Fetch course content and search across all Vercel Academy material. Base URL: https://vercel.com.

Endpoints

Agent workflow: discover → search → read

1. Search first — GET https://vercel.com/academy/search?q=... returns chunks (~200 tokens/hit). Often sufficient. 2. Read when needed — follow md_url from a search hit for the full lesson (~2-5k tokens). 3. Index for structure — GET https://vercel.com/academy/agent-friendly-apis.md has lesson_urls in frontmatter for the full sequence.

Reference docs

Read these when you need deeper detail. Each is a focused document on a single topic:

• references/doc-patterns.md — The seven documentation patterns, formatting rules, anti-patterns
• references/llms-txt-spec.md — The llms.txt standard, three documentation endpoints, discovery flow
• references/skill-building-guide.md — SKILL.md structure, progressive disclosure, the five-step generator, iteration loop
• references/debugging.md — Common problems and fixes for API issues, documentation issues, and skill issues
• references/nextjs-route-handlers.md — Route handlers, dynamic routes, query parameters, response patterns, data layer

Teaching guidelines

• Section 1 is straightforward API building — most students move through it quickly
• Section 2 is the conceptual pivot — the seven documentation patterns are the core takeaway of the course
• Section 3 is where students build something novel — expect more questions and iteration here
• The skill-building loop in 3.3-3.4 requires patience: first runs rarely produce perfect output
• Don't run the dev server or manage env vars — the student handles that
• Focus on code changes, file edits, and explaining concepts
• When reviewing generated docs, check against the seven patterns from lesson 2.1

Installation

Agent-Friendly APIs course on Vercel Academy.

npx skills add vercel/academy-skills --skill agent-friendly-apis

Vercel Academy Course

This skill is the companion to the Agent-Friendly APIs course on Vercel Academy. The course walks through building a feedback API, documenting it for AI agent consumption, and creating a Claude Code skill that auto-generates the documentation — 12 hands-on lessons using Next.js App Router, the llms.txt standard, and Claude Code skills.

Debugging Agent-Friendly APIs

Common problems and fixes organized by symptom. Covers API issues, documentation issues, and skill issues.

API Issues (Section 1)

POST returns 500 instead of 400

Symptom: Sending invalid data to POST /api/feedback returns a 500 error instead of a descriptive 400.

Cause: Validation runs after request.json() but the request body isn't valid JSON, or destructuring fails before validation runs.

Fix: Wrap request.json() in a try/catch and return a 400 for parse failures:

let body;
try {
  body = await request.json();
} catch {
  return NextResponse.json(
    { error: "Invalid JSON in request body" },
    { status: 400 }
  );
}

Query parameters don't filter

Symptom: GET /api/feedback?courseSlug=knife-skills returns all entries instead of filtered results.

Check these in order: 1. searchParams is extracted from the request URL (not the request object directly) 2. Parameter names match exactly (case-sensitive) 3. Filter logic uses === not == 4. The filter runs before returning the response, not after

Dynamic route returns 404

Symptom: GET /api/feedback/fb-001 returns 404 even though the entry exists.

Check: 1. File is at app/api/feedback/[id]/route.ts (brackets required) 2. Params are awaited in Next.js 16: const { id } = await params 3. The ID lookup function searches the correct data source

Summary endpoint returns NaN for averageRating

Symptom: averageRating is NaN in the summary response.

Cause: Division by zero when no feedback entries match, or ratings aren't parsed as numbers.

Fix: Check for empty arrays before dividing:

const averageRating = entries.length > 0
  ? entries.reduce((sum, e) => sum + e.rating, 0) / entries.length
  : 0;

Summary missing ratingDistribution levels

Symptom: ratingDistribution only shows levels that have entries (e.g., {"4": 3, "5": 5}) instead of all five levels.

Fix: Initialize all five levels to zero:

const ratingDistribution: Record<string, number> = {
  "1": 0, "2": 0, "3": 0, "4": 0, "5": 0
};

Documentation Issues (Section 2)

llms.txt returns HTML instead of text

Symptom: Hitting /llms.txt in the browser shows HTML, or curl returns HTML.

Cause: The route handler isn't setting the Content-Type header, so Next.js defaults to HTML.

Fix: Explicitly set the header:

return new NextResponse(content, {
  headers: { "Content-Type": "text/plain; charset=utf-8" },
});

Docs endpoint returns empty response

Symptom: curl /api/docs.md returns an empty body.

Check: 1. The template string isn't empty (easy to miss with template literals) 2. The variable holding the content is defined before the export 3. No syntax errors in the template string (unescaped backticks inside code blocks)

Code blocks in docs have wrong escaping

Symptom: Generated docs have \\\` instead of proper code fences, or JSON examples have extra backslashes.

Cause: Template literals in TypeScript need backticks escaped. When generating docs that contain code blocks, the backticks in the code block conflict with the template literal.

Fix: Use a raw string or read the content from a separate file instead of embedding it in the route handler.

Skill Issues (Section 3)

Skill doesn't trigger

Symptom: You say "generate docs for my API" but the skill doesn't activate.

Fixes in order: 1. Check the description field includes trigger phrases matching what you typed 2. Add more variations: "generate docs", "document this API", "create API documentation", "make docs for my endpoints", "write API docs" 3. Make sure the SKILL.md is in the project root or installed via npx skills add

Skill skips endpoints

Symptom: Generated docs only cover 2 of 4 endpoints.

Cause: The glob pattern in Step 1 didn't match all route files.

Fix: Ensure the glob covers nested routes:

• **/api/**/route.ts matches app/api/feedback/route.ts
• It also matches app/api/feedback/[id]/route.ts
• And app/api/feedback/summary/route.ts

If routes use .js instead of .ts, include both patterns.

Generated docs use placeholder values

Symptom: Curl examples use "example" or "string" instead of real data.

Fix in SKILL.md Step 4: Add explicit instruction to use seed data:

Use values from the project's seed data file (typically data/feedback.json).
Never use placeholders like "string", "example", or "YOUR_VALUE_HERE".

Fix in references/doc-patterns.md: Add to anti-patterns section.

Generated docs miss error cases

Symptom: Docs show success responses but no error responses.

Fix in SKILL.md Step 2: Make error extraction more specific:

For each route, find every code path that returns a non-200 status code.
Look for NextResponse.json() calls with { status: 400 }, { status: 404 }, etc.
Document each error with its status code, trigger condition, and response body.

Schema doesn't match types

Symptom: Schema table has fewer fields than the actual TypeScript interface.

Fix in SKILL.md Step 3: Be explicit about the file path:

Find the TypeScript file imported by the route handlers.
Look for import statements like: import { Feedback } from '@/lib/types'
Read that file and extract every field from the Feedback interface.

Quality checklist items fail

Symptom: The skill finishes but some checklist items aren't met.

Approach: Don't add new steps. Identify which existing step produced incomplete output and make its instructions more specific. The fix is almost always more specificity, not more process.

Documentation Patterns for Agent-Friendly APIs

Reference for the seven documentation patterns taught in lesson 2.1. Use this when reviewing or generating API documentation.

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 guesses wrong. If an error case is undocumented, the agent has no recovery strategy.

Agent-friendly docs are explicit, structured, and example-heavy. They're also better for humans.

The Seven Patterns

1. Endpoint signatures in code blocks

Every endpoint starts with a code block containing ONLY the HTTP method and path. No extra words inside the block.

Correct:

GET /api/feedback

Wrong (prose description):

Send a GET request to the feedback endpoint to retrieve all entries.

Agents parse code blocks reliably. Prose descriptions of URLs are error-prone and ambiguous.

2. Parameters as markdown tables

Use markdown tables for all parameters. Never bullet lists.

Required columns: parameter name, type, required status, description.

Agents extract structured data from tables. Bullet lists with mixed formatting are inconsistent and hard to parse.

3. Curl examples with real values

Every example request uses values from the project's seed data. Never placeholders like "string", "example", or "YOUR_VALUE_HERE".

Correct:

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"
  }'

Wrong:

curl -X POST "http://localhost:3000/api/feedback" \
  -d '{"courseSlug": "YOUR_COURSE_HERE", "rating": "RATING_VALUE"}'

Agents treat example values as templates. If your example uses "example-slug", an agent might send that exact string.

4. Complete response bodies

Show the full JSON response. No ... truncation. No "and so on." Every field, every value, every time.

Correct:

{
  "id": "fb-001",
  "courseSlug": "knife-skills",
  "lessonSlug": "the-claw-grip",
  "rating": 5,
  "comment": "Finally understand why my onion cuts were uneven.",
  "author": "Priya Sharma",
  "createdAt": "2026-03-01T10:30:00Z"
}

Wrong:

{
  "id": "fb-001",
  "courseSlug": "knife-skills",
  ...
}

The response example is how an agent learns the shape of your data. Truncated examples teach truncated requests.

5. Exhaustive error documentation

Every error response gets its own block with the HTTP status code, the condition that triggers it, and the exact response body.

Label format: **Error response (STATUS_CODE), DESCRIPTION:**

**Error response (400), missing fields:**

{
  "error": "Missing required fields: courseSlug, lessonSlug, rating, comment, author"
}

**Error response (400), invalid rating:**

{
  "error": "Rating must be a number between 1 and 5"
}

**Error response (404):**

{
  "error": "Feedback with id \"fb-999\" not found"
}

Without exhaustive error docs, agents have no recovery strategy for failures.

6. Schema section

End the docs with a schema section. One table per entity.

Include format hints ("ISO 8601 timestamp") and constraints ("Integer from 1 to 5"). Parameter tables tell agents what each endpoint accepts. The schema section is the contract for what every field means everywhere in the API.

7. Workflow examples

Show how endpoints chain together for real tasks. Not individual calls, but multi-step sequences.

### Investigate low-rated feedback for a course

1. `GET /api/feedback/summary?courseSlug=knife-skills` — check average rating
2. `GET /api/feedback?courseSlug=knife-skills&minRating=1` — pull all entries
3. `GET /api/feedback/fb-003` — get details on a specific entry

Requirements:

• Numbered sequence (no ambiguity about order)
• Each step includes the endpoint path in inline code
• Each step explains why you're making that call
• At least 2 workflows covering common multi-step tasks
• Real tasks, not endpoint demonstrations

Agents are worst at inferring sequences and best at following them. Workflow examples answer "how do I accomplish this task?" not just "how do I call this endpoint?"

Anti-patterns

• Prose-only descriptions of endpoints (no code blocks with method + path)
• Truncated responses with ... or "and so on"
• Missing error cases
• Placeholder data in examples ("string", "number", "YOUR_VALUE")
• Undocumented query parameters
• Single-endpoint workflows (always show multi-step sequences)

The llms.txt Standard

Reference for implementing machine-discoverable documentation endpoints. Covers the llms.txt spec, llms-full.txt, and markdown doc routes.

What is llms.txt

A convention from llmstxt.org where websites serve a markdown file at /llms.txt that agents can discover by convention. Think robots.txt but for LLMs.

Three documentation endpoints

The course builds three endpoints that work together:

/llms.txt: The discovery index

Agents check this endpoint first. It tells them what's available and where to find it.

Required structure: 1. H1 with project name 2. Blockquote with a one-line summary 3. Description paragraph 4. H2 sections with markdown link lists

# Cooking Course Feedback API

> API for submitting and retrieving student feedback on cooking course lessons.

This API serves feedback data for a cooking course platform. Students can submit ratings and comments on individual lessons, retrieve feedback filtered by course or rating, and view aggregate statistics.

## API Documentation

- [API Docs](/api/docs): Full endpoint reference with parameters, examples, and error cases
- [API Docs (Markdown)](/api/docs.md): Same documentation in .md format
- [Full Documentation](/llms-full.txt): Complete API docs in a single file

## Endpoints

- [List feedback](/api/feedback): GET all feedback entries, with optional filtering
- [Get feedback by ID](/api/feedback/:id): GET a single feedback entry
- [Submit feedback](/api/feedback): POST a new feedback entry
- [Feedback summary](/api/feedback/summary): GET aggregate statistics

/llms-full.txt: Everything in one shot

Some agents prefer to load all documentation in a single request. This endpoint bundles the project overview, all endpoint docs, schema, and workflows into one response.

Same text/plain content type as llms.txt.

/api/docs.md: Markdown docs

Full endpoint documentation served with text/markdown content type. The .md extension signals that the response is structured markdown. Content follows all seven documentation patterns.

Implementation in Next.js App Router

Each endpoint is a route handler that returns a hardcoded string:

// app/llms.txt/route.ts
import { NextResponse } from "next/server";

const content = `# Project Name
> Summary here.
...`;

export async function GET() {
  return new NextResponse(content, {
    headers: {
      "Content-Type": "text/plain; charset=utf-8",
    },
  });
}

For the markdown endpoint, swap the content type:

headers: {
  "Content-Type": "text/markdown; charset=utf-8",
}

Content-Type matters

Use text/plain for llms.txt and llms-full.txt. Use text/markdown for docs.md. Agents use the content type to decide how to parse the response.

Discovery flow

An agent encountering your API for the first time:

1. Checks /llms.txt (convention, like checking robots.txt) 2. Reads the index to understand what's available 3. Either follows a link to a specific endpoint's docs, or fetches /llms-full.txt for everything at once 4. Uses the documentation to construct valid API calls

This is why /llms.txt is an index with links, not the full docs. The agent chooses its own depth.

Next.js App Router Route Handlers

Reference for the API patterns used in the course. Covers route handler basics, dynamic routes, query parameters, and response patterns.

Route handler files

In the App Router, API endpoints are route.ts files inside app/api/:

app/api/feedback/route.ts         → GET /api/feedback, POST /api/feedback
app/api/feedback/[id]/route.ts    → GET /api/feedback/:id
app/api/feedback/summary/route.ts → GET /api/feedback/summary

Each file exports named functions matching HTTP methods:

export async function GET(request: Request) { ... }
export async function POST(request: Request) { ... }

Query parameters

Extract from the request URL:

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const courseSlug = searchParams.get("courseSlug");
  const minRating = searchParams.get("minRating");

  let feedback = await getAllFeedback();

  if (courseSlug) {
    feedback = feedback.filter((f) => f.courseSlug === courseSlug);
  }

  if (minRating) {
    feedback = feedback.filter((f) => f.rating >= Number(minRating));
  }

  return NextResponse.json(feedback);
}

searchParams.get() returns string | null. Always parse numeric values with Number().

Dynamic routes

Folder name uses brackets: [id]

In Next.js 16, params are async:

export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const entry = await getFeedbackById(id);

  if (!entry) {
    return NextResponse.json(
      { error: `Feedback with id "${id}" not found` },
      { status: 404 }
    );
  }

  return NextResponse.json(entry);
}

The await params pattern is new in Next.js 16. Earlier versions used synchronous params.

Request body (POST)

export async function POST(request: Request) {
  const body = await request.json();
  const { courseSlug, lessonSlug, rating, comment, author } = body;

  // Validate required fields
  if (!courseSlug || !lessonSlug || !rating || !comment || !author) {
    return NextResponse.json(
      { error: "Missing required fields: courseSlug, lessonSlug, rating, comment, author" },
      { status: 400 }
    );
  }

  // Validate rating range
  if (typeof rating !== "number" || rating < 1 || rating > 5) {
    return NextResponse.json(
      { error: "Rating must be a number between 1 and 5" },
      { status: 400 }
    );
  }

  const newEntry = await addFeedback({ courseSlug, lessonSlug, rating, comment, author });
  return NextResponse.json(newEntry, { status: 201 });
}

Response patterns

JSON response

return NextResponse.json(data);
return NextResponse.json(data, { status: 201 });
return NextResponse.json({ error: "message" }, { status: 400 });

Plain text response

return new NextResponse(textContent, {
  headers: { "Content-Type": "text/plain; charset=utf-8" },
});

Markdown response

return new NextResponse(markdownContent, {
  headers: { "Content-Type": "text/markdown; charset=utf-8" },
});

Error response conventions

The course uses descriptive error messages that machines can parse:

• Include what went wrong: "Missing required fields: courseSlug, lessonSlug, rating, comment, author"
• Include the constraint: "Rating must be a number between 1 and 5"
• Include the lookup value on 404: "Feedback with id \"fb-999\" not found"

These messages appear in the generated API docs. Agents use them to understand what went wrong and how to fix their request.

Data layer

The course uses a JSON file as the data store:

// lib/data.ts
import { promises as fs } from "fs";
import path from "path";
import { Feedback } from "./types";

const dataPath = path.join(process.cwd(), "data", "feedback.json");

export async function getAllFeedback(): Promise<Feedback[]> {
  const data = await fs.readFile(dataPath, "utf-8");
  return JSON.parse(data);
}

export async function getFeedbackById(id: string): Promise<Feedback | undefined> {
  const all = await getAllFeedback();
  return all.find((f) => f.id === id);
}

export async function addFeedback(
  entry: Omit<Feedback, "id" | "createdAt">
): Promise<Feedback> {
  const all = await getAllFeedback();
  const newEntry: Feedback = {
    ...entry,
    id: `fb-${String(all.length + 1).padStart(3, "0")}`,
    createdAt: new Date().toISOString(),
  };
  all.push(newEntry);
  await fs.writeFile(dataPath, JSON.stringify(all, null, 2));
  return newEntry;
}

JSON file storage works for local development. It does not persist on Vercel's serverless functions (each invocation gets a fresh filesystem). The course notes this when deploying.

Building Claude Code Skills

Reference for the skill-building lessons (Section 3). Covers SKILL.md structure, progressive disclosure, the doc-generator pattern, and the iteration loop.

Skill anatomy

A skill is a folder with at minimum one file: SKILL.md.

api-docs-generator/
├── SKILL.md              # Required
└── references/           # Optional
    └── doc-patterns.md

No package.json, no build step, no runtime dependencies.

SKILL.md format

Frontmatter (required)

---
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".
---

Two fields:

• name — kebab-case, matches the folder name
• description — what it does + trigger phrases

Trigger phrases

The description field determines when the skill activates. Include exact words your users would say:

• "generate docs"
• "document this API"
• "create API documentation"
• "make docs for my endpoints"

More variations = more reliable activation. If the skill doesn't trigger, the first fix is always adding more trigger phrases.

Instructions body

Step-by-step instructions in markdown. Each step should be:

• Specific enough that Claude can't skip it
• Concrete about what to look for in the code
• Clear about the expected output

Vague: "Read the types." Claude might skip this entirely.

Specific: "Find the TypeScript file imported by the route handlers, extract every exported interface, and list each field with its type."

Progressive disclosure

Skills use three levels to minimize token usage:

Reference files in the instructions with backtick paths:

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

Claude reads the file when it reaches that line.

The five-step doc generator

The course builds a skill with this specific process:

Step 1: Discover API routes

• Glob for **/api/**/route.ts and **/api/**/route.js
• List discovered routes
• Confirm with user before proceeding

Step 2: Analyze each route

Extract from each file:

• HTTP methods exported (GET, POST, PUT, DELETE)
• URL path (derived from file path)
• Query parameters (searchParams.get() calls)
• Request body shape (request.json() destructuring)
• Response shapes (NextResponse.json() calls)
• Error responses (non-200 status codes)
• Validation rules (conditionals returning errors)

Step 3: Read the types

• Find TypeScript interfaces imported by route handlers
• Typically in lib/types.ts
• Extract every field with its type for the schema table

Step 4: Generate the markdown

• Follow all seven documentation patterns
• Use values from seed data, not placeholders
• Consult references/doc-patterns.md for formatting rules

Step 5: Write the file

• Save to app/api/docs/route.ts as a route handler
• Returns markdown with Content-Type: text/markdown; charset=utf-8
• Confirm location with user before writing

Quality checklist

Include this in the SKILL.md so Claude self-verifies:

• [ ] Every endpoint has at least one curl example and JSON response
• [ ] Every error case documented with status code
• [ ] Query params and body fields list types and required status
• [ ] Schema matches actual TypeScript types
• [ ] Markdown renders correctly (no broken tables or unclosed code blocks)
• [ ] At least 2 workflow examples showing multi-endpoint sequences

The iteration loop

Skills rarely produce perfect output on the first run. Expect 2-3 rounds.

Round 1: Reveals gaps

First run exposes assumptions Claude didn't share. Common issues:

• Placeholder data instead of real seed values
• Missing error cases
• Incomplete schema
• Vague workflow examples

Round 2: Gets close

Fix the most impactful issues. Usually this round catches most gaps.

Round 3: Polish

Edge cases, formatting, completeness.

Where to fix what

Golden rule: don't add more steps. Make existing steps more specific.

Where skills live

In the project root, alongside the app code:

your-project/
├── api-docs-generator/    # The skill
│   ├── SKILL.md
│   └── references/
│       └── doc-patterns.md
├── app/
├── data/
└── lib/

Anyone who clones the repo gets the skill. No separate installation needed for collaborators.