agentleFS
TyrannicAweTyrannicAwe/claude-skills-pack/skills/api-debugger/SKILL.md

api-debugger

Skill0 starsChanged 3 months agoMITView on GitHub

Systematic API debugging workflow — reproduce with curl, isolate the failing layer, classify the error, and find the root cause with evidence

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    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:

    If auth is sensitive, substitute a test token or read it from an env var — never echo secrets.

    line 15
  2. Distinctive:

    Test in this order, stopping when the layer works:

    line 25
  3. Distinctive:

    Never change code before reproducing with curl — the bug often lives outside the app.

    line 37
  4. Distinctive:

    Never assume a 500 is the app's fault: check reverse proxy, load balancer, and upstream APIs first.

    line 38
  5. Distinctive:

    If two calls differ only in payload, diff the payloads — the answer is usually in a renamed or missing field.

    line 39

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

Debug failing API calls methodically. Never guess — reproduce first, isolate the layer, then fix with evidence.

Step 1 — Reproduce with a minimal curl

  1. Replay the exact failing request with curl: curl -i -X <METHOD> '<url>' -H 'Content-Type: application/json' -H 'Authorization: ...' -d '<body>'
  2. Capture: status code, response headers, response body, timing (-w '\n%{time_total}').
  3. If auth is sensitive, substitute a test token or read it from an env var — never echo secrets.

Step 2 — Classify the error (use the taxonomy)

ClassStatus rangesTypical causes
4xx client400, 401, 403, 404, 409, 422wrong payload shape, bad/expired auth, wrong path, validation, state conflict
5xx server500, 502, 503, 504app crash, upstream failure, gateway timeout, rate limit misconfigured
Networkno response, TLS, DNS, timeoutswrong base URL, proxy, cert, firewall, IPv6 vs IPv4

Step 3 — Isolate the failing layer

Test in this order, stopping when the layer works:

  1. Reachability: curl -i <base_url>/health or any known-good endpoint.
  2. Auth: replay with a freshly issued token; check expiry/issuer/scope.
  3. Payload: validate the body against the documented schema (field names, types, required fields, null vs missing).
  4. Headers: Content-Type, Accept, idempotency keys, required custom headers.
  5. Server: reproduce twice — if flaky, check for rate limits (Retry-After header), upstream dependencies, logs.

Step 4 — Verify the fix

  • Re-run the exact same curl from Step 1 and diff the output.
  • Confirm the status code changed and the response is semantically correct, not just non-error.

Anti-guessing rules

  • Never change code before reproducing with curl — the bug often lives outside the app.
  • Never assume a 500 is the app's fault: check reverse proxy, load balancer, and upstream APIs first.
  • If two calls differ only in payload, diff the payloads — the answer is usually in a renamed or missing field.

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.