When to use this
- An API has a published schema (OpenAPI, GraphQL SDL, protobuf) and the implementation needs checking against it.
- Before publishing/updating an API spec, to confirm it matches what the code actually does.
- Not for designing a new contract from scratch -- this validates an existing implementation against an existing or proposed spec.
The skill file
Copy this verbatim. It's written in the SKILL.md format (YAML frontmatter + markdown instructions) that Claude Code, and increasingly other agent tools, read directly.
--- name: api-contract-validator description: Check that an API implementation actually matches its published contract (OpenAPI spec, GraphQL schema, protobuf definition) -- field types, required vs. optional, status codes, error shapes -- not just that manual happy-path testing works. Use when a schema exists or is being updated. --- # API Contract Validator A schema that doesn't match the implementation is worse than no schema -- consumers will generate clients against it and break at runtime. ## What to cross-check - **Every field's type**: does the implementation actually return/accept the type the schema declares (string vs. number, nullable vs. not)? - **Required vs. optional**: does the implementation always populate fields the schema marks required? Does it reject requests missing a schema-required field, or silently accept and misbehave? - **Enums**: does the implementation only ever produce/accept the exact set of values the schema's enum declares -- including checking for a value the code can produce that isn't in the schema's enum at all. - **Status codes and error shapes**: does every status code the implementation can actually return appear in the schema, with a matching response body shape? - **Pagination/array semantics**: if the schema declares a paginated response, does the implementation's pagination actually match (cursor vs. offset, field names)? ## Process 1. Walk the schema field by field, endpoint by endpoint. 2. For each, find the corresponding implementation code and confirm the match, not just skim for a plausible-looking name match. 3. Flag every mismatch, however small -- a client generated from the schema will trust it exactly. ## Output List of mismatches (schema says X, implementation does Y), each with whether the fix should be to the schema or the implementation (which is correct depends on which reflects the actually-intended contract).
Installing it elsewhere
The frontmatter/body split above is Claude Code's convention. Here's how to carry the same instructions into other tools:
Save the file below verbatim (frontmatter included) at that path, project-local or in ~/.claude/skills/ for a user-level skill. Claude Code loads the name/description pair to decide when to pull it in, or you invoke it directly as /api-contract-validator.
Convert the YAML frontmatter to Cursor's rule format (description, globs, alwaysApply: false) and keep the markdown body as the rule content. Cursor surfaces it by description match, same idea as Claude Code's auto-load.
Codex CLI (and increasingly other agentic CLIs) read AGENTS.md at the repo root as always-on instructions. Paste the markdown body under a heading like ## {title}; for GitHub Copilot's coding agent, the equivalent file is .github/copilot-instructions.md.
Append the markdown body to .windsurfrules at the repo root. Windsurf treats the whole file as always-on context, so keep only the instructions you want applied on every request.
- Checking only the happy-path response shape and missing that an error case returns a status code or body shape not in the schema.
- Assuming a schema is correct just because it exists, without verifying it against current implementation behavior.
- Missing an enum value the implementation can produce that isn't declared in the schema, which breaks strict client-side validation.