agent-friendly-apis

これはレビュー時に保存された抜粋です。完全で最新の内容は外部ソースを確認してください。

---
name: agent-friendly-apis
description: >-
  Companion skill for the Agent-Friendly APIs course on Vercel Academy.
  Use when the user mentions "agent-friendly APIs", "API documentation",
  "llms.txt", "the course", "teach me", or asks about agent-friendly docs,
  documentation patterns, or building Claude Code skills in the context
  of the Academy course.
user-invocable: true
---

# Agent-Friendly APIs

Companion skill for the [Agent-Friendly APIs](https://vercel.com/academy/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:

| Mode | Trigger | Behavior |
|------|---------|----------|
| **TA** | Any question (default) | Reactive help — detect progress, answer questions, point to relevant docs |
| **Teaching** | "teach me", "start the course", "next lesson" | Proactive — fetch lesson content, prompt step by step, check progress |
| **Evaluation** | "check my work", "am I done", "submit" | Run lesson-specific checks against the student's codebase, report pass/fail |

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](https://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:

| Check | How | Lesson |
|-------|-----|--------|
| No `app/api/feedback/route.ts` | File does