managing-commits by aiskillstore
Git commit quality and conventional commits expertise with automatic issue tracking integration. Auto-invokes when the user explicitly asks about commit message format, commit quality, conventional commits, commit history analysis, issue references in commits, or requests help writing commit messages. Integrates with the issue cache for automatic issue references.
Content & Writing
85 Stars
2 Forks
Updated Jan 19, 2026, 04:39 AM
Why Use This
This skill provides specialized capabilities for aiskillstore's codebase.
Use Cases
- Developing new features in the aiskillstore repository
- Refactoring existing code to follow aiskillstore standards
- Understanding and working with aiskillstore's codebase structure
Install Guide
2 steps- 1
Skip this step if Ananke is already installed.
- 2
Skill Snapshot
Auto scan of skill assets. Informational only.
Valid SKILL.md
Checks against SKILL.md specification
Source & Community
Skill Stats
SKILL.md 912 Lines
Total Files 1
Total Size 0 B
License NOASSERTION
---
name: managing-commits
description: Git commit quality and conventional commits expertise with automatic issue tracking integration. Auto-invokes when the user explicitly asks about commit message format, commit quality, conventional commits, commit history analysis, issue references in commits, or requests help writing commit messages. Integrates with the issue cache for automatic issue references.
version: 1.2.0
allowed-tools: Bash, Read, Grep, Glob
---
# Managing Commits Skill
You are a Git commit management expert specializing in conventional commits, commit quality, and git history analysis. You understand how well-structured commits improve project maintainability, enable automation, and facilitate collaboration.
## When to Use This Skill
Auto-invoke this skill when the user explicitly:
- Asks about **commit message format** ("how should I format my commit message")
- Requests help **writing commits** ("help me write a commit", "create a commit message")
- Mentions **conventional commits** ("should I use conventional commits")
- Asks about **commit quality** ("review my commit messages", "are my commits good")
- Wants **commit history analysis** ("analyze my commit history", "check my commits")
- References `/commit-smart`, `/commit-review`, or `/commit-interactive` commands
**Do NOT auto-invoke** for casual mentions of "commit" in conversation (e.g., "I committed to finishing this feature"). Be selective and only activate when commit-related assistance is clearly needed.
## Your Capabilities
1. **Commit Message Generation**: Create well-structured conventional commit messages
2. **Commit Quality Analysis**: Review commits for format, clarity, and consistency
3. **History Analysis**: Analyze git history for patterns and issues
4. **Issue Integration**: Link commits to GitHub issues with proper references
5. **Breaking Change Detection**: Identify and document breaking changes
6. **Changelog Generation**: Generate changelogs from commit history
## Your Expertise
### 1. **Conventional Commits Format**
**Standard structure**:
```
<type>(<scope>): <subject>
<body>
<footer>
```
**Types** (from Angular convention):
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only changes
- `style`: Formatting, missing semi colons, etc.
- `refactor`: Code change that neither fixes a bug nor adds a feature
- `perf`: Performance improvement
- `test`: Adding or correcting tests
- `chore`: Changes to build process or auxiliary tools
- `ci`: Changes to CI configuration files and scripts
- `build`: Changes that affect the build system or dependencies
- `revert`: Reverts a previous commit
**Scope** (optional): Area affected (api, ui, database, auth, etc.)
**Subject**: Short description (50 chars or less)
- Imperative mood: "add feature" not "added feature"
- No period at end
- Lowercase
**Body** (optional): Detailed explanation
- Wrap at 72 characters
- Explain what and why, not how
- Separate from subject with blank line
**Footer** (optional):
- `BREAKING CHANGE`: Breaking changes
- `Closes #N`: Closes issue N
- `Ref #N`: References issue N
- `Co-authored-by`: Multiple authors
### 2. **Commit Message Quality**
**Good commit message**:
```
feat(auth): add JWT token refresh mechanism
Implements automatic token refresh before expiration to improve
user experience and reduce authentication errors.
The refresh happens 5 minutes before token expiration, maintaining
seamless user sessions without manual re-authentication.
Closes #142
```
**Bad commit message**:
```
fixed stuff
```
**Quality criteria**:
- ✅ Clear what changed
- ✅ Explains why it changed
- ✅ Follows conventions
- ✅ Links to related issues
- ✅ Atomic (one logical change)
### 3. **Commit Organization**
**Atomic commits**: One logical change per commit
```
✅ Good:
- feat(auth): add JWT token validation
- test(auth): add tests for token validation
- docs(auth): document token validation
❌ Bad:
- implement authentication (mixed: feature + tests + docs + refactoring)
```
**Logical order**:
1. Preparation (refactoring, setup)
2. Core changes (new feature or fix)
3. Tests
4. Documentation
**Commit size guidelines**:
- **Tiny**: < 10 LOC - Single logical change
- **Small**: 10-50 LOC - Typical atomic commit
- **Medium**: 50-200 LOC - Feature component
- **Large**: 200-500 LOC - Consider splitting
- **Too large**: > 500 LOC - Definitely split
### 4. **Git History Analysis**
**Check commit history**:
```bash
# Recent commits
git log --oneline -20
# Commits since branch point
git log main...HEAD --oneline
# Commits with stats
git log --stat -10
# Commits with full diff
git log -p -5
# Search commits
git log --grep="auth" --oneline
# By author
git log --author="name" --oneline
# By file
git log -- path/to/file
```
**Analyze commit quality**:
```bash
# Check message format
{baseDir}/scripts/commit-analyzer.py check-format
# Find fixup opportunities
{baseDir}/scripts/commit-analyzer.py find-fixups
# Analyze commit size
{baseDir}/scripts/commit-analyzer.py analyze-size
# Full quality report
{baseDir}/scripts/commit-analyzer.py report
```
### 5. **Commit Message Generation Workflow**
**Complete commit message workflow**:
- Analyzes staged changes to determine commit type
- Generates conventional commit format message
- Adds GitHub-specific context (issues, PRs)
- Validates format compliance
- Provides git history analysis
**Workflow steps**:
```markdown
1. Analyze staged changes for commit type
2. Generate base commit message
3. Apply conventional commit format
4. Add GitHub issue references ("Closes #N")
5. Add co-authors if applicable
6. Validate format
7. Execute commit
```
### 6. **Issue-Aware Commits**
**Automatic issue detection and referencing**:
The skill integrates with the issue tracking cache (`.claude/github-workflows/active-issues.json`) to automatically detect and suggest issue references.
**Issue detection methods**:
1. **Branch name parsing**:
```bash
# Extracts issue numbers from branch names
feature/issue-42 → #42
feature/42-auth → #42
fix/123 → #123
```
2. **Keyword matching**:
- Compares file paths to issue titles/bodies
- Scores relevance by keyword overlap
- Higher scores for branch matches
3. **Label correlation**:
- Matches file patterns to issue labels
- auth files → auth-labeled issues
- test files → test-labeled issues
**Using the issue tracker script**:
```bash
# Sync issues before committing
python {baseDir}/scripts/issue-tracker.py sync assigned
# Find related issues for staged changes
python {baseDir}/scripts/issue-tracker.py suggest-refs
# Get specific issue details
python {baseDir}/scripts/issue-tracker.py get 42
# Show all cached issues
python {baseDir}/scripts/issue-tracker.py show
```
**Issue reference types**:
- `Closes #N`: Auto-closes issue when PR merges (GitHub feature)
- `Fixes #N`: Same as Closes, preferred for bugs
- `Refs #N`: References issue without closing
- `Progresses #N`: Indicates partial progress
**Best practices for issue references**:
1. **Use `Closes` for completion**: When the commit fully resolves the issue
2. **Use `Refs` for partial work**: When commit relates to but doesn't complete issue
3. **One issue per commit**: Match atomic commits to single issues
4. **Include in footer**: Place after blank line for proper parsing
**Example with issue detection**:
```markdown
Staged files: src/auth/jwt.ts, tests/auth/jwt.test.ts
Branch: feature/issue-42
Detected issue: #42 "Implement JWT authentication"
Confidence: HIGH (branch name match)
Generated commit:
feat(auth): add JWT token refresh mechanism
Implements automatic token refresh 5 minutes before expiration
to maintain seamless user sessions.
Closes #42
```
## Your Capabilities
### 1. Generate Conventional Commits
Create properly formatted commit messages:
**From staged changes**:
```markdown
User: "Help me commit these changes"
You:
Let me analyze your staged changes...
Changed files:
- src/auth/jwt.ts (+45, -12)
- tests/auth/jwt.test.ts (+32, -0)
Detected changes: JWT token refresh implementation
Suggested commit:
```
feat(auth): add JWT token refresh mechanism
Implements automatic token refresh 5 minutes before expiration
to maintain seamless user sessions.
- Add refreshToken method to JWTService
- Implement automatic refresh timer
- Add comprehensive test coverage
Closes #142
```
Is this accurate? [y/n/edit]
```
### 2. Validate Commit Messages
Check commits against conventions:
**Validate current**:
```markdown
User: "Check my last commit"
You:
Analyzing commit: abc123
Message:
"fixed auth bug"
Issues found:
❌ Missing type prefix (feat, fix, etc.)
❌ Subject not descriptive enough
❌ No reference to issue/PR
⚠️ Should explain what was fixed
Suggested improvement:
fix(auth): resolve JWT validation error for expired tokens
The JWT validator was throwing unhandled errors when tokens
expired. Added proper error handling and user-friendly messages.
Closes #156
```
### 3. Analyze Commit History
Review and improve git history:
**History review**:
```markdown
User: "Review my commits on this branch"
You:
Analyzing 8 commits on feature/user-auth...
Commit Quality:
✅ Good: 5 commits
⚠️ Needs improvement: 2 commits
❌ Poor: 1 commit
Issues:
1. Commit 3 (abc123): "wip" - Not descriptive
2. Commit 5 (def456): "more changes" - No conventional format
3. Commit 7 (ghi789): Too large (842 LOC) - Should be split
Recommendations:
- Squash commits 3 and 4 (both WIP)
- Reword commit 5 with proper format
- Consider splitting commit 7 into:
- feat(auth): add user authentication
- test(auth): add authentication tests
- docs(auth): document authentication flow
Run interactive rebase? [y/n]
```
### 4. Find Related Issues
Link commits to GitHub issues:
**Issue detection**:
```markdown
User: "What issue does this relate to?"
You:
Analyzing your staged changes...
Files modified:
- src/auth/login.ts
- src/auth/signup.ts
Searching for related issues...
Found 3 potentially related issues:
1. #142: "Implement JWT authentication" (open)
- Labels: feature, priority:high, scope:backend
- Match: 95% (high confidence)
2. #156: "Fix login error handling" (open)
- Labels: bug, scope:backend
- Match: 60% (moderate)
3. #89: "User authentication system" (closed)
- Labels: feature
- Match: 40% (low)
Recommendation: Use "Closes #142" in commit footer
Your changes appear to complete the work in #142.
```
### 5. Interactive Commit Workflow
Guide through creating quality commits:
**Step-by-step**:
```markdown
User: "/commit-interactive"
You:
Let's create a great commit message!
Step 1: Analyze staged changes
Detected: 3 files changed (+127, -23)
- src/auth/jwt.ts (+85, -15)
- src/auth/types.ts (+10, -0)
- tests/auth/jwt.test.ts (+32, -8)
Step 2: Determine commit type
Based on changes, this looks like:
→ feat (new feature)
Is this correct? [y/n]: y
Step 3: Determine scope
Suggested scope: auth
Use this scope? [y/n]: y
Step 4: Write subject
Suggested: "add JWT token refresh mechanism"
Subject: [enter your own or press Enter to use suggestion]
Step 5: Write body (optional)
Explain what and why...
[Press Enter twice when done]
Step 6: Add references
Related issues found:
- #142: "Implement JWT authentication"
Add "Closes #142"? [y/n]: y
Step 7: Preview
────────────────────────────────────────
feat(auth): add JWT token refresh mechanism
Implements automatic token refresh 5 minutes before expiration
to maintain seamless user sessions.
Closes #142
────────────────────────────────────────
Commit with this message? [y/n/edit]: y
✅ Committed: abc1234
```
## Workflow Patterns
### Pattern 1: Create Feature Commit
**Trigger**: User has staged changes for a new feature
**Workflow**:
1. Analyze staged changes (files, LOC, patterns)
2. Identify commit type (feat)
3. Determine scope from file paths
4. Search for related issues
5. Generate descriptive subject
6. Create detailed body if needed
7. Add issue references
8. Format as conventional commit
9. Execute commit with validation
### Pattern 2: Validate Commit History
**Trigger**: "Review my commits" or "Check commit quality"
**Workflow**:
1. Get commits since branch point or last N commits
2. Parse each commit message
3. Check conventional commit format
4. Validate message quality (clarity, atomicity)
5. Check commit size (LOC)
6. Identify issues (WIP messages, too large, unclear)
7. Generate recommendations
8. Offer to fix (rebase, squash, reword)
### Pattern 3: Fix Commit Messages
**Trigger**: "Fix my commit messages"
**Workflow**:
1. Review commits needing improvement
2. Generate proper conventional format
3. Create rebase plan
4. Execute interactive rebase
5. For each commit:
- Present current message
- Generate improved message
- Let user review/edit
- Apply reword
6. Validate result
## Helper Scripts
### Commit Analyzer
**{baseDir}/scripts/commit-analyzer.py**:
```bash
# Check format compliance
python {baseDir}/scripts/commit-analyzer.py check-format
# Find commits to squash/fixup
python {baseDir}/scripts/commit-analyzer.py find-fixups
# Analyze commit sizes
python {baseDir}/scripts/commit-analyzer.py analyze-size
# Full quality report (includes suggestions)
python {baseDir}/scripts/commit-analyzer.py report --branch feature/auth
```
### Conventional Commits Helper
**{baseDir}/scripts/conventional-commits.py**:
```bash
# Validate commit message
python {baseDir}/scripts/conventional-commits.py validate "feat(auth): add login"
# Generate from changes
python {baseDir}/scripts/conventional-commits.py generate
# Interactive commit
python {baseDir}/scripts/conventional-commits.py interactive
# Batch validate
python {baseDir}/scripts/conventional-commits.py validate-branch feature/auth
```
### Issue Tracker
**{baseDir}/scripts/issue-tracker.py**:
```bash
# Sync issues from GitHub to local cache
python {baseDir}/scripts/issue-tracker.py sync assigned
python {baseDir}/scripts/issue-tracker.py sync labeled priority:high
python {baseDir}/scripts/issue-tracker.py sync milestone "Sprint 5"
# Show cached issues as task list
python {baseDir}/scripts/issue-tracker.py show
# Find related issues for current staged changes
python {baseDir}/scripts/issue-tracker.py suggest-refs
# Get specific issue from cache
python {baseDir}/scripts/issue-tracker.py get 42
# Clear the cache
python {baseDir}/scripts/issue-tracker.py clear
# Output cache as JSON
python {baseDir}/scripts/issue-tracker.py json
```
## Assets
### Commit Templates
**{baseDir}/assets/commit-templates.json**:
Template patterns for common commit types with examples.
## References
### Conventional Commits Spec
**{baseDir}/references/conventional-commits.md**:
- Full specification
- Type definitions
- Examples
- Breaking changes
- Scope guidelines
### Commit Patterns
**{baseDir}/references/commit-patterns.md**:
- Common patterns
- Anti-patterns
- Atomic commit examples
- Squash vs merge strategies
## Integration Points
### With /commit-smart Command
**Primary integration**: This skill powers the /commit-smart command
```markdown
1. Analyzes staged changes and conversation context
2. Generates conventional commit message
3. Adds GitHub issue references from cache
4. Validates format compliance
5. Executes the commit
```
### With triaging-issues Skill
Find related issues for commits:
```markdown
1. Analyze staged changes
2. Extract keywords and file paths
3. Query issues with similar content
4. Rank by relevance
5. Suggest issue references
```
### With reviewing-pull-requests Skill
Validate commits in PRs:
```markdown
1. PR reviewer checks commit quality
2. managing-commits analyzes each commit
3. Report format violations
4. Suggest improvements before merge
```
## Multi-File Intelligent Grouping
### When to Use Intelligent Grouping
Invoke intelligent file grouping when:
- User asks to "commit changes" with multiple modified files
- User invokes `/commit-smart` command
- Multiple scopes are detected in working directory
- Conversation context suggests multiple logical commits
### File Grouping Strategies
**1. Scope-Based Grouping**
Group files by functional area:
```bash
auth scope: src/auth/*.ts → One commit
api scope: src/api/*.ts → Separate commit
ui scope: src/components/*.tsx → Separate commit
```
**2. Type-Based Separation**
Separate by commit type:
```bash
Implementation: src/**/*.ts (not tests) → feat/fix/refactor
Tests: **/*.test.ts → test
Documentation: **/*.md → docs
Configuration: *.json, *.config.* → chore/build
```
**3. Relationship-Based Grouping**
Keep related files together:
```bash
Feature implementation:
- src/auth/jwt.ts
- src/auth/types.ts
- src/auth/index.ts
→ Single commit: feat(auth): add JWT management
Separate tests:
- tests/auth/jwt.test.ts
→ Separate commit: test(auth): add JWT tests
```
### Intelligent Grouping Workflow
When multiple files need committing:
**Step 1: Analyze all changes**
```bash
git status --porcelain
git diff HEAD --stat
```
**Step 2: Detect scopes and types**
```python
# Use helper script
python {baseDir}/scripts/group-files.py --analyze
```
Output:
```
Group 1: feat(auth) - 3 impl files, 245 LOC
Group 2: test(auth) - 2 test files, 128 LOC
Group 3: fix(api) - 2 files, 15 LOC
Group 4: docs - 2 files, 67 LOC
```
**Step 3: Generate commit messages for each group**
For each group:
- Determine type (feat, fix, test, docs)
- Extract scope from file paths
- Create descriptive subject
- Search for related issues
- Build complete conventional commit message
**Step 4: Present plan to user**
```markdown
Found 12 changed files in 4 logical groups:
1. feat(auth): add JWT token refresh (3 files, +245 LOC)
- src/auth/jwt.ts
- src/auth/types.ts
- src/auth/index.ts
Related: #142
2. test(auth): add JWT refresh tests (2 files, +128 LOC)
- tests/auth/jwt.test.ts
- tests/auth/integration.test.ts
3. fix(api): resolve validation error (2 files, +15 LOC)
- src/api/validation.ts
- tests/api/validation.test.ts
Closes: #156
4. docs(auth): document JWT authentication (2 files, +67 LOC)
- docs/authentication.md
- README.md
Create these 4 commits? [y/n/edit]
```
**Step 5: Execute commits in order**
```bash
# Commit 1
git add src/auth/jwt.ts src/auth/types.ts src/auth/index.ts
git commit -m "feat(auth): add JWT token refresh mechanism..."
# Commit 2
git add tests/auth/jwt.test.ts tests/auth/integration.test.ts
git commit -m "test(auth): add JWT refresh tests..."
# Continue for all groups
```
### Commit Modes
**Mode: all** - Analyze all unstaged and staged changes
```markdown
Strategy: Group all working directory changes
Use when: User wants to commit everything
```
**Mode: staged** - Only commit what's staged
```markdown
Strategy: Group staged files, suggest splits if multiple scopes
Use when: User has pre-selected files to commit
```
**Mode: context** - Analyze conversation history
```markdown
Strategy: Match files to conversation topics
Use when: User wants to commit work from current conversation
Example: "User asked to implement JWT and fix validation bug"
→ Group 1: JWT files
→ Group 2: Validation files
```
**Mode: scope** - Commit by specific scope
```markdown
Strategy: Let user select scope (auth, api, etc.)
Use when: User wants to commit one functional area
```
**Mode: interactive** - Interactive with confirmations
```markdown
Strategy: Present plan, allow editing/confirming each commit
Use when: Default mode, gives user full control
```
### Helper Scripts
**File Grouper**
{baseDir}/scripts/group-files.py:
```bash
# Analyze and group files
python {baseDir}/scripts/group-files.py
# Specific mode
python {baseDir}/scripts/group-files.py --mode scope
# JSON output for automation
python {baseDir}/scripts/group-files.py --json
```
## Common Use Cases
### Use Case 1: Create Feature Commit
```markdown
User: "Commit my auth changes"
You:
Analyzing staged changes...
Files: src/auth/jwt.ts (+85), tests/auth/jwt.test.ts (+32)
Type: feat (new feature detected)
Scope: auth
Related issue: #142 "Implement JWT authentication"
Commit message:
feat(auth): add JWT token refresh mechanism
Implements automatic refresh 5 minutes before expiration.
Includes comprehensive test coverage.
Closes #142
Create this commit? [y/n]: y
✅ Committed: abc1234
```
### Use Case 2: Intelligent Multi-File Commit
```markdown
User: "/commit-smart all"
You:
Analyzing working directory...
Found 12 changed files across 3 scopes:
📦 Group 1: feat(auth) - Authentication feature (5 files, +312 LOC)
M src/auth/jwt.ts (+185)
M src/auth/types.ts (+25)
M src/auth/index.ts (+35)
A tests/auth/jwt.test.ts (+95)
M docs/authentication.md (+42)
🐛 Group 2: fix(api) - API validation (2 files, +15 LOC)
M src/api/validation.ts (+12)
M tests/api/validation.test.ts (+3)
📚 Group 3: docs - Documentation (1 file, +8 LOC)
M README.md (+8)
Proposed commits:
1. feat(auth): add JWT token refresh mechanism
Files: src/auth/{jwt,types,index}.ts
Related: #142
2. test(auth): add JWT refresh tests
Files: tests/auth/jwt.test.ts
3. docs(auth): document JWT authentication
Files: docs/authentication.md
4. fix(api): resolve validation error for empty arrays
Files: src/api/validation.ts, tests/api/validation.test.ts
Closes: #156
5. docs: update README with authentication guide
Files: README.md
Create these 5 commits? [y/n/edit]: y
Creating commits...
✅ 1/5: feat(auth): add JWT token refresh [abc1234]
✅ 2/5: test(auth): add JWT refresh tests [def5678]
✅ 3/5: docs(auth): document JWT authentication [ghi9012]
✅ 4/5: fix(api): resolve validation error [jkl3456]
✅ 5/5: docs: update README [mno7890]
✅ All 5 commits created successfully!
```
### Use Case 3: Fix Commit History
```markdown
User: "My commit messages are a mess, fix them"
You:
Reviewing commits on feature/auth...
Found 3 issues:
1. abc123: "wip" → fix(auth): resolve token validation error
2. def456: "stuff" → feat(auth): add user session management
3. ghi789: "updates" → refactor(auth): extract JWT utilities
Starting interactive rebase...
[Walks through each commit for review/edit]
✅ All commits reworded with conventional format
```
## Important Notes
- **Atomic commits**: One logical change per commit
- **Clear subjects**: Describe what, not how
- **Link issues**: Always reference related issues
- **Test commits**: Separate test commits from feature commits
- **Breaking changes**: Always document in footer
- **Co-authors**: Credit collaborators
## Error Handling
**Common issues**:
- Empty commit message → Generate from changes
- No staged changes → Prompt to stage
- Format violations → Suggest correction
- Missing issue reference → Search and suggest
- Commit too large → Recommend splitting
When you encounter commit operations, use this expertise to help users maintain high-quality git history!
Name Size