home / skills / shunsukehayashi / miyabi / commit-helper

commit-helper skill

safe

/.claude/skills/commit-helper

This skill converts git diffs into clear, conventional commit messages to speed up commits and maintain consistency.

npx playbooks add skill shunsukehayashi/miyabi --skill commit-helper

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.9 KB

---
name: commit-helper
description: Generate clear, conventional commit messages from git diffs. Use when creating commits, reviewing staged changes, or writing commit messages.
allowed-tools: Bash, Read, Grep
---

# Commit Helper

**Version**: 1.0.0
**Purpose**: Generate Conventional Commits compliant messages

---

## Triggers

| Trigger | Examples |
|---------|----------|
| Commit | "commit this", "コミットして", "commit changes" |
| Message | "write commit message", "コミットメッセージ作成" |
| Stage | "what should I commit?", "変更内容は？" |

---

## Conventional Commits Format

```
<type>(<scope>): <subject>

<body>

<footer>
```

### Types

| Type | Description | Example |
|------|-------------|---------|
| `feat` | New feature | `feat(auth): add OAuth login` |
| `fix` | Bug fix | `fix(api): handle null response` |
| `docs` | Documentation | `docs: update README` |
| `style` | Formatting | `style: fix indentation` |
| `refactor` | Code restructure | `refactor(utils): extract helper` |
| `perf` | Performance | `perf(query): add index` |
| `test` | Tests | `test(auth): add unit tests` |
| `chore` | Maintenance | `chore: update deps` |
| `ci` | CI/CD | `ci: add GitHub Action` |

---

## Workflow

### Step 1: Analyze Changes

```bash
# View staged changes
git diff --cached --stat
git diff --cached
```

### Step 2: Determine Type

- Adding new functionality? → `feat`
- Fixing a bug? → `fix`
- Updating docs? → `docs`
- Refactoring without behavior change? → `refactor`

### Step 3: Write Subject

```
✅ GOOD: feat(api): add user authentication endpoint
❌ BAD: updated stuff
❌ BAD: feat: Add User Authentication Endpoint (no caps after colon)
```

**Rules:**
- Imperative mood ("add" not "added")
- No period at end
- Max 50 characters
- Lowercase after colon

### Step 4: Write Body (optional)

```
feat(auth): add OAuth2.0 authentication

Implement OAuth2.0 flow with Google and GitHub providers.
This replaces the legacy session-based auth system.

- Add OAuth callback handlers
- Store refresh tokens securely
- Add logout functionality
```

### Step 5: Add Footer (optional)

```
BREAKING CHANGE: auth tokens now expire after 24h

Closes #123
Co-authored-by: Name <email>
```

---

## Examples

### Simple Fix

```bash
git commit -m "fix(parser): handle empty input gracefully"
```

### Feature with Body

```bash
git commit -m "$(cat <<'EOF'
feat(dashboard): add real-time metrics

- WebSocket connection for live updates
- Auto-refresh every 5 seconds
- Graceful fallback to polling

Closes #456
EOF
)"
```

### Breaking Change

```bash
git commit -m "$(cat <<'EOF'
feat(api)!: change response format to JSON:API

BREAKING CHANGE: API responses now follow JSON:API spec.
See migration guide: docs/migration-v2.md

Closes #789
EOF
)"
```

---

## Auto-Generated Footer

All commits include:

```
🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
```

Overview

This skill generates clear, Conventional Commits–compliant messages from git diffs to improve commit quality and consistency. It helps create meaningful commit subjects, optional bodies, and footers following Conventional Commits rules. Use it when creating commits, reviewing staged changes, or automating commit message generation in CI or local hooks.

How this skill works

The skill inspects staged or unstaged git diffs and maps changes to a Conventional Commit type (feat, fix, docs, refactor, perf, test, style, chore, ci). It suggests an imperative, concise subject line, optional descriptive body lines for context and bullet points, and an optional footer for issue references or breaking changes. It can produce single-line messages or multi-line commits with body and footer ready to pass to git commit.

When to use it

When preparing a commit locally and you want a conventional, lint-friendly message
When reviewing staged changes to decide the correct commit type and scope
In git hooks or CI to auto-generate standardized commit messages
When writing multi-line commit bodies that explain rationale and migration notes
When closing issues or adding Co-authored-by and breaking-change footers

Best practices

Choose the commit type that matches intent (feat for new features, fix for bug fixes)
Keep subject under 50 characters, imperative mood, no period at end
Include scope when it improves clarity (e.g., feat(api): ...)
Add a body for non-trivial changes with bullet points and rationale
Use the footer for BREAKING CHANGE notes and issue closers

Example use cases

Generate a one-line fix for a small parser bug from a staged diff
Create a feature commit with body describing added endpoints and migration steps
Auto-add a BREAKING CHANGE footer when a public API shape is altered
Populate Co-authored-by lines and issue references when merging collaborative work
Run in a pre-commit hook to enforce commit message format across a team

FAQ

Can the skill detect breaking changes automatically?

It suggests a BREAKING CHANGE footer when diffs show public API or signature changes, but final confirmation should come from the developer.

Does it support non-English commit messages?

Conventional Commits recommends English for consistency; the skill generates messages in English to integrate with standard tooling and changelog generators.