Api contract check
Skill superluminar-io/pinky-promise/skills/api-contract-check
Invoke before finalizing any plan or code that calls another service's public API. Verifies the call matches the published interface contract. Typical triggers: 'this service calls X', 'integrate with Y', 'use Z's API', 'make a request to', code that imports or invokes an external service client.From its SKILL.md
npx -y skills add superluminar-io/pinky-promise --skill api-contract-checkAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 10 stars10 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
6.1 KB, as published. Nobody here has run it
API Contract Check
Validate the current implementation or plan against published API specs.
When invoked
- Before finalizing a plan that calls another service
- During code review of consumer code
- When implementing code that calls an external service
What to do
Specs come exclusively from the registry. Never read another service's code or files — no find, no reading from .. or sibling directories, no inferring the API from .go, .ts, .proto, or any other source files. Only read from .pinky-promise/registry/ after a fresh clone.
Announce: "Running api-contract-check to validate against published API specs."
Step 1: Locate API_REGISTRY_REPO and clone
Resolve API_REGISTRY_REPO — use the Read tool, no shell execution:
- Read
.claude/settings.json→ checkenv.API_REGISTRY_REPO - Read project
CLAUDE.md→ line matchingAPI_REGISTRY_REPO=
If not found in either, $API_REGISTRY_REPO may still be set in the session environment and will be used directly by the clone command below. Only stop if the clone itself fails.
Clone with --filter=blob:none --sparse — no blobs are fetched yet:
rm -rf .pinky-promise/registry
git clone --depth 1 --filter=blob:none --sparse "$API_REGISTRY_REPO" .pinky-promise/registry
If clone fails:
"Registry unreachable or not configured (
API_REGISTRY_REPOis not set, or the repo is inaccessible). Skipping contract check. SetAPI_REGISTRY_REPOin.claude/settings.jsonor projectCLAUDE.md— seedocs/registry-setup.md."
Stop.
Step 2: Read api-dependencies.json
cat api-dependencies.json
If the file does not exist, prompt to create it:
"No api-dependencies.json found. Which services does this project consume?"
List available services using the tree index (no blobs downloaded):
git -C .pinky-promise/registry ls-tree HEAD services/
For each service the user names (resolve partial names against the listing), list available versions and ask which to pin:
git -C .pinky-promise/registry sparse-checkout set "services/<service-name>"
ls .pinky-promise/registry/services/<service-name>/ | sort -V
Write api-dependencies.json to the project root:
{
"<service-name>": "<pinned-version>"
}
Announce: "Created api-dependencies.json. Proceeding with contract check."
Step 3: Fetch pinned specs and bindings
For each entry in api-dependencies.json, sparse-checkout that service (adding to any already checked out):
git -C .pinky-promise/registry sparse-checkout add "services/<service-name>"
If the service directory does not exist after checkout:
"Warning: [service-name] has no entry in the registry. Run
/api-spec-import <url-to-spec>to register it and enable contract checking. Skipping contract check for this service."
Continue to the next dependency.
If the service exists, read the pinned contract:
cat .pinky-promise/registry/services/<service-name>/<pinned-version>.json
Check pinkyPromiseVersion in the contract. If it is higher than 1:
"Warning: [service-name] v[pinned-version] was written by a newer version of pinky-promise (format version [n]). Update the plugin to validate correctly. Skipping contract check for this service."
Continue to the next dependency.
Also read the bindings if present:
cat .pinky-promise/registry/services/<service-name>/bindings.json 2>/dev/null || true
Select the binding entries that apply to the pinned version using this priority order:
- Exact
contractVersionmatch (e.g."1.5.0"for pinned version1.5.0) - Major wildcard match (e.g.
"1.*"for any1.x.y) - Entries with no
contractVersion(fallback)
Use only the selected entries for transport-level validation (HTTP paths, gRPC RPC names, connection URLs).
Also read the consumer's credential mapping if present:
cat .pinky-promise/credentials.json 2>/dev/null || true
If connection.auth is declared in the binding but .pinky-promise/credentials.json has no entry for this service, warn:
"Warning: [service-name] requires
[auth.type]authentication but no credentials are configured. Add an entry for[service-name]to.pinky-promise/credentials.json."
If the file does not exist:
"Error: [service-name] version [pinned-version] not found in registry ([API_REGISTRY_REPO]). Check api-dependencies.json."
rm -rf .pinky-promise/registry
Stop on this error.
Step 4: Validate the implementation
For each pinned spec, check the current implementation or plan:
Operations called:
- Does each called operation exist in the spec?
- Do parameter names match exactly?
- Do parameter types match (string ≠ number, required ≠ optional)?
- Is the return type handled correctly?
Events/subscriptions consumed:
- Does each consumed event/subscription exist in the spec?
- Does the payload handling match the spec type?
Report each violation:
"[service-name] — [member-name]: [description of violation]"
If no violations:
"[service-name] v[pinned-version] — contract check passed."
Step 5: Warn about deprecated usage
For each deprecated member in use:
"Warning: [service-name].[member-name] is deprecated. [deprecated.message][. Sunset planned for v[deprecated.sunsetVersion] if present]."
Step 6: Report available updates
For each pinned service, find the highest version within the same major:
MAJOR=$(echo "<pinned-version>" | cut -d. -f1)
ls .pinky-promise/registry/services/<service-name>/ | sort -V | grep "^${MAJOR}\." | tail -1
If a newer compatible version exists:
"Update available: [service-name] [pinned-version] → [latest-compatible]. New in [latest-compatible]: [list operations/events/subscriptions added since pinned-version, found by comparing the two spec files]."
Clean up
rm -rf .pinky-promise/registry