---
title: "Run and Evaluate"
description: "Run the API docs generator skill for the first time in Claude Code. Watch it discover routes, generate markdown docs, and create the /api/docs endpoint. Then evaluate the output against the quality checklist and test the generated curl examples."
canonical_url: "https://vercel.com/academy/agent-friendly-apis/run-and-evaluate"
md_url: "https://vercel.com/academy/agent-friendly-apis/run-and-evaluate.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-08-26T21:03:36.596Z"
content_type: "lesson"
course: "agent-friendly-apis"
course_title: "Agent-Friendly APIs"
prerequisites:  []
---

<agent-instructions>
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.
</agent-instructions>

# Run and Evaluate

# Run and Evaluate

The instructions are ready for a first run.

Evaluate the skill by the documentation it produces. A first run reveals instructions that seemed clear to you but left room for Claude to interpret them differently.

## 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. Run `/skills` and confirm that `api-docs-generator` appears from `.claude/skills/api-docs-generator/`.

Invoke it directly first:

```
/api-docs-generator
```

Then 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 the three feedback route files while excluding `/api/docs` and `/api/docs.md`?
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?

The starter's `/api/docs` route contains placeholder content. The skill should read the route handlers, generate the Markdown, and replace that stub with a working documentation route.

\*\*Note: What the skill creates\*\*

When the skill finishes, `app/api/docs/route.ts` should contain a route handler that returns the API documentation as Markdown. Claude creates it by following your SKILL.md instructions.

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

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?

Use the first run to identify which requirements Claude followed and where the output drifted.

### Testing the generated docs

Start your dev server and hit the generated endpoint:

```bash
curl -i http://localhost:3000/api/docs
```

The response should be `200` with `Content-Type: text/markdown; charset=utf-8`, followed by structured Markdown with all four endpoints documented. Now pick a few curl examples from the generated docs and run them:

```bash
# 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 appear.** Run `/skills` to verify discovery and check that the file is exactly `.claude/skills/api-docs-generator/SKILL.md`. If direct invocation works but a natural-language request does not, add that request wording to the description.

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

\*\*Note: Take notes on what needs fixing\*\*

Record each issue you find, such as a missing error case, incorrect curl syntax, truncated response, or placeholder value. The next lesson uses this list to refine the instructions.

## Commit

```bash
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 the three feedback route files and excludes the documentation routes
- [ ] The skill creates `app/api/docs/route.ts` (you didn't write it by hand)
- [ ] `curl -i http://localhost:3000/api/docs` returns 200, the Markdown content type, and the complete documentation body
- [ ] You've run the quality checklist and noted any gaps
- [ ] You've tested at least three curl examples from the generated docs


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)