Use when creating git commits or pull requests. Enforces conventional commit format and atomic change principles. Verified on Git 2.30+
Scanned 2/10/2026
Install via CLI
Skills Directoryopenskills install majiayu000/claude-skill-registry---
name: git-commit-standards
description: "Use when creating git commits or pull requests. Enforces conventional commit format and atomic change principles. Verified on Git 2.30+"
author: "Claude Code Learning Flywheel Team"
allowed-tools: ["Bash", "Read", "Grep"]
version: 1.2.0
last_verified: "2025-12-31"
tags: ["git", "workflow", "team-standards"]
related-skills: []
verification:
test_script: "tests/skills/test_git_commit_standards.py"
command: "python3 tests/skills/test_git_commit_standards.py"
frequency: "on-change"
---
# Git Commit Standards
## 1. Context & Scope
This skill defines the team's git commit and pull request standards, ensuring consistent history and easy rollback/debugging.
**Trigger Conditions:**
- When user asks to "commit changes"
- When user asks to "create a pull request"
- Before running `git commit` or `gh pr create`
**Environment:**
- Git: 2.30+
- GitHub CLI (optional): 2.20+
- Pre-commit hooks: Enabled (validates format)
**Out of Scope:**
- Branching strategy (see `git-workflow` skill)
- Code review guidelines (see `code-review-process` skill)
---
## 2. Negative Knowledge (Read First)
*Common mistakes that have caused problems in the past.*
### Failed Attempts Table
| # | Attempted Strategy | Error/Symptom | Root Cause | Fix/Prevention |
|---|-------------------|---------------|------------|----------------|
| 1 | Used generic "fix bug" messages | Unable to identify which commit caused production issue | No context about WHAT was fixed | Use format: `fix(component): specific issue description` |
| 2 | Committed multiple unrelated changes together | Had to revert feature A but it also reverted unrelated fix B | Atomic commit principle violated | One logical change per commit, use `git add -p` |
| 3 | Used past tense "Added feature X" | Inconsistent with team convention, hard to scan history | Team uses imperative mood | Use "Add feature X" not "Added feature X" |
| 4 | Forgot to reference issue number | PM couldn't track which commits belonged to which feature | No traceability to project management | Add `Refs: #123` footer to all commits |
### Common Pitfalls
- **❌ Don't:** Write vague messages like "updates", "fixes", "changes"
- **Why it fails:** 6 months later, impossible to understand intent
- **✅ Do instead:** "fix(auth): prevent token expiry race condition"
- **❌ Don't:** Commit WIP code directly to main branch
- **Why it fails:** Breaks CI/CD, blocks other developers
- **✅ Do instead:** Use feature branches, squash before merge
- **❌ Don't:** Include passwords, API keys, or secrets in commits
- **Why it fails:** Git history is permanent, secrets are exposed forever
- **✅ Do instead:** Use .env files (gitignored), run `scripts/check_secrets.sh` pre-commit
---
## 3. Verified Procedure
> **IMPORTANT:** This skill is a "Tool Wrapper" - DO NOT analyze commit message format yourself.
> Use the deterministic validation script for accuracy and speed.
### Prerequisites Check
```bash
# Run automated pre-commit validator
python scripts/validate_commit_msg.py --check-setup
# Expected output: "✅ Git hooks installed, conventional commit format enabled"
```
### Step 1: Stage Changes Atomically
**Description:** Group related changes together, exclude unrelated changes
```bash
# Review what changed
git status
git diff
# Stage specific files (atomic changes)
git add path/to/changed/file.py
# OR stage interactively (parts of files)
git add -p path/to/file.py
# Press 'y' to stage hunks that belong together
# Press 'n' to skip unrelated changes
```
**Validation:**
```bash
# Verify only intended changes are staged
git diff --cached
# Expected: Only logically related changes visible
```
### Step 2: Write Conventional Commit Message
**Description:** Format message according to team standards
**Format:**
```
<type>(<scope>): <subject>
<body>
<footer>
```
**Types (choose one):**
- `feat`: New feature for the user
- `fix`: Bug fix for the user
- `docs`: Documentation changes
- `style`: Code formatting (no logic change)
- `refactor`: Code restructuring (no behavior change)
- `test`: Adding or updating tests
- `chore`: Build process, dependencies, tooling
**Example:**
```bash
git commit -m "$(cat <<'EOF'
feat(api): add rate limiting to /users endpoint
Implements token bucket algorithm with 100 req/min limit.
Prevents abuse observed in incident #456.
Refs: #123
Breaking Change: Clients must handle 429 status codes
EOF
)"
```
**Validation:**
```bash
# DO NOT validate commit message text manually
# Use the deterministic script instead:
python scripts/validate_commit_msg.py HEAD
# Expected output: "✅ Commit message follows conventional format"
# If errors returned, fix them based ONLY on script output
```
### Step 3: Verify Before Push
**Description:** Run final checks before pushing to remote
```bash
# Run tests (if applicable)
npm test # or: pytest, cargo test, etc.
# Check commit message format
python scripts/validate_commit_msg.py HEAD
# Push to remote
git push -u origin <branch-name>
```
**Success Criteria:**
- [ ] Commit message follows conventional format
- [ ] Only one logical change per commit
- [ ] Tests pass locally
- [ ] No secrets or sensitive data included
- [ ] Issue number referenced (if applicable)
---
## 4. Configuration Reference
### Conventional Commit Format
**Regex Pattern:**
```regex
^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .{1,72}$
```
**Scope Examples:**
- `api` - Backend API changes
- `ui` - Frontend user interface
- `db` - Database schema/migrations
- `auth` - Authentication/authorization
- `ci` - CI/CD pipeline changes
### Git Hooks Configuration
Create `.git/hooks/commit-msg`:
```bash
#!/bin/bash
# Validate commit message format
python scripts/validate_commit_msg.py "$1"
exit $?
```
Make executable:
```bash
chmod +x .git/hooks/commit-msg
```
---
## 5. Troubleshooting
### Error Pattern Recognition
| Error Message | Likely Cause | Quick Fix |
|---------------|--------------|-----------|
| `pre-commit hook failed` | Commit message doesn't match format | Amend with `git commit --amend` using correct format |
| `secret detected in commit` | API key or password in staged files | `git reset HEAD <file>`, add to `.gitignore`, use env vars |
| `diverged branches` | Remote has commits you don't have | `git pull --rebase origin main` then re-push |
### Diagnostic Commands
```bash
# Check recent commit history
git log --oneline -10
# See what would be committed
git diff --cached --stat
# Check for secrets (before committing)
python scripts/check_secrets.sh
# View commit message of last commit
git log -1 --pretty=%B
```
---
## 6. Reference Links
**Internal Documentation:**
- Full commit message examples: See `examples/commit-messages.md`
- Branching strategy: See `.claude/skills/git-workflow/SKILL.md`
**External Resources:**
- [Conventional Commits Specification](https://www.conventionalcommits.org/)
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
---
## 7. Maintenance Log
| Date | Version | Change Summary | Trigger |
|------|---------|----------------|---------|
| 2026-01-01 | 1.2.0 | Added executable verification framework integration | Agent Ops framework enhancement |
| 2025-12-31 | 1.1.0 | Refactored to Tool Wrapper pattern, verified skill still accurate | Architectural audit remediation |
| 2025-01-01 | 1.0.0 | Initial skill creation | Setup learning flywheel scaffold |
---
## 8. Metrics & Success Indicators
**How to measure if this skill is working:**
- **Consistency:** 95%+ of commits follow conventional format (checked in CI)
- **Traceability:** Every commit links to an issue or requirement
- **Revert Safety:** Can revert individual features without side effects
**When to update this skill:**
- When a commit causes a problem (add to Negative Knowledge)
- When team adopts new commit type or scope
- When git version changes behavior
No comments yet. Be the first to comment!
