# Git Commit

> Implements Conventional Commits workflow. Ensures proper commit message formatting with structured body, footer, and skill signature. Facilitates semantic versioning compliance and clean project history.

- Skill: `wxy/git-commit` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add wxy/git-commit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wxy/git-commit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: wxy (https://skillmd.com/u/wxy)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/wxy/git-commit

---


# _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

```markdown
<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 .`):

```bash
# Stage specific files only
git add src/file1.ts src/file2.ts

# Or review changes before staging
git diff --name-only
git add <files>
```

### Step 2: Create Commit Description File

Copy template, fill in details, maintain required signature:

```bash
# Copy template and edit
cat .agent/skills/_git-commit/references/commit_template.md > .github/COMMIT_DESCRIPTION.local.md
# Then edit with actual changes
```

**Template structure** (keep all sections):
```markdown
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:

```bash
# Verify signature exists
grep -i "git-commit\|🤖" .github/COMMIT_DESCRIPTION.local.md

# Verify type format on first line
head -1 .github/COMMIT_DESCRIPTION.local.md | grep -E "^(feat|fix|docs|style|refactor|test|chore|perf|ci)"
```

### Step 4: Execute Commit

```bash
git commit -F .github/COMMIT_DESCRIPTION.local.md
```

### Step 5: Clean Up

```bash
rm .github/COMMIT_DESCRIPTION.local.md
```

**Complete workflow in one command**:
```bash
git add src/file.ts && \
git commit -F .github/COMMIT_DESCRIPTION.local.md && \
rm .github/COMMIT_DESCRIPTION.local.md
```

---

## Examples

### Example 1: Simple Fix

```markdown
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

```markdown
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

```markdown
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**:
```bash
# Create feature branch
git checkout -b feature/name
git cherry-pick <commit>  # Move commits if needed
```

**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:
- [ ] Files explicitly staged (not `git add .`)
- [ ] Type matches list (feat/fix/docs/etc)
- [ ] Subject ≤50 characters
- [ ] Body ≤72 chars per line
- [ ] Signature line present
- [ ] Issue reference included (if applicable)
- [ ] File correctly saved as `.github/COMMIT_DESCRIPTION.local.md`

---

## 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

