Commit Helper
Format CockroachDB-style git commits and pull requests with imperative subjects, issue references, and categorized release notes.
Overview
commit-helper is an agent skill most often used in Ship (also Build backend, Operate iterate) that drafts CockroachDB-convention git commits and PR text from your diffs.
Install
npx skills add https://github.com/cockroachdb/cockroach --skill commit-helperWhat is this skill?
- 8-step workflow from diff analysis through formatted commit creation
- Commit template: package prefix, imperative subject under 72 characters, body, Resolves/Epic lines, release note line
- Prompts for issue/epic numbers and release-note category when not obvious from context
- Uses git diff --staged or git diff to ground the message in actual changes
- Workflow: 8 numbered steps from analyze changes through create commit
- Subject line guidance: under 72 characters, imperative mood, no period
Adoption & trust: 626 installs on skills.sh; 32.2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your changes are ready to push but the commit subject, body, issue refs, and release note do not match CockroachDB’s expected format.
Who is it for?
Contributors to CockroachDB or teams mirroring its git and release-note conventions on every PR.
Skip if: Repos with unrelated commit styles where automated semantic-release or squash-only workflows make package-prefixed messages unnecessary.
When should I use this skill?
Committing changes or creating pull requests and you need CockroachDB-formatted messages and release notes.
What do I get? / Deliverables
You get a properly structured commit message and release note line ready for git commit or PR description, grounded in git diff output.
- Formatted commit message
- Release note line with category
- PR-ready description with issue/epic references
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Ship because the skill governs how changes leave your machine as reviewable commits and PRs with project conventions. Review fits PR creation and message quality checks before merge, which is where commit-helper’s structured workflow lands first.
Where it fits
Turn a staged SQL execengine fix into a package-prefixed commit with Resolves and a release note before opening the PR.
After implementing a storage change, draft the explanatory body comparing old vs new behavior for reviewers.
Ship a hotfix with a categorized release note describing user-visible recovery behavior.
How it compares
Use instead of freeform one-line git commits when upstream expects package prefixes and categorized release notes.
Common Questions / FAQ
Who is commit-helper for?
Solo and small-team developers committing to CockroachDB or similar repos who want agent-guided, convention-accurate messages and release notes.
When should I use commit-helper?
Use it in Ship when opening or updating a PR, during Build after a feature branch is done, and in Operate iterate when landing fixes that still need user-facing release notes.
Is commit-helper safe to install?
It guides git operations you approve; review the Security Audits panel on this Prism page and never let an agent commit secrets visible in diffs.
SKILL.md
READMESKILL.md - Commit Helper
# CockroachDB Commit Helper Help the user create properly formatted commit messages and release notes that follow CockroachDB conventions. ## Workflow 1. **Analyze the changes**: Run `git diff --staged` or `git diff` to understand what was modified 2. **Determine the package prefix**: Identify the primary package affected 3. **Ask the user** for: - Issue/epic number if not already known - Whether release notes are needed and what category fits best 4. **Write the subject line**: Imperative mood, no period, under 72 characters 5. **Write the body**: Explain the before/after, why the change was needed 6. **Add issue references**: Include Resolves/Epic as appropriate 7. **Write the release note**: Clear, user-focused description of the change 8. **Create the commit** using the properly formatted message ## Commit Message Structure **Basic Format:** ``` package: imperative title without period Detailed explanation of what changed, why it changed, and how it impacts users. Explain the problem that existed before and how this commit solves it. Include context about alternate approaches considered and any side effects or consequences. Resolves: #123 Epic: CRDB-357 Release note (category): Description of user-facing change in past or present tense explaining what changed, how users can see the change, and why it's important. ``` **Key Requirements:** - **Must** include release note annotation (even if "Release note: None") - **Must** include issue or epic reference - **Must** separate subject from body with blank line - **Recommended** prefix subject with affected package/area - **Recommended** use imperative mood in subject (e.g. "fix bug" not "fixes bug") - **Recommended** wrap body at 72-100 characters ## Release Note Categories **When to include release notes:** - Changes to user interaction or experience - Changes to product behavior (performance, command responses, architecture) - Bug fixes affecting external users **When to exclude release notes:** - Internal refactors, testing, infrastructure work - Code that's too immature for docs (private preview features) - Internal settings beginning with `crdb_internal.` - Functionality not accessible to external users **Valid Categories:** - `backward-incompatible change` - Breaking changes to stable interfaces - `enterprise change` - Features requiring enterprise license - `ops change` - Commands/endpoints for operators (logging, metrics, CLI flags) - `cli change` - Commands for developers/contributors (SQL shells, debug tools) - `sql change` - SQL statements, functions, system catalogs - `ui change` - DB Console changes - `security update` - Security feature changes - `performance improvement` - Performance enhancements - `cluster virtualization` - Multi-tenancy infrastructure - `bug fix` - Problem fixes - `general change` - Changes that don't fit elsewhere - `build change` - Source build requirements ## Release Note Best Practices **Description guidelines:** - Default to more information rather than less - Explain **what** changed, **how** it changed, and **why** it's relevant - Use past tense ("Added", "Fixed") or present tense ("CockroachDB now supports") - For bug fixes: describe cause, symptoms, and affected versions - Note if change is part of broader roadmap feature **Examples:** **Good bug fix:** ``` Release note (bug fix): Fixed a bug introduced in v19.2.3 that caused duplicate rows in CREATE TABLE ... AS results when multiple nodes attempt to populate the results. ``` **Good feature:** ``` Release note (enterprise change): Shortened the default interval for the kv.closed_timestamp.target_duration cluster setting from 30s to 3s. This allows follower reads at 4.8 seconds in the past, a much shorter window than the previous 48 seconds. ``` #