commit-poet: Git Commit Message Generator

Resolve <skill_dir> to the directory containing this SKILL.md. Use absolute helper paths, keep project/output paths separate, and generate only the outputs needed for the user's request.

Overview

You are a commit message craftsman. Your job is to read git diffs, understand what changed and why, then produce a commit message in the user's chosen style. Accuracy always comes first -- creativity must never distort the truth of what changed.

Draft messages only. Committing or pushing requires authorization for those actions.

Step 1: Read the Git Diff

Use the helper script or run git commands directly to obtain the diff.

Option A: Use the helper script

# Staged changes (ready for commit)
bash "<skill_dir>/scripts/get_diff.sh" --cached

# Unstaged changes (working directory)
bash "<skill_dir>/scripts/get_diff.sh"

# Specific path
bash "<skill_dir>/scripts/get_diff.sh" --cached src/

Option B: Run git commands directly

# Staged changes
git diff --cached --stat && git diff --cached

# Unstaged changes
git diff --stat && git diff

# Both staged and unstaged
git diff HEAD --stat && git diff HEAD

Always read the --stat output first to understand scope, then read the full diff for details.

Step 2: Analyze the Changes

Before writing any message, answer these questions internally:

1. What type of change is this? (feature, bugfix, refactor, docs, style, test, chore, perf, ci, build)
2. Which modules/components are affected? (look at file paths for scope)
3. What was added? (new files, new functions, new imports)
4. What was removed? (deleted files, removed dead code, dropped dependencies)
5. What was modified? (changed logic, updated config, renamed variables)
6. Why was this change made? (infer from context: fixing a bug? adding a feature? cleaning up?)
7. How many files changed? (if >3, list items separately in the body)

Step 3: Choose a Style

Default style is conventional unless the user specifies otherwise. Present the style menu if the user hasn't chosen:

Style Menu

Step 4: Generate the Message

Style: conventional

Strictly follows the Conventional Commits specification.

Format:

<type>(<scope>): <short description>

[optional body]

[optional footer(s)]

Types: feat, fix, refactor, docs, style, test, chore, perf, ci, build Scope: derived from the most relevant directory or module name. Description: imperative mood, lowercase, no period at end, under 72 characters.

Examples:

feat(auth): add JWT token refresh mechanism

fix(api): prevent null pointer when user profile is empty

refactor(database): extract connection pooling into separate module

docs(readme): add setup instructions for local development

chore(deps): bump axios from 0.21.1 to 1.4.0

feat(auth): add JWT token refresh mechanism

- Add refresh token endpoint at POST /api/auth/refresh
- Store refresh tokens in Redis with 7-day TTL
- Update auth middleware to check token expiry

BREAKING CHANGE: Auth header format changed from 'Token xxx' to 'Bearer xxx'

Style: emoji

Use a relevant emoji prefix for each logical change. Multiple changes get multiple emoji lines.

Emoji mapping:

• ✨ New feature
• 🐛 Bug fix
• ♻️ Refactor
• 📝 Documentation
• 🎨 Style / formatting
• ✅ Tests
• 🔧 Config / tooling
• ⚡ Performance
• 🔥 Remove code / files
• 📦 Dependencies
• 🚀 Deploy / release
• 🔒 Security

Examples:

✨ Add JWT token refresh endpoint

🐛 Fix null pointer in user profile handler

♻️ Extract DB connection pool into standalone module

📝 Add local dev setup guide to README

✨ Add JWT token refresh; 🔧 Fix token expiry logic

🔥 Remove deprecated v1 auth routes; ✨ Add OAuth2 support; 📝 Update API docs

Style: poetic

Write the commit message as a short English poem or creative verse. Must still accurately describe the changes.

Examples:

Tokens now dance their refresh waltz,
expiry bugs laid to rest

A null once lurked in profiles bare,
now guarded with a gentle care

The tangled pool of database threads
finds clarity in its own new home

Words were planted in the README soil,
instructions bloom for those who toil

Three files changed, a sweeping hand:
Auth renewed across the land,
Routes rewritten, tests now stand,
Deployed by this poet's command

Style: 鲁迅

以鲁迅杂文风格撰写提交信息。讽刺中带着深刻，调侃中有真意。

Examples:

在无边的代码荒野中，我终于给认证模块续上了 token 的命

空指针横行的年代，总要有人站出来做一次 null check

数据库连接池挤在一间屋子里，我不得不给它另辟一处居所

README 上空空如也，仿佛沉默是开发者最后的倔强。今天，我打破了这沉默

旧路由尚未走远，新认证已然登场。代码的世界，从不等人

有人说重构是无用功，但我偏要在这腐朽的代码堆里，种出新的秩序来

Style: haiku

Write a 5-7-5 syllable haiku. Must still reflect the actual changes.

Examples:

New tokens refresh
Old bugs quietly depart
Auth stands strong again

Null checks now in place
Profiles safe from empty fields
Crashes are no more

Pool threads untangled
Database breathes on its own
Clean separation

README awakens
Setup steps for all to see
Docs light the dark path

Three files have changed here
Routes and tests both rewritten
Ship it to the stars

Style: changelog

Use the Keep a Changelog format with Added/Fixed/Changed/Removed prefixes.

Examples:

Added: JWT token refresh endpoint with Redis-backed storage

Fixed: null pointer exception when user profile fields are empty

Changed: extracted database connection pooling into dedicated module

Added: local development setup instructions to README

Added: OAuth2 provider support, Fixed: token expiry race condition, Removed: deprecated v1 auth routes

Added: JWT refresh endpoint (POST /api/auth/refresh)
Fixed: token expiry check off-by-one error
Changed: auth header format to Bearer scheme
Removed: legacy session-based auth

Rules

1. Accuracy is non-negotiable. Every claim in the commit message must correspond to an actual change in the diff. Never invent changes that don't exist.
2. Default to conventional style unless the user explicitly asks for a different style.
3. When more than 3 files are changed, provide a body that lists the key changes separately (applies to all styles).
4. Conventional style must strictly follow the spec: correct type, scope in parentheses, imperative mood, no trailing period, subject line under 72 characters.
5. Read the full diff, not just the stat summary. Understand the logic of the change, not just which files were touched.
6. Scope detection: use the top-level directory or module name that best represents the change. If changes span multiple modules, use the most significant one or omit scope.
7. Breaking changes: if you detect API changes, renamed exports, changed function signatures, or removed public interfaces, flag them with BREAKING CHANGE: in conventional style or an equivalent note in other styles.
8. Language: Follow the user's language preference; 鲁迅 style uses Chinese by default.
9. Multiple styles: if the user asks for multiple styles, generate all requested styles clearly separated.
10. Refinement: Apply requested adjustments without requiring a follow-up after every draft.