English | 中文

api-analyzer

A general-purpose Agent Skill that helps backend developers quickly troubleshoot API issues — call chains, exception points, optimization suggestions — all in one report.

When a production incident or test failure hits, tracing a single endpoint typically takes 10-30 minutes of digging through code. This skill wraps that workflow into two commands, targeting 60-90 seconds per report.

Two Commands

Command	Purpose
scan	Analyze the entire project's API landscape: tech stack, endpoint inventory, layering, top risk points
trace <endpoint> <params> <response/error>	Trace a single endpoint: call chain, parameter handling, root cause analysis (P0/P1/P2 severity), optimization suggestions

Usage Examples

scan

trace POST /api/v1/orders body={"amount":100} returns 500 NullPointerException

trace GET /api/users/123 returns empty object but database has data

On platforms with slash commands (e.g. Claude Code): /api-analyzer scan and /api-analyzer trace ....

Natural language also works:

• "What APIs does this project have?" → routes to scan
• "POST /api/orders returns 500, help me debug" → routes to trace

Supported Tech Stacks

Out-of-the-box route recognition for:

• Java: Spring / Spring Boot
• Node: Express, Koa, NestJS, Fastify
• Python: FastAPI, Flask, Django
• Go: Gin, Echo, chi, stdlib net/http
• Rust: actix, axum, rocket
• PHP: Laravel, Symfony
• Ruby: Rails, Sinatra

Other stacks also work with slightly lower recognition accuracy.

What Are Agent Skills

Agent Skills is a reusable AI capability packaging format proposed by Anthropic: a folder + SKILL.md (with frontmatter) + optional support files, using progressive disclosure to save context. This skill fully follows that specification.

Installation

Claude Code (CLI / IDE Extension)

git clone https://github.com/Nuggets1024/api-analyzer.git ~/.claude/skills/api-analyzer

Then in any session:

/api-analyzer scan
/api-analyzer trace POST /api/orders returns 500

Claude API (Skills beta)

Upload the entire api-analyzer/ directory as a skill to your API project. See Claude API Skills docs.

Claude will automatically decide when to activate this skill based on the description field in SKILL.md.

claude.ai (Projects → Skills)

Upload the api-analyzer/ directory in Project settings. The model will automatically recognize and invoke it in other sessions.

Codex CLI (OpenAI)

Codex doesn't have a native skill mechanism yet, but you can use this skill as AGENTS.md:

git clone https://github.com/Nuggets1024/api-analyzer.git
cat api-analyzer/SKILL.md api-analyzer/references/scan.md api-analyzer/references/trace.md > AGENTS.md

Or have Codex read the three files as instructions on demand.

Cursor

Copy contents to .cursor/rules/api-analyzer.mdc (replace Claude's frontmatter with Cursor's rule frontmatter).

Cline / Continue / Others

Any tool that supports injecting system prompts or rules files can import SKILL.md + references/scan.md + references/trace.md as context.

Universal Fallback

If none of the above applies, paste SKILL.md, references/scan.md, and references/trace.md into the conversation and say "Follow this workflow to debug endpoint XXX".

Report Output

After analysis, the skill generates a self-contained HTML report (inline CSS, dark mode support) saved to the current working directory:

• api-analyzer-scan-<YYYYMMDD-HHMMSS>.html
• api-analyzer-trace-<YYYYMMDD-HHMMSS>.html

The conversation only shows the report's absolute path + 1-2 key conclusions. Open the HTML file in a browser for the full report:

• Top metadata bar (report time, project name, working directory, tech stack, symptoms)
• Call chain tree visualization (Controller → Service → Repo / External, with layer labels and colors)
• Exception point P0/P1/P2 severity cards (red/yellow/green borders)
• Endpoint inventory table (HTTP method color badges)
• Optimization suggestions with fix/harden/perf tags

Consider adding api-analyzer-*.html to your project's .gitignore.

Directory Structure

api-analyzer/
├── SKILL.md            # Entry point: command routing + global report spec + speed rules (always loaded)
├── references/
│   ├── scan.md         # scan subcommand: methodology + HTML placeholder spec (loaded on demand)
│   └── trace.md        # trace subcommand: methodology + HTML placeholder spec (loaded on demand)
├── assets/
│   └── templates/
│       ├── scan.html   # scan report HTML template (self-contained CSS)
│       └── trace.html  # trace report HTML template (self-contained CSS)
├── README.md           # This file (English)
├── README.zh-CN.md     # Chinese README
└── LICENSE             # MIT

SKILL.md is the always-loaded entry point (small, always in context). references/scan.md and references/trace.md are loaded only when the corresponding subcommand is invoked. This is the progressive disclosure pattern of Agent Skills — a short description decides whether to activate the skill, while the full methodology loads only when actually needed.

Design Principles

1. Speed > Perfection: Reports may include [speculative] [needs verification] labels rather than slowing down for certainty.
2. Report only, no code changes: The skill never modifies files unless the user explicitly asks after seeing the report.
3. Code locations always use file:line: Directly jumpable.
4. No full indexing: Only reads relevant files; when candidates are too many, filter first then deep-read.
5. Never default to scan: scan is slower than trace; when intent is unclear, always ask.

Report Contents (trace mode)

The generated HTML report includes:

• Top metadata: POST /api/v1/orders + report time / project name / working directory / tech stack / symptoms
• Call chain: Tree visualization, Controller → Service → Repository / External, each node with layer labels
• Parameter handling: Validation rules + DTO mapping relationships
• Key business logic: Listed in execution order, each step with file:line jump link
• Exception analysis: P0 / P1 / P2 severity cards, each with evidence, symptom matching, verification method
• Optimization suggestions: Sorted by ROI, with fix / harden / perf tags
• Uncovered / pending: Areas not explored due to time or missing information

Limitations

• Low recognition rate for highly dynamic route registration (runtime path assembly)
• Cannot trace cross-service / cross-repo call chains (only analyzes current working directory)
• Optimization suggestions are based on static analysis, not a substitute for load testing and production monitoring
• Ultra-large monorepos (>500 endpoints) automatically downgrade to sampling analysis

Contributing

PRs welcome to add:

• New framework route patterns (add a row in references/scan.md's tech stack table)
• New exception symptom → check item mappings (add a row in references/trace.md's symptom table)
• New platform installation instructions (add a section in this README)

All changes are pure markdown — no build or test steps required.

License

MIT