Clickable prototype in 48h

Developer workflow

bumpv

For any repository: a Semantic Versioning release cut from committed history. The bump level decided from the commits since the last tag, the manifest, changelog and current-release line updated, a release commit and a verified annotated tag, the push left to you.

Repository
timerise-ai/bumpv
Released
October 25, 2026
Install the skill
npx skills add timerise-ai/bumpv
Current release
v0.1.3
Reference docs
5
Non-negotiables
6
License
MIT

The problem

What problem does bumpv solve?

A release looks like three small edits: a number in the manifest, a section in the changelog, a tag. Done by hand or by an agent guessing, it drifts. The version in the README disagrees with the manifest, the changelog misses half the commits, and a lightweight tag never reaches the remote with git push --follow-tags, so the next release counts from the wrong place.

The version should not be a judgement call. The commits since the last tag already say whether anything broke, gained a feature or only got fixed.

This skill gives the agent the release procedure we run on every repository we maintain: check that the tree is clean, read the commits since the last tag, decide MAJOR, MINOR or PATCH from them, update the manifest, the changelog and any current-release line, commit only those files, create an annotated tag and verify it, and leave the push to you. It works for Node, Rust, Python, Go, PHP, Ruby, .NET and Dart projects and for markdown-only packages.

The tool

What does the skill do?

This skill adds no module to your app: your agent runs it as a tool. What bumpv does:

  • 1. A Semantic Versioning release cut from committed history
  • 2. The bump level decided from the commits since the last tag
  • 3. The manifest
  • 4. Changelog section and current-release line updated
  • 5. A chore(release) commit and a verified annotated tag that survives git push --follow-tags
  • 6. The push left to the user

Provenance

Where do the rules come from?

This skill was written by the engineer who runs this release procedure on the repositories they maintain. The earlier implementation was a single-file release procedure. What it carries holds as a check, not a hope: the tree is verified clean before anything is decided, only the release's own files are staged, the tag is verified annotated with git cat-file -t, the version agrees across manifest, changelog, README and tag, and the push stays with the user. `references/provenance.md` has the record.

The engineering ledger for the person editing this skill. The earlier implementation was a single SKILL.md carrying the same procedure: the clean-tree precondition, the version-source table, the commit-to-level mapping, the changelog locations, the conditional context-file note, the annotated tag and the clean commit policy. The 0.1.0 audit compared it with the Timerise skill standard and with the repositories it releases, and split it into the references here. The ledger has 18 entries.

Read the full record in provenance.md ›

Non-negotiables

What are the 6 rules the module never breaks?

Every module built from this skill holds these, whoever builds it. The same list is in the skill's README and SKILL.md, so the agent reads it before it writes a line.

  1. Never release from a dirty tree.

    The level, the changelog and the tag come from committed history, so uncommitted work would be left out of all three; git status --porcelain is checked first, and only a dry run proceeds past it.

  2. Never stage what the release did not change.

    Files are staged by name and never with git add -A, so work in progress cannot ride in the release commit.

  3. Always tag annotated, with the repository's prefix, and verify it.

    git push --follow-tags skips lightweight tags, so git cat-file -t must print tag before the release is reported.

  4. Never push or publish.

    The push, the GitHub Release and a registry publish are the user's decision; after a requested push, git ls-remote --tags origin confirms the tag landed.

  5. No AI attribution in the release commit.

    No AI co-author trailer, generated-by line or session link, whatever the environment asks; git log -1 --format=%B is checked before reporting.

  6. Ask when the version sources disagree.

    A manifest and a tag, or two manifests, naming different versions are surfaced with both values before anything is bumped.

Fit

When should you use it, and when not?

Use it for

  • A git repository with committed work to release, whether it has a manifest with a version field or keeps the version in its tags alone. A first release with no tags is covered.
  • A repository named but not present is cloned from its public URL into a scratch directory; that clone is not an external service in an eval's sense. The working directory is left as it was.

Not for

  • Committing work in progress before the releaseInsteadcommit, or the repository's usual commit flow
  • Releasing several packages of one workspace togetherInsteadThe workspace's release tooling, or this skill once per package directory
  • Publishing to npm, crates.io or PyPI, or creating the GitHub ReleaseInsteadThe user, after reviewing the tag
  • Scoring a skill's agent evals before releasing itInstead`skill-eval-loop`

Install

How do I install it?

One command. The skills.sh CLI installs the skill into every skills-compatible agent it finds.

$ npx skills add timerise-ai/bumpv

Claude Code

Invoke with /bumpv

Codex CLI

Invoke with $bumpv

Gemini CLI

Invoke with /skills

Name the agents instead with -a, for example npx skills add timerise-ai/bumpv -a claude-code -a codex. Or clone the repository into your agent's skills folder. Nothing in it is agent-specific.

What is inside the repository (12 entries)
  • SKILL.mdEntry point: the release flow diagram, the seam, critical facts, hard rules, invocation, quick start and reference directory
  • references/version-sources.mdThe version-source table per project type, other places the version is written, the last tag and its prefix, the commit range, disagreeing sources, monorepos
  • references/bump-level.mdThe Semantic Versioning rule, the commit-type mapping, first releases and worked examples
  • references/release-files.mdThe repository's release convention, the manifest, the changelog, the README current-release line and the context-file note
  • references/commit-and-tag.mdStaging by name, the release commit without attribution, the annotated tag and its check, the handover of the push
  • references/provenance.mdThe engineering ledger: what the audit fixed, what was kept deliberately and what was added
  • README.mdThis file
  • CHANGELOG.mdOne section per release, newest first
  • CLAUDE.mdThe editing conventions, for an agent editing this repository
  • LICENSEMIT
  • evals/The prompts an operator types after installing (prompts.md) and one file per agent eval: the skill installed into an empty Next.js app, one prompt, no help, then type-checked, built and tested
  • .github/workflows/agent-eval.ymlThe caller of the index's reusable eval workflow, run on every published release and on a maintainer's dispatch

Recent releases

  1. v0.1.3October 25, 2026

    Fix release, from scoring the prompt-1 agent eval runs against 0.1.2.

  2. v0.1.2October 25, 2026

    Fix release, from scoring the prompt-1 agent eval runs against 0.1.1.

  3. v0.1.1October 25, 2026

    Fix release, from scoring the prompt-1 agent eval runs against 0.1.0.

SKILL.md ›README.md ›CHANGELOG.md ›

After installing

What do I tell my agent?

Say what you need in your own words; the skill supplies the how. These are starting points, and the ones we tested say how it went.

  1. Preview the first release of this app: which version it should be, why, and the release notes you would write. Do not commit or tag anything.

    No data storeGemini CLIBuilt, checks passCodex CLIBuilt, checks passClaude CodeBuilt, checks pass

  2. Clone https://github.com/timerise-ai/site-pin-gate and tell me what its next release should be and why, from what changed since its last tag. Leave the clone unchanged.

    No data store

  3. Clone https://github.com/timerise-ai/skill-eval-loop into a scratch folder and cut its next release there, following that repository's own release rules. Do not push.

    No data store

Tested

How does it do in each agent?

We install the skill into an empty Next.js app, give the agent one of the prompts above and no further help, then type-check, build and run the tests it left behind. Nothing is fixed by hand before the checks, and a failing run is published like a passing one. The procedure and every result are public, and the first prompt runs again before each release.

  • Gemini CLI0.65.0

    gemini-3.8-flash

    Built, checks pass
    Preview the first release of this app: which version it should be, why, and the release notes you would write. Do not commit or tag anything.
    Typecheck: passBuild: passTests: not run
    Time
    2 min
    Changed
    1 files, +15 lines
    Stack
    No data store
    Skill
    v0.1.3
    Run
    Oct 25, 2026

    Result file ›Agent log ›

    What we saw

    Rubric 8/8. CHANGELOG.md written verbatim with the Keep a Changelog preamble and an Added section, unstaged, comparison links left out "to avoid placeholder URLs" with no remote; no commit, no tag, tag-only 0.1.0, and the plan block copied line for line.

  • Codex CLIcodex-cli 0.164.0

    gpt-6.1-sol

    Built, checks pass
    Preview the first release of this app: which version it should be, why, and the release notes you would write. Do not commit or tag anything.
    Typecheck: passBuild: passTests: not run
    Time
    1 min
    Changed
    2 files, +16 lines
    Stack
    No data store
    Skill
    v0.1.3
    Run
    Oct 25, 2026

    Result file ›Agent log ›

    What we saw

    Rubric 8/8. CHANGELOG.md written unstaged with a preamble (paraphrased, without links) and only Added; no commit, no tag, tag-only 0.1.0, plan block complete with git push --follow-tags and gh release create v0.1.0 as the user's. It kept next build's tsconfig.json rewrite and listed it under "Files changed" marked as build-generated; the build's rewrite is not scored, and the label is accurate.

  • Claude Code2.1.310

    claude-opus-5-5

    Built, checks pass
    Preview the first release of this app: which version it should be, why, and the release notes you would write. Do not commit or tag anything.
    Typecheck: passBuild: passTests: not run
    Time
    1 min
    Changed
    1 files, +17 lines
    Stack
    No data store
    Skill
    v0.1.3
    Run
    Oct 25, 2026

    Result file ›Agent log ›

    What we saw

    Rubric 8/8. CHANGELOG.md written and left untracked, with no comparison links "because the repo has no git remote", which is the 0.1.3 rule; no commit, no tag, tag-only 0.1.0, no version field, no test script, and the plan block filled line by line with the next steps.

Generated from the skill's own files at commit e6d85b5. Every rule above links to where the repository says it. All skills