About validate-api
validate-api is a testing skill for checking API behavior against a running server, including response shapes and persistent side effects. It turns acceptance criteria into live requests, records results, fixes failures, and promotes checks to durable tests.
Key features
- 01Start server and record run instructions
- 02Translate criteria into concrete requests
- 03Check status, response shape, and side effects
- 04Verify persistence across reads or restarts
- 05Fix failures and add regression tests
- 06Commit requirement-tagged durable tests
Use cases
- 01Validate an API change against acceptance criteria
- 02Check edge cases and persisted data on a live server
- 03Turn manual API checks into repeatable tests
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/validate-apiin Claude Code to confirm it loaded.
Bundled fileseval.json
Details
From the project READMEAcceptance — API
Exercise the running server the way a real client will. A unit test passes against the code's own assumptions; this proves the wire behavior — the status codes, the JSON shape, the side effects that survive a reload.
Invoked by validate-feature with a slice of the acceptance ledger — or run
directly against an API change, in which case first derive the checklist from the
change's acceptance criteria (the spec, or the endpoints touched). Either way,
work through the items in order.
1. Get the server running — and persist how
Read docs/agents/project.md for a Run locally (dev) entry. If it exists,
start the backend with that command. If it does not: discover the command from
the repo (Cargo bins / tauri / package.json scripts / Makefile), start the
server, confirm it answers (a health route, or the first checklist request
returning anything), then WRITE the command and its ready-signal into project.md
under ## Run locally (dev). Done when: the server answers a request AND the
start command is recorded in project.md.
Preconditions — auth, data, environment. If any endpoint needs
authentication (a token, a seeded test account), fixture/seed data, or
environment configuration (env vars, a test database), discover how the repo
provides them and record it in project.md alongside the run command. An
acceptance run that stalls on a 401 or an empty database is testing the
harness, not the feature — resolve the precondition and note it, rather than
marking the item unverifiable.
API standards doc (optional)
Applicability: checklist items are HTTP/RPC APIs. Load:
skills/project/define-system-doc/consult-recipe.md. Path: docs/standards/api.md.
Consult when Approved; no-op when absent; suggest once /define-system-doc standards/api
if the gap is material; never auto-invoke.
2. Turn each checklist item into a real request
For each API item in the ledger, write the concrete request a client sends — method, path, headers, body — and its expected response: status, the body fields (names, casing, id type), and any side effect. Cover the edge criteria explicitly: empty/whitespace field → the documented error, unknown id → the documented status, malformed body, repeated calls.
3. Exercise against the live server
Send each request (curl / http / a script) and assert the FULL expectation,
not just a 2xx: status, body shape, and — where the criterion says "persists" —
read it back with a fresh GET; where it says "across restart", restart the
server and read again. Record actual-vs-expected in the ledger for every item.
Done when: every API item has an observed result.
4. Fix what breaks
REQUIRED SUB-SKILL: use root-cause — the failing request is already your
red-capable loop. Fix the root cause, add the regression test, re-run the item.
5. Promote to a durable test
Turn the exercised requests into a committed test that hits the server (or the
handler at its real seam), tagged with the requirement ID per the conventions in
docs/agents/project.md, so it joins the verify suite and guards the behavior
after this run. Done when: the durable test is committed, tagged, and green.