agentsclimarketplace

Api spec publish

Skill superluminar-io/pinky-promise/skills/api-spec-publish

Invoke when completing a branch where the public API was defined or changed. Commits the draft public API definition to the registry. Typical triggers: branch completion, 'ready to merge', 'done with this feature', or when a draft public API or unresolved versioning decisions are in context.From its SKILL.md

Install
npx -y skills add superluminar-io/pinky-promise --skill api-spec-publish

Assembled 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

5.9 KB, as published. Nobody here has run it

API Spec Publish

Publish a service's API spec to the registry.

When invoked

  • At finishing-a-development-branch when a draft spec or unresolved guardian decisions exist
  • Manually when a producer wants to publish

What to do

Published specs come exclusively from the registry. Never search the local filesystem for existing specs — no find, no directory traversal, no reading .json files from the project tree. Only read registry data from .pinky-promise/registry/ after a fresh clone.

Announce: "Running api-spec-publish to publish the API spec to the registry."

Step 1: Check for a draft spec and bindings

Check for .pinky-promise/draft-spec.json:

cat .pinky-promise/draft-spec.json 2>/dev/null

Check for .pinky-promise/bindings.json:

cat .pinky-promise/bindings.json 2>/dev/null

If draft-spec.json exists, use it as the contract. If bindings.json exists, use it as the bindings.

If neither file exists, look for a draft contract and bindings in the conversation context — produced by api-spec-brainstorming or accumulated through guardian-approved changes.

If no contract is found in either source:

"No draft spec found. Running api-spec-brainstorming first."

Invoke api-spec-brainstorming, then continue.

Step 2: Check for unresolved deferred decisions

Scan the conversation for lines marked "Deferred:" from previous api-change-guardian runs.

If any exist:

"Cannot publish: the following decisions must be resolved first:

  • [deferred decision 1]
  • [deferred decision 2]

For each: proceed with the version bump, or find a backwards-compatible approach?"

Wait for each to be resolved before continuing.

Step 3: Locate API_REGISTRY_REPO

Resolve API_REGISTRY_REPO — use the Read tool, no shell execution:

  • Read .claude/settings.json → check env.API_REGISTRY_REPO
  • Read project CLAUDE.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.

Clone with sparse-checkout to the current service only. Always fetch fresh:

rm -rf .pinky-promise/registry
git clone --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_REPO is not set, or the repo is inaccessible). Cannot publish. Set API_REGISTRY_REPO in .claude/settings.json or project CLAUDE.md — see docs/registry-setup.md."

Stop.

Step 4: Determine the version number

Check whether this service has been published before:

ls .pinky-promise/registry/services/<service-name>/ 2>/dev/null | sort -V | tail -1

First publish: No versions found → version is 1.0.0.

Subsequent publish: Current version is the last result above. Apply the highest bump classification from all guardian decisions recorded in this session (major > minor > patch). If no guardian decisions were recorded, apply a patch bump to the current registry version.

Calculate the new semver:

  • patch: increment third number (1.2.3 → 1.2.4)
  • minor: increment second number, reset third (1.2.3 → 1.3.0)
  • major: increment first number, reset second and third (1.2.3 → 2.0.0)

Use AskUserQuestion (single-select) to confirm:

  • Publish [service-name] as [new-version] ([bump]) — proceed
  • Cancel — stop without publishing

Step 5: Write and publish

Update the version field in the draft contract to <new-version>.

Create the service directory if needed:

mkdir -p .pinky-promise/registry/services/<service-name>

Write the contract file (always include pinkyPromiseVersion: 1):

cat > .pinky-promise/registry/services/<service-name>/<new-version>.json << 'SPEC'
<full contract JSON — no bindings, pinkyPromiseVersion: 1 at top level>
SPEC

If bindings are present, update bindings.json:

  • Minor or patch bump: overwrite bindings.json with the draft bindings.

  • Major bump: read the existing bindings.json from the registry, keep all entries whose contractVersion does not match the new major, then append the new major's entries. This preserves reachability of older versions.

    Ask the user: "This is a major bump to [new-version]. The new binding will be added for [new-major].*. Clients on v[old-major] will continue using the existing binding. Confirm?"

cat > .pinky-promise/registry/services/<service-name>/bindings.json << 'BINDINGS'
<full merged bindings JSON — pinkyPromiseVersion: 1 at top level>
BINDINGS

Commit and push:

cd .pinky-promise/registry
git add services/<service-name>/<new-version>.json
git add services/<service-name>/bindings.json 2>/dev/null || true
git commit -m "<service-name>: <new-version> (<bump>) — <one-line summary>"
git push origin main

The summary describes the most significant change (e.g. "added listUsers operation", "removed deprecated getUser").

Step 6: Announce and clean up

"Published [service-name] v[new-version] to the registry."

rm -rf .pinky-promise/registry
rm -f .pinky-promise/draft-spec.json .pinky-promise/bindings.json

Step 7: Offer follow-up tooling

Use AskUserQuestion (multi-select):

  • Generate mock server — invoke api-mock-server to create a Prism/gRPC stub
  • Generate Pact contract tests — invoke api-pact-generate to create consumer-driven contract tests
  • Nothing, I'm done

Invoke the selected skills in sequence.

Keep looking

Skills are one crate of 610,677. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.