From gh-sdlc
Commit message formatting standards (part of gh-sdlc). Provides formatting rules for git commits — only applies when commits are actually being created. Does NOT trigger the full SDLC workflow on its own.
How this skill is triggered — by the user, by Claude, or both
Slash command
/gh-sdlc:commit-policyThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Keep messages simple by default. Add descriptions only when the change's purpose isn't clear from code inspection alone. If work is tracked in an issue, omit the description — the issue provides context.
Keep messages simple by default. Add descriptions only when the change's purpose isn't clear from code inspection alone. If work is tracked in an issue, omit the description — the issue provides context.
Guiding rule: Use the simplest format that provides necessary context. Allow problem complexity to dictate message structure.
gh-<issue>: <imperative summary> (#pr)
Examples:
gh-23: add database migration for user roles (#30)gh-142579: avoid divmod crash on malformed _pylong.int (#435)gh-18421: reject invalid UTF-8 in marshal string loader (#19012)Rules:
(#pr) MUST be appended to all commits that land on main — this is the final commit message after merge, not optional(#pr) since the PR does not exist yet. The PR number is added at merge time (squash merge auto-appends it; for rebase merge, amend the commit message before merging)<type>(<scope>): <imperative summary>
Examples:
refactor(parser): eliminate redundant token bufferingfix(auth): handle expired session tokens gracefullyfeat(api): add rate limiting middlewareScope references modules/subsystems (e.g., parser, gc, stdlib/asyncio, auth). Omit scope when changes span multiple systems.
| Rule | Detail |
|---|---|
| Mood | Imperative ("add", "fix", "remove" — NOT "added", "fixes") |
| Target length | 50 characters |
| Hard limit | 72 characters (optimized for git log --oneline) |
| Capitalization | Lowercase after type/scope prefix |
| Punctuation | No trailing period |
| Inline codeblocks | Use backtick-wrapped codeblocks for filenames, flags, identifiers, and tool names in commit messages. See below. |
Aggressively use inline codeblocks (backtick wrapping) in commit messages, issue titles, PR titles, and any public-facing text for:
| What to wrap | Example |
|---|---|
| Filenames and extensions | `README.md`, `.gitignore`, `pyproject.toml` |
| CLI flags and options | `--body-file`, `--force-with-lease`, `--assignee` |
| Directory paths | `plugins/`, `src/auth/`, `.claude/` |
| Function/class/variable names | `export_session()`, `ConfigSnapshot` |
| Plugin/tool/package names | `ccgraft`, `gh-sdlc`, `watchdog` |
| Config keys and values | `SINGLE_SELECT`, `settings.json` |
Do NOT wrap:
#42, not `#42`)Shell escaping in --title: When passing backtick-wrapped titles to gh issue create --title or gh pr create --title, use single quotes and raw backticks — never backslash-escape them. Single quotes preserve all characters literally, so backslashes pass through as literal \ characters in the title.
# CORRECT — raw backticks inside single quotes
gh issue create --title 'Plugin: add `hypersaint` architecture skill'
# WRONG — backslash-escaped backticks produce literal backslashes in the title
gh issue create --title 'Plugin: add \`hypersaint\` architecture skill'
# renders as: Plugin: add \hypersaint\ architecture skill
Examples:
gh-37: use --body-file for all issue and PR body content (#38) — flag wrappedgh-42: add README.mdforgh-sdlc plugin (#44) — filename and plugin name wrappeddocs: add MIT license and .gitignore (#5) — filename wrappedgh-23: migrate gh-sdlcskills toplugins/ directory (#30) — plugin name and directory wrapped| Type | Purpose |
|---|---|
feat | New feature |
fix | Bug fix |
perf | Performance improvement |
refactor | Code restructuring (no behavior change) |
test | Test modifications |
build | Build system changes |
ci | CI/CD configuration |
docs | Documentation |
chore | Maintenance/tooling |
revert | Revert previous commit |
Include body text ONLY for:
Omit descriptions when:
gh-<issue>: <imperative summary> (#pr)
- Bullet point explaining the "why"
- Another point if needed
- Keep lines under 72 characters
Use imperative language in bullets. Focus on WHY, not WHAT (the diff shows what).
Order commits logically within a PR:
Example PR sequence:
gh-23: add database migration for user roles
gh-23: implement role-based permission system
gh-23: add permission check tests
gh-23: document permission API in README
During development, mark commits for auto-squashing:
git commit --fixup=<target-hash>
git rebase -i --autosquash origin/main
Before finalizing any commit:
npx claudepluginhub achxy/dotclaude --plugin gh-sdlcGit commit message conventions: structure, formatting, scoping, body content, breaking changes, trailers. Invoke whenever task involves any interaction with commit messages — writing, reviewing, validating, or understanding message format.
Enforces git commit best practices with conventional commits format, atomic principles, type prefixes, and semantic versioning for clear, meaningful history. Use when committing code.
Generates ultra-compressed Conventional Commits messages with ≤50 char subject and body only when 'why' isn't obvious. Auto-triggers when staging changes.