agentleFS
neeraj181-dotneeraj181-dot/ClaudeSkills/.claude/skills/api-doctor/SKILL.md

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

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
  1. Distinctive:

    Read-only by default: Do not modify code during inspection.

    line 15
  2. Distinctive:

    Read manifests, configs, and route definition files.

    line 28
  3. Distinctive:

    Check how errors are handled:

    line 69
  4. Distinctive:

    Verify correct HTTP status codes:

    line 80
  5. Distinctive:

    When authorized to fix:

    line 141
  6. Distinctive:

    Verify the fix by re-tracing the affected flow.

    line 145
  7. Distinctive:

    Run tests if present.

    line 146
  8. Distinctive:

    If a section has no issues, say so in one line.

    line 175

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. Read-only by default. Do not modify code during inspection. Only fix when the user explicitly asks (Phase 11).
  2. 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 Response

At 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:

  1. Fix the root cause, not symptoms.
  2. Make the smallest change that resolves the issue.
  3. Preserve existing behavior for non-broken paths.
  4. Verify the fix by re-tracing the affected flow.
  5. 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 Fixes

For 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.