From pinky-promise
Detects changes to a published API spec and forces a conscious versioning decision before modifying a service's public API. Prevents unversioned breaking changes.
How this skill is triggered — by the user, by Claude, or both
Slash command
/pinky-promise:api-change-guardianThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Detect changes to a published API spec and force a conscious versioning decision.
Detect changes to a published API spec and force a conscious versioning decision.
Any stage (brainstorming, planning, implementation, review) proposes a change that would affect the public API surface of a service with a published spec.
Specs come exclusively from the registry. Never search the local filesystem — no find, no directory traversal, no reading .json files from the project tree. Only read from .pinky-promise/registry/ after a fresh clone.
Announce: "Running api-change-guardian to check for API contract changes."
Infer the service name from the draft spec in context or the project directory name. If ambiguous, ask.
Resolve API_REGISTRY_REPO — use the Read tool, no shell execution:
.claude/settings.json → check env.API_REGISTRY_REPOCLAUDE.md → line matching API_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.
Always fetch fresh — sparse-checkout to only the current service:
rm -rf .pinky-promise/registry
git clone --depth 1 --filter=blob:none --sparse "$API_REGISTRY_REPO" .pinky-promise/registry
git -C .pinky-promise/registry sparse-checkout set "services/<service-name>"
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. Work can continue — changes are unvalidated."
Stop.
ls .pinky-promise/registry/services/<service-name>/ 2>/dev/null | sort -V | tail -1
If no versions exist, this is a new service — no published contract to check.
rm -rf .pinky-promise/registry
Stop.
Read the spec:
cat .pinky-promise/registry/services/<service-name>/<current-version>.json
Check pinkyPromiseVersion. If it is higher than 1:
"This registry entry was written by a newer version of pinky-promise (format version [n]). Update the plugin before proceeding."
Stop.
From the conversation context, determine exactly what is changing:
If only connection URLs, paths, or protocols are changing, these are binding changes — they belong in bindings.json and are not subject to semver. Stop and inform the user:
"This change only affects bindings (connection URLs, paths, or protocols). Update
bindings.jsondirectly — no contract version bump needed."
List each contract change explicitly before classifying.
Apply these rules to each change:
| Change | Classification |
|---|---|
| Remove or change an existing operation, event, subscription, or type | major |
| Add a required field to an existing type | major |
| Add a new operation, event, or subscription | minor |
| Add an optional field to an existing type | minor |
| Deprecate a member | minor |
| Change a description | patch |
The overall classification is the highest across all individual changes (major > minor > patch).
Calculate the new version by applying the bump to <current-version>.
"This change is a [major/minor/patch] change to [service-name] (currently [current-version]).
Changes detected:
- [change 1]
- [change 2]
How would you like to proceed?
- Proceed — bump to [new-version] when publishing
- Find a backwards-compatible approach instead
- Defer this decision"
If proceeding:
"Recorded: [service-name] will bump to [new-version] ([major/minor/patch]) when published."
If finding backwards-compatible approach:
"Understood. Let's find an approach that doesn't require a [major/minor] bump." Collaborate on the alternative before continuing.
If deferring:
"Deferred: [description of change]. This must be resolved before api-spec-publish runs."
Accumulate deferred decisions across multiple guardian runs in the same session. The final version bump at publish time is the highest classification across all resolved decisions.
rm -rf .pinky-promise/registry
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub superluminar-io/pinky-promise --plugin pinky-promise