Building an Intelligent Commit Skill for Claude Code

The Daily Commit Struggle Every Developer Knows

It's 11:47 PM. You've just fixed a critical bug that took three hours to track down. Your eyes are heavy, the fix spans six files, and you need to commit. So you type the first thing that comes to mind:

1git commit -m "fix stuff"

We've all been there. "wip", "update", "asdfgh", "please work"... the git log of shame is universal. But here's the thing: those lazy commit messages aren't just embarrassing. They actively slow down your team, your future self, and every code review that follows.

I built claude-commit-skill to solve exactly this problem. It's an open-source skill for Claude Code that analyzes your git changes, asks your preferences, and generates well-structured commit messages following the Conventional Commits specification, fully automatically.

Why Commit Messages Matter More Than You Think

A commit message is not just a label. It's a communication tool. It tells your teammates what changed, why it changed, and what to watch out for. When commit messages are meaningful, your entire development workflow improves:

• Code reviews become faster because reviewers understand context before reading a single line of code
• Debugging is easier since git bisect and git blame actually tell you something useful
• Changelogs write themselves. Tools like semantic-release can auto-generate release notes from structured commits
• Onboarding accelerates as new team members understand the project history by reading the log
• Reverts are safer. When each commit is atomic and well-described, rolling back is surgical, not catastrophic

This is where the Conventional Commits specification comes in. It's a lightweight convention that structures commit messages into a predictable format: type(scope): description. Types like feat, fix, refactor, perf, and chore give immediate context about the nature of the change.

Introducing claude-commit-skill

claude-commit-skill is a Claude Code skill that brings intelligent, Conventional Commits-compliant commit messages to your workflow. Instead of manually crafting commit messages, you type /commit and the skill handles the rest.

Here's what it does:

• Interactive scope selection. When both staged and unstaged changes exist, it asks whether to commit only staged or all changes
• Language support. Always asks your preferred language before generating messages. Subject line stays English per Conventional Commits standard, while the body is written in your chosen language
• Rich commit messages. Generates detailed body with bullet points when changes touch 2+ files or the diff exceeds 30 lines
• Batch commit grouping. In batch mode, groups unrelated changes into separate logical commits by module, file affinity, and change intent
• Smart file pairing. Keeps related files together: implementation + test, component + styles, manifest + lock file, migration + rollback
• Edge case handling. Binary files, large diffs, lock files, merge conflicts, pre-commit hook failures, and submodule changes are all handled gracefully

Getting Started

Quick Install

The fastest way to install is with a single command:

1npx claude-commit-skill

This downloads the package, runs the installer script, and copies the skill files to ~/.claude/skills/commit/. No manual configuration needed.

Manual Install

If you prefer to inspect the source first:

1git clone https://github.com/mustafakbaser/claude-commit-skill.git
2mkdir -p ~/.claude/skills/commit
3cp -r claude-commit-skill/SKILL.md claude-commit-skill/references ~/.claude/skills/commit/

How It Works

When you run /commit, the skill executes a well-defined sequence:

1. Gather context: reads git status, git diff, and recent commit history
2. Determine scope: checks if there are staged changes, unstaged changes, or both, and asks what to include
3. Request language preference: asks whether you want the commit body in English or Turkish
4. Analyze changes: examines the diff to determine the appropriate commit type, scope, and description
5. Execute and verify: creates the commit and confirms success

Let's walk through a real example. First, the skill detects both staged and unstaged changes and asks you to choose the commit scope:

Next, it asks your preferred language for the commit body. The subject line always stays in English per the Conventional Commits standard, but the body can be written in your chosen language:

Finally, the skill analyzes the diff, generates a well-structured commit message, executes the commit, and verifies success:

Single Commit Mode

When you have staged changes ready to commit, the skill generates a single, well-structured message. Here's an example with an English body:

1feat(contracts): add PDF generation for contract renewals
2
3- Add PDF generation support for contract renewal workflows
4- New template system supports all 7 contract types
5- PDF generation runs asynchronously via Edge Functions
6- Upload generated files to Supabase Storage with signed URLs

And the same commit with a Turkish body. Note how the subject line stays in English per the Conventional Commits standard:

1feat(contracts): add PDF generation for contract renewals
2
3- Sözleşme yenileme işlemleri için PDF oluşturma desteği eklendi
4- Yeni şablon sistemi ile 7 farklı sözleşme tipi destekleniyor
5- Edge Function üzerinden asenkron PDF üretimi yapılıyor
6- Oluşturulan dosyalar signed URL ile Supabase Storage'a yükleniyor

Batch Commit Mode

When nothing is staged or the --all flag is passed, the skill switches to batch mode. It groups all changes by logical affinity, presents a commit plan, and waits for your approval before executing:

1Proposed commits:
2
31. feat(wizard): add discount calculation to pricing step
4   - src/components/wizard/PricingStep.tsx
5   - src/lib/pricing.ts
6
72. fix(db): correct meeting balance view
8   - supabase/migrations/20250102_fix_balance.sql
9
103. chore: update dependencies
11   - package.json
12   - package-lock.json

The grouping algorithm runs in five phases: affinity pairing (matching related files), directory clustering (grouping by shared path), semantic separation (feature vs fix vs config), balancing (targeting 2–5 commits), and ordering (infrastructure first, docs last).

Smart File Pairing

One of the most useful features is automatic file pairing. The skill understands that certain files belong together and should never be split across commits:

• Implementation + Test. UserService.ts and UserService.test.ts always stay together
• Component + Styles. Button.tsx and Button.module.css are grouped as one change
• Manifest + Lock file. package.json and package-lock.json are always committed together
• Migration + Rollback. Database migration files and their rollback counterparts are paired

Commit Message Format

The skill follows strict formatting rules to ensure consistency:

Supported commit types: feat, fix, refactor, perf, style, docs, test, chore, ci, security, revert.

Edge Case Handling

Real-world repositories are messy. The skill handles the edge cases that trip up most commit tools:

Start Writing Better Commits Today

Good commit messages are a form of documentation that lives forever in your repository. With claude-commit-skill, you get structured, meaningful commits without the mental overhead of crafting them by hand every time.

If you're already using Claude Code, getting started takes exactly one command:

1npx claude-commit-skill