skywalkskills

CatalogueArchitecture & Code Health

D4Ready

API Design & Contract Audit

Compares the API you document with the requests clients already send and the responses the server already returns.

What it examines

  • Endpoints with no contract, or a contract that has drifted
  • Inconsistent names, status codes, and error shapes
  • Fields clients send that the server ignores, and fields the server requires that clients omit
  • Breaking changes between what is deployed and what is described

What you get back

A findings file. Each item has the evidence, how serious it is, and a fix.

Dependencies

  • An AI coding agent that reads SKILL.md files, such as Claude Code, Codex or Gemini CLI
  • Read access to the repository
  • Node.js, to run the analysis tool that ships in the package’s tool folder
  • Optional: an OpenAPI or Swagger file. The audit treats it as the contract. Only JSON is read, so a YAML-only spec shows as present but unparsed. With no spec, that is itself a finding.
  • Optional: a baseline to compare against, either an earlier copy of the spec or a git reference such as the commit before an extraction. Without one, the breaking-change check cannot run.
  • Git, if you use a baseline git reference
  • Python 3 with the jsonschema package, to check findings.json before fixing anything

How it works

The audit is read-only. It scans the code for routes and compares them with your spec, in both directions: code the spec does not know about, and spec entries the code no longer backs.

With a baseline it also reports breaking changes, such as removed routes or changed return types. Run it after a decomposition to see what the extraction broke. It reads old code with git show and never touches your working files.

You get findings.json and findings.md. The remediate skill reads findings.json. Publishing a missing spec from the detected routes is additive and safe, and other changes are proposals you approve.

Setup

  1. Unzip the download and keep the whole folder. Copy its audit and remediate folders into your agent's skills folder (for Claude Code, .claude/skills/) in the repository you want to check.
  2. Confirm Node.js is installed. If you want the breaking-change check, decide the baseline: a spec file or a git reference.
  3. Open the repository in your agent and ask it to run the d4-api-design-contract-audit skill. Tell it which baseline to use.
  4. Check the result with the validator: pip install jsonschema, then python3 path/to/the-unzipped-folder/schema/validate.py findings.json.
  5. Ask your agent to run the d4-api-design-contract-remediate skill using findings.json. Fix some findings and leave the rest open if you like.

Run it with your agent

Copy the prompt, fill in the parts in square brackets, and paste it into your agent.

Audit prompt

Run the d4-api-design-contract-audit skill on this repository. Run the bundled tool with Node.js against this repository. OpenAPI or Swagger file: [path, or none]. Baseline to compare with: [spec file, git reference, or none]. Mode: audit only. Do not change any code. Write findings.json and findings.md in the repository root.

Fix prompt, after you have findings.json

Run the d4-api-design-contract-remediate skill using findings.json. Work through the findings I choose, and leave the rest open.

What is inside

The files that make up this skill, as your agent reads them.

packages/d4-api-design-contract

audit › SKILL.md

Sign in to download

Use the email and password you signed up with.