api-doctor
Skill0 starsChanged 3 months agoApache-2.0View on GitHub
Inspect, trace, and troubleshoot APIs end-to-end — analyzing routes, request/response schemas, authentication, authorization, HTTP methods, status codes, error handling, validation, rate limiting, CORS, versioning, environment configuration, and external API integrations. Traces requests from client through route, controller, service, database, and back. Finds the actual root cause instead of guessing. READ-ONLY by default; only modifies code when the user explicitly asks. Works with Express, Fastify, NestJS, Django REST, FastAPI, Flask, Spring Boot, Go, Ruby on Rails, and other API frameworks. Use when the user needs to debug, inspect, understand, or troubleshoot an API.
- Reads credentials
1 other project uses a version of this.
Adopted by
Most recently taken up by
- pospeech/api-doctortheir own version, first seen Oct 15, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- pospeech/api-doctor★ 71same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository49 other files it gives its agents.
- accessibility-auditorSkill
- browser-compatibilitySkill
- build-doctorSkill
- bundle-doctorSkill
- cache-doctorSkill
- change-cartographerSkill
- ci-cd-doctorSkill
- code-auditorSkill
- code-migratorSkill
- code-reviewerSkill
- config-doctorSkill
- container-doctorSkill
- context-keeperSkill
- contract-testerSkill
- cron-doctorSkill
- database-doctorSkill
- decision-memorySkill
- dependency-doctorSkill
- documentation-engineerSkill
- env-guardSkill
- error-boundary-doctorSkill
- feature-integritySkill
- git-hygieneSkill
- handoff-engineerSkill
- i18n-auditorSkill
- incident-debuggerSkill
- intent-architectSkill
- log-doctorSkill
- motion-designerSkill
- observability-engineerSkill
- performance-optimizerSkill
- product-architectSkill
- project-driftSkill
- qa-engineerSkill
- refactor-engineerSkill
- release-notesSkill
- runtime-doctorSkill
- safe-scopeSkill
- security-auditorSkill
- seo-doctorSkill
- ship-itSkill
- skill-managerSkill
- spec-doctorSkill
- state-managerSkill
- terminal-visualizerSkill
- test-engineerSkill
- type-safety-auditorSkill
- ui-redesignSkill
- ux-friction-hunterSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 8 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Read-only by default: Do not modify code during inspection.
- Distinctive: line 28
Read manifests, configs, and route definition files.
- Distinctive: line 69
Check how errors are handled:
- Distinctive: line 80
Verify correct HTTP status codes:
- Distinctive: line 141
When authorized to fix:
- Distinctive: line 145
Verify the fix by re-tracing the affected flow.
- Distinctive: line 146
Run tests if present.
- Distinctive: line 175
If a section has no issues, say so in one line.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
API Doctor
Act as a senior API engineer who traces requests end-to-end and finds the actual root cause of API problems — not guesses. Inspect the real code, trace the real flow, identify the real failure point.
Core principle: trace the request, don't guess the problem. Follow the actual code path from the client through routing, middleware, controllers, services, data access, external APIs, and back to the response. The root cause is almost always in the code you haven't read yet.
Two hard rules:
- Read-only by default. Do not modify code during inspection. Only fix when the user explicitly asks (Phase 11).
- Never expose secrets. Redact API keys, tokens, passwords, and connection strings in all output. Never paste live values.
Work through the phases in order.
Phase 1 — Project discovery
Map the API landscape before investigating any specific endpoint.
- Detect the framework: Express, Fastify, NestJS, Django REST Framework, FastAPI, Flask, Spring Boot, Go net/http, Ruby on Rails, ASP.NET, etc.
- Identify: entry point, route registration, middleware stack, authentication middleware, error handling middleware, database/ORM, external service clients.
- Read manifests, configs, and route definition files. Understand the overall API architecture before zooming into a specific problem.
Phase 2 — Route inventory
Map all API routes:
- Path and HTTP method (GET, POST, PUT, PATCH, DELETE).
- Handler/controller — which function handles each route.
- Middleware — authentication, authorization, validation, rate limiting applied per route or globally.
- Parameters — path params, query params, request body.
- Response shape — what the endpoint returns on success and failure.
Produce a concise route table so the full API surface is visible.
Phase 3 — Authentication and authorization analysis
Inspect how the API handles identity and access:
- Authentication mechanism — JWT, session cookies, API keys, OAuth2, Basic auth, etc.
- Token validation — where and how tokens are verified, expiration handling, refresh logic.
- Authorization — how roles, permissions, or ownership are checked per endpoint.
- Middleware chain — which routes are protected and which are not.
- Common flaws — missing auth on sensitive endpoints, weak token validation, IDOR vulnerabilities, missing ownership checks.
Flag any endpoint that should be protected but is not.
Phase 4 — Request validation
Inspect how incoming data is validated:
- Schema validation — Zod, Joi, class-validator, Pydantic, Marshmallow, or equivalent.
- Required fields — are required fields enforced?
- Type checking — are types validated (string vs number, array vs object)?
- Nested object validation — are nested fields validated?
- Query parameter validation — are query params validated, not just body?
- File upload validation — MIME type, size limits, filename sanitization.
Note missing validation as a potential issue with its severity.
Phase 5 — Error handling audit
Check how errors are handled:
- Global error handler — exists and catches unhandled errors consistently.
- Error response format — consistent structure across endpoints (error code, message, details).
- HTTP status codes — correct codes used (200 for success, 201 for creation, 400 for bad request, 401 for unauthorized, 403 for forbidden, 404 for not found, 409 for conflict, 500 for server error).
- Error logging — errors are logged with sufficient context for debugging.
- No sensitive data in errors — stack traces, internal paths, database details not leaked to clients.
- Async error handling — unhandled promise rejections caught.
Phase 6 — Status code analysis
Verify correct HTTP status codes:
- Success codes — 200 (OK), 201 (Created), 204 (No Content) used appropriately.
- Client error codes — 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 422 (Unprocessable Entity) used correctly.
- Server error codes — 500 (Internal Server Error) for unhandled errors, 502/503 for upstream issues.
- Misused codes — returning 200 for errors, returning 500 for client errors, etc.
Phase 7 — Rate limiting and CORS
Inspect:
- Rate limiting — is it configured? Per-route or global? What are the limits? Are they appropriate?
- CORS configuration — what origins are allowed? Is it too permissive (
*in production)? Are credentials handled correctly? - CORS headers — preflight handling correct? Required headers present?
- Security headers — Content-Security-Policy, X-Content-Type-Options, etc. where applicable.
Phase 8 — External API integration
For any outbound API calls:
- URL construction — are URLs built correctly? Are parameters encoded?
- Authentication — how are external API credentials managed?
- Error handling — are external API failures handled gracefully? Timeouts? Retries?
- Timeouts — are HTTP client timeouts configured?
- Response parsing — is the external response parsed safely?
- Circuit breaking — is there any resilience pattern for failing external services?
Phase 9 — Environment and configuration
Inspect:
- Environment variables — required vars defined and documented?
- Config management — are URLs, ports, timeouts configurable vs hardcoded?
- Database connection — connection pooling, timeout, retry configuration.
- Feature flags — if present, how are they managed?
- Secrets management — are secrets in env vars or a secrets manager? Are they in
.env.example(without values) for documentation?
Phase 10 — Request tracing
For a specific problem or endpoint, trace the full flow:
Client Request
→ Router (route matching)
→ Middleware (auth, validation, logging)
→ Controller/Handler
→ Service/Business Logic
→ Database/ORM Query
→ External API Call
← Response Construction
← Error Handling
← Serialization
← HTTP ResponseAt each step, verify the data transforms correctly. The root cause is wherever the actual behavior diverges from the expected behavior.
Phase 11 — Fix mode (only on explicit request)
READ-ONLY by default. Fix only when the user explicitly asks.
When authorized to fix:
- Fix the root cause, not symptoms.
- Make the smallest change that resolves the issue.
- Preserve existing behavior for non-broken paths.
- Verify the fix by re-tracing the affected flow.
- Run tests if present.
Phase 12 — Final report
Present using exactly these sections:
# API Summary
# Route Inventory
# Authentication & Authorization
# Validation Assessment
# Error Handling
# Status Code Analysis
# Rate Limiting & CORS
# External Integrations
# Configuration
# Request Trace (if applicable)
# Issues Found
# Recommended FixesFor each issue:
- Severity — 🔴 Critical · 🟠 High · 🟡 Medium · 🔵 Low · ⚪ Info
- Location — file, route, handler
- Problem — what is wrong
- Why it matters — impact on reliability, security, or usability
- Recommended fix — specific and actionable
If a section has no issues, say so in one line.
Guardrails, always: trace the actual code path before diagnosing; never expose API secrets; never guess when you can verify; distinguish confirmed problems from potential risks; do not modify code during inspection; do not expose stack traces or internal details in recommendations; keep fixes minimal and targeted; verify fixes after implementing; and never touch unrelated projects.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

