Next.js API Route Formatter skill for Claude and Codex
Delivers a TypeScript Next.js API route with typed query parameters, body, and response, plus a short fetch example the frontend can copy, so both sides of…
Install it once and Claude or Codex runs it for you. When your request matches, your AI loads the skill, asks for anything it is missing, and works through the template itself. Prefer to fill it in by hand? See the full prompt template.
Download the skill (.zip) · View SKILL.md
When it is used
Use when a TypeScript API route needs its query parameters, body, and response typed and exported so the frontend can import the types and call it correctly. Do not use for routes with zod and session middleware composition, or plain JavaScript routes. Related topics: coding, next.js.
What it will ask you for
- HTTP method (choose one: GET, POST, PUT, DELETE, PATCH)
- Route path (free text, e.g. "/api/example")
- Description (longer free text)
- Query parameters (optional) (longer free text)
- Request body schema (for POST or PUT or PATCH) (longer free text)
- Authentication required (choose one: Yes, No)
- Response shape (longer free text)
How it works
- Define and export the Query, RequestBody, and Response types from the spec so the handler and the frontend share them.
- Parse req.query into the Query type with explicit coercion and answer 400 for missing or malformed required parameters.
- Add the 405 method guard and, when required, the 401 auth check before any parsing.
- Implement the handler typed as NextApiHandler of the Response type with a comment marking each section.
- Write the typed fetch usage example that imports the exported types and handles the error statuses, then output both blocks.
What you get
Two blocks: the complete route file as a code block tagged ts with exported types and a commented handler, then a short markdown usage example with a typed fetch call.
What it watches out for
- Treating req.query values as numbers or booleans when Next.js always delivers strings or string arrays.
- Keeping the types private to the route file, which forces the frontend to retype them and drift.
- Returning a different shape on error than the Response type declares without widening the handler type.
How to install
Claude.ai and the Claude desktop app
- Download the skill .zip.
- Open Settings, then Capabilities, and find Skills.
- Choose Upload skill and select the .zip.
- Ask Claude for help with the task. It loads the skill when your request matches.
Claude Code
- Download the skill .zip.
- Unzip it into ~/.claude/skills/ (or .claude/skills/ inside a project).
- Start a new session. Claude Code loads the skill when your request matches.
Codex
- Download the skill .zip.
- Unzip it into ~/.agents/skills/ (or .agents/skills/ inside a project).
- Codex picks it up on its own. Type $ and the skill name to use it, or just ask for the task.
Cursor
- Download the Cursor rule (.mdc).
- Save it in .cursor/rules/ inside your project.
- Cursor's agent applies the rule when your request matches its description.
AGENTS.md (Codex, Cursor, and other coding agents)
- Copy the AGENTS.md section.
- Paste it into AGENTS.md at the root of your repository, creating the file if needed.
- Coding agents that read AGENTS.md follow it when your request fits.