API Route Debugger skill for Claude and Codex
Finds why a single API route returns the wrong status or error, with an ordered checklist, the exact command to confirm each suspect, and a code patch for the…
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 specific API route returns the wrong status code or an unexpected error and the cause is not obvious from the logs. Do not use for writing a new route from scratch, or reviewing a route that works for style and test coverage. Related topics: coding, api.
What it will ask you for
- HTTP method (choose one: GET, POST, PUT, PATCH, DELETE)
- Route path (free text, e.g. "/api/v1/orders/:id")
- Expected status code (free text, e.g. "200")
- Observed status code and error message (longer free text)
- Sample request payload (longer free text)
- Authentication type (choose one: None, API key, OAuth2, JWT, Session cookie)
- Framework (choose one: Express, FastAPI, Django, Spring, NestJS, Rails, Laravel, Other)
- Route handler code (longer free text)
How it works
- Classify the failure by status code and error text into a layer (routing, middleware, auth, validation, handler, dependency) so the search starts in the right place.
- Write a checklist ordered from cheapest to most expensive to confirm, each item paired with one command or request and the result that rules it in or out.
- Read the handler and middleware against the sample payload and name the most likely root cause with the lines that support it.
- Write the patch as a fenced code block in the framework's idiom, changing only what the diagnosis requires.
- State the exact request to re-run and the response that confirms the route is fixed.
What you get
A Markdown report with sections Overview, Environment, Checklist (ordered, each item with a verification command), Root Cause, and Suggested Fix with a fenced code block and the confirming request.
What it watches out for
- Starting with the handler body when the status code says the request never reached it, such as a 404 from a route registered after a catch-all.
- Proposing a fix without a verification step, so the user cannot tell a real fix from a coincidental pass.
- Ignoring middleware order; a body parser mounted after the route leaves req.body empty and looks like a validation bug.
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.