dh-semver
Apply strict Semantic Versioning — analyze commits since the last tag to determine the bump type (major/minor/patch from conventional commit prefixes), generate an automated changelog grouped by breaking changes, features, fixes, and chores, and create a git tag locally without pushing until confirmed, handling both conventional commits and manual version decisions. Use when preparing a release, invoked by dh-execute-plan after plan completion and dh-final-review for release readiness, or when the user asks "what version is next?", "bump version", "generate changelog", "tag release", or "what changed since last release?".
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 8
- Forks
- 1
01 前言 Front Matter
- name
- dh-semver
- license
- MIT
- metadata
- { "audience": "developers", "workflow": "development" }
- description
- Apply strict Semantic Versioning — analyze commits since the last tag to determine the bump type (major/minor/patch from conventional commit prefixes), generate an automated changelog grouped by breaking changes, features, fixes, and chores, and create a git tag locally without pushing until confirmed, handling both conventional commits and manual version decisions. Use when preparing a release, invoked by dh-execute-plan after plan completion and dh-final-review for release readiness, or when the user asks "what version is next?", "bump version", "generate changelog", "tag release", or "what changed since last release?".
- allowed-tools
- bash, read
- compatibility
- opencode
03 SKILL.md 正文
Harness-localized adaptation of the global semver skill. The versioning
algorithm is identical; the harness adaptations are that every git command
runs through the dh-execute-cli skill, and this skill is invoked from the
bundled loop skills or a direct user request — the harness bundles no
commands.
Core Rules
- Find the last tag:
git describe --tags --abbrev=0. If that fails because the repo has no tags yet, default tov0.0.0. - Collect the commits since that tag:
git log <tag>..HEAD --oneline. - Map commit messages to the bump type using conventional commit prefixes:
BREAKING CHANGE:in the message body, or!after the type (feat!:), → MAJOR bumpfeat:orfeat(scope):→ MINOR bumpfix:,chore:,docs:,style:,refactor:,perf:,test:,ci:,build:→ PATCH bump
- If no conventional commit format is detected, prompt the user for the bump type — never guess.
- Generate the changelog grouped by Breaking Changes (if any), Features, Fixes, and Chores & Maintenance; every entry keeps its short commit hash.
- Create the tag locally:
git tag -a v<major>.<minor>.<patch> -m "Release v<major>.<minor>.<patch>". - Do NOT push the tag — the user confirms before pushing.
- Run ALL git commands through the
dh-execute-cliskill — never run bash directly from the agent applying this skill.
Edge Cases
- No commits since the last tag → report "No changes — no version bump needed" and stop.
- No tags in the repo → treat
v0.0.0as the current version, but note it is not a real ref to diff against — enumerate ALL commits withgit log --onelineto determine the first release. - Tags exist but are unreachable from the current branch (e.g. releases are
tagged on
mainwhile you work ondevelop) →git describeunder-reports the current version. Cross-checkgit tag --sort=-v:refnamefor the highest released tag and state the assumption; the durable fix is the repo's back-merge ofmainafter tagging, which keeps tags reachable. - History without conventional commit prefixes → ask the user which bump applies; do not infer a bump from vague messages.
Harness Invocation Sources
The harness bundles no commands, so there is no release command step to import. This skill runs when:
dh-execute-planfinishes a plan on a software project and needs the next version bump.dh-final-reviewchecks release readiness and reports the recommended bump.- The user asks directly: "what version is next?", "bump version", "generate changelog", "tag release", or "what changed since last release?".
Output Template
# Version Decision
**Current:** vX.Y.Z (tag: <tagname>)
**Bump:** MAJOR / MINOR / PATCH → **vX.Y.Z**
**Reason:** [N breaking changes, N features, N fixes]
# Changelog vX.Y.Z
## Breaking Changes
- [Description] (<commit-short-hash>)
## Features
- [Description] (<commit-short-hash>)
## Fixes
- [Description] (<commit-short-hash>)
## Chores & Maintenance
- [Description] (<commit-short-hash>)
**Tag:** `vX.Y.Z` (created locally — awaiting confirmation to push)
Safety
- Do not push tags or commits without explicit user confirmation.
- Do not delete or modify existing tags.
- Create the tag only after the version decision and changelog are reported; the tag stays local until the user confirms pushing.
- Report the decision with its git evidence (last tag, commit counts, short
hashes) exactly as the
dh-execute-cliskill reports it — no guessing.
References
dh-execute-plananddh-final-reviewskills: the bundled loop steps that invoke this skill.AGENTS.mdversioning note: tags are semver onmainonly.
Doc search
Documentation management: delegate create / update / delete / retrieve of generated documents (excluding docs/plans) to the best available documentation agent (bundled documentation capability as fallback) — the main and only documentation owner (see dh-create-documentation).
Search generated documentation quickly: notesmd-cli search-content "<term>" --vault "<project-name>" or obsidian search query="<term>" (fallback: rg --glob '*.md' "<term>" docs/).
04 同仓库更多 Skills
dh-simplify
Review changed code for reuse, quality, and efficiency (three parallel reviews), then fix findings directly. Use after making changes or when asked to clean up, refactor, simplify, or improve this code.
dh-setup
Audit system software, configure user MCPs/plugins, scaffold project QA (hooks + per-stack tools), bootstrap docs/architecture with the selected architecture agent, and write harness directives into AGENTS.md. Use to check requirements or setup the environment.
dh-review
Verify a plan sub-task against acceptance criteria, scope, done-when; review diff, validation, regression risk; structured verdict to tasks/review.md. Plan Alignment Mode (fast execution) is a separate mode: no sub-task selection, no diff review, no code review — it compares plan.md with plan_fast.md and writes tasks/review-fast.md (pre-execution) or tasks/review-fast-final.md (plan-end). Use after implementation, to review/verify the sub-task, or to check fast-plan alignment.
dh-resume-plan
Resume a paused phased plan from docs/plans/<slug>/handoff.md: validate the contract, detect drift, rehydrate context, mark the handoff resumed, and continue via dh-execute-plan resume mode. Use when the user says "resume the plan", "continue where we stopped", "pick up the plan", or "resume after a pause".
dh-preflight
Run tests, linters, static analysis as a release gate: auto-detect tooling, check dirty state, pass/fail verdict with actionable failures (no auto-fixes). Use to run preflight, pre-release check, or validate before release.
dh-planning
Write phased plans to ./docs/plans/<slug>/plan.md: phases with sub-tasks, requirements mapping (stable IDs), scope, acceptance criteria. SDD gate: invoke dh-grill-sdd when ./docs/plans/<slug>/sdd.md is absent. Use to plan this or create a plan.