| name | git-commit |
| description | Implements Conventional Commits workflow. Ensures proper commit message formatting with structured body, footer, and skill signature. Facilitates semantic versioning compliance and clean project history. |
_git-commit
Overview
Standardizes git commit process using Conventional Commits format. Replaces inline commit messages with structured .github/COMMIT_DESCRIPTION.local.md file for clarity and consistency.
When to use: Every code change, feature, fix, or documentation update
Key principle: Never use git commit -m "..." for complex commits - use structured file format instead
Conventional Commits Format
Basic Structure
<type>(<scope>): <subject>
<body>
<footer>
Where:
- type:
feat, fix, docs, style, refactor, test, chore, perf, ci
- scope (optional): Affected component (e.g.,
auth, ui, core)
- subject: Short description (≤50 chars, imperative mood, no period)
- body: Detailed explanation (≤72 chars per line)
- footer: References (e.g.,
Fixes #123) or breaking changes
Commit Types
| Type | Purpose | Example |
|---|
feat | New feature | feat(auth): add OAuth integration |
fix | Bug fix | fix(ui): correct button alignment |
docs | Documentation | docs: update API reference |
style | Code style | style: format TypeScript files |
refactor | Code restructure | refactor: simplify state management |
test | Testing | test: add auth integration test |
chore | Maintenance | chore: upgrade dependencies |
perf | Performance | perf: optimize database queries |
ci | CI/CD changes | ci: add test coverage workflow |
Workflow (5 Steps)
Step 1: Stage Specific Files
Always explicitly stage files (never use git add .):
git add src/file1.ts src/file2.ts
git diff --name-only
git add <files>
Step 2: Create Commit Description File
Copy template, fill in details, maintain required signature:
cat .agent/skills/_git-commit/references/commit_template.md > .github/COMMIT_DESCRIPTION.local.md
Template structure (keep all sections):
feat(scope): Brief description
## Changes
- Change 1
- Change 2
## Technical Details
- Implementation notes
## Testing
- What was tested
---
🤖 Generated by _git-commit skill
Step 3: Verify Format
Check before committing:
grep -i "git-commit\|🤖" .github/COMMIT_DESCRIPTION.local.md
head -1 .github/COMMIT_DESCRIPTION.local.md | grep -E "^(feat|fix|docs|style|refactor|test|chore|perf|ci)"
Step 4: Execute Commit
git commit -F .github/COMMIT_DESCRIPTION.local.md
Step 5: Clean Up
rm .github/COMMIT_DESCRIPTION.local.md
Complete workflow in one command:
git add src/file.ts && \
git commit -F .github/COMMIT_DESCRIPTION.local.md && \
rm .github/COMMIT_DESCRIPTION.local.md
Examples
Example 1: Simple Fix
fix(storage): correct database transaction timeout
Transactions failed when processing >1000 records.
Split into batches of 100 using segment transactions.
Fixes #456
Example 2: Feature
feat(core): implement caching layer
Reduces database load by caching query results.
## Changes
- Add CacheManager class
- Configure TTL (default 5 min, configurable)
- Add unit tests
## Performance
- 40% reduction in database queries
- Query latency improved from 200ms to 50ms
Fixes #123
Example 3: Refactor
refactor(api): unify provider interfaces
Consolidates multiple provider implementations into single factory pattern.
## Breaking Changes
BREAKING CHANGE: Removed legacy Provider class, use ProviderFactory instead
## Migration
1. Update imports to use ProviderFactory.create()
2. Review error handling (new ProviderError type)
Fixes #789
Critical Guidelines
❌ Prohibited:
git commit -m "inline message" (use file instead)git add . (explicitly list files)- Omitting signature line
- Mixing types (feat+fix in one commit)
✅ Required:
- Explicit file list with
git add
- Signature line:
🤖 Generated by _git-commit skill
- Type conformance: feat/fix/docs/etc
- First line ≤50 characters
Common Mistakes
Missing signature:
- Add to description file:
🤖 Generated by _git-commit skill
Accidentally in master:
git checkout -b feature/name
git cherry-pick <commit>
Wrong type:
- Review type table above
- Amend:
git commit --amend
Forgot to clean up .local.md:
- File won't be committed (ignored by .gitignore)
- Delete manually to avoid confusion
Quick Checklist
Before committing:
Related Skills
- _release-process: Release versioning (uses _git-commit for release commits)
- _pr-creator: PR with commit reference
- _code-health-check: Code quality before commit
