Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →hashgraph-online/contract-version-bump
Use this skill when changing a machine-readable contract — a JSON Schema, an API spec, or a config schema — and bumping its version: tightening a constraint, adding/removing/renaming a field, introducing a breaking change, raising an API version, or writing the changelog entry for a schema change. Trigger on "change the schema", "tighten this constraint", "bump the schema version", "breaking change to the API", "new API version", "changelog entry for a schema change". Runs six phases — classify
Passed 15 of 19 test cases with the skill, and 10 of 19 without it.
and 4 more in the full report
6 fixed11 passed either way4 still failing1 broke
Tokens, turns and time describe resource use, not a dollar price.
One of 6 test cases the skill fixed. Same model, same prompt, with and without the skill.
I am updating `docs/spec/inventory.schema.json` to fix a typo in a field's description text and clarify a field explanation. No schema constraints, validation rules, field names, or types are being changed. Do I need to perform a contract version bump on this schema?
| Checked | Without skill | With skill |
|---|---|---|
| State that pure documentation typo fixes and description clarifications do not require a contract version bump | Passed | Passed |
| Confirm that no schema version increment or contract bump workflow is needed for this edit | Missed | Passed |
The instructions your model reads when the skill loads.
Project-instruction file resolution:
CLAUDE.mdandAGENTS.md(Codex CLI) are transparent aliases — see skills/_shared/instruction-file-resolution.md. Every reference toCLAUDE.mdin this skill resolves via that precedence rule.
A version bump on a machine-readable contract (JSON Schema, OpenAPI/API spec, config schema) is not just "increment the number." Three failure modes recur and are each individually non-obvious enough that a careful agent still misses them without a checklist: the contract's own versioning rule may not even cover the change you're making; version literals live in more places than you remember; and a schema keyword that no consumer evaluates is worse than no constraint at all, because it looks enforced. This skill runs six phases to close all three.
Reference case: aiat-enablement repo, GitLab issue #17 (2026-07-25). A JSON Schema contract
(docs/spec/estate.schema.json, draft/2020-12) had six fields tightened with new pattern
constraints; schema_version moved 0.1.0 → 0.1.1. All three traps below happened in that
one change. Where cited, "the reference case" means this.
Do not classify Patch/Minor/Major from generic semver instinct. Read the contract's own
versioning-rules section (in its prose spec, README, or a ## Versioning block near the schema)
and ask explicitly: does this rule even define the change class you're making?
# Does the spec define rules for Patch changes at all? (substitute Minor/Major as needed)
grep -n "^#.*[Vv]ersion" docs/spec/<contract>.md
grep -c "Patch" docs/spec/<contract>.md
If the clause you need is missing, authoring that clause is part of this change, not a side quest — write it with an explicit justification for why the new class exists and why your change belongs in it, then proceed. If the clause exists but classifies your change as a stricter tier than you assumed (e.g. a "just tightening a pattern" edit is actually forbidden under an additive-only Minor rule), the rule wins — either recategorize the change or amend the rule first, but never bump the number past what the contract's own rule permits.
Reference case: docs/spec/estate-yaml-v0.md defined only Minor (additive-only) and Major
(needs a migration step). grep -c "Patch" docs/spec/estate-yaml-v0.md returned 0. A
constraint tightening is not additive, so under the existing rule alone it was forbidden. The
test cases passed, vs 10 / 19 without
More skills from the same source and nearby in the registry, with their headline benchmark lift.