Git Commit with Auto-Changelog Skill

Automatically documents code changes in a searchable changelog when committing to git.

Purpose

Every commit creates a structured changelog entry that captures:

• •What changed (files, features, fixes)
• •Why (decision rationale)
• •Issues encountered
• •Dependencies added
• •Testing notes
• •Next steps

All entries are indexed in an auto-generated README for easy searching.

Usage

The skill activates automatically when you ask to commit changes:

"Commit these changes"
"Let's commit this work"
"Create a git commit with changelog for this session"

You can optionally provide a summary:

"Commit with message: Implement sectional evaluation system"

What This Skill Does

1. First-Time Setup (if changelog/ doesn't exist)

• •Creates changelog/ directory
• •Creates .changelog-keywords.txt with default tags
• •Creates initial README.md index
• •Logs the setup as first changelog entry

2. Every Commit

• •Analyzes git changes (git diff --stat)
• •Suggests keywords based on file paths
• •Prompts for changelog details (what, why, issues)
• •Generates timestamped markdown entry
• •Regenerates README index
• •Stages all changes (code + changelog)
• •Creates commit with descriptive message
• •Optionally pushes to remote

3. Maintains Searchability

• •Auto-updates README with one-line summaries
• •Groups entries by month
• •Creates keyword index at bottom
• •Enables Cmd+F searching across all sessions

Process Flow

1. •

   Check for changes

   • •Run git status
   • •If no changes, exit with message
   • •If changes exist, proceed
2. •

   First-time setup check

   • •Look for changelog/ directory
   • •If missing, create full structure
   • •Add setup entry to changelog
3. •

   Analyze changes

   • •Run git diff --stat for file summary
   • •Parse file paths to suggest keywords
   • •Count lines added/removed
4. •

   Prompt user for details

   • •Session description (or use provided message)
   • •Why these changes were made
   • •Issues encountered (optional)
   • •Keywords (show suggestions, allow editing)
   • •Dependencies added (if package.json changed)
5. •

   Generate changelog entry

   • •Create changelog/YYYY-MM-DD-HHMM-descriptive-slug.md
   • •Fill template with user responses
   • •Include git diff summary
   • •Add timestamp and session duration estimate
6. •

   Update index

   • •Use Glob to find all changelog/*.md files (exclude README.md)
   • •Read each file and parse headers (title, keywords, date)
   • •Group entries by month (YYYY-MM)
   • •Build keyword index with entry counts
   • •Write new README with monthly entries + keyword index
7. •

   Commit everything

   • •Stage all code changes: git add .
   • •Stage changelog files: git add changelog/
   • •Create commit with message
   • •Show commit SHA
8. •

   Push prompt

   • •Ask: "Push to remote? (Y/n)"
   • •If yes: git push origin [current-branch]
   • •Show push status

Keyword Auto-Suggestion

Based on file paths modified:

User can always add/remove keywords from suggestions.

Changelog Entry Template

# YYYY-MM-DD - Descriptive Title
**Keywords:** [KEYWORD1] [KEYWORD2] [KEYWORD3]
**Session:** [Time of day], Duration (~X hours)
**Commit:** [commit-sha]

## What Changed
- File: `path/to/file.tsx`
  - Added feature X
  - Modified component Y
- File: `path/to/migration.sql`
  - Created table Z
  - Added columns A, B, C

## Why
[User's explanation of decision rationale]

## Issues Encountered
[Problems hit during implementation, workarounds applied]

## Dependencies
[NPM packages added/updated, if any]

## Testing Notes
- What was tested: [description]
- What wasn't tested: [known gaps]
- Edge cases: [discovered issues]

## Next Steps
- [ ] Item 1
- [ ] Item 2

Example Session

You: Let's commit this work

Skill analyzing changes...

📊 Changes detected:
  src/api/users/controller.ts
  src/models/user.ts
  src/components/UserProfile.tsx
  tests/users.test.ts
  (8 files changed, 234 insertions(+), 67 deletions(--)

Describe this session (or press Enter for AI summary):
> Add user profile customization feature

Why these changes?
> Users requested ability to customize their profiles. Added avatar upload, bio field, and social links. Integrated with existing authentication system.

Any issues encountered? (optional)
> Avatar upload needed file size validation. Initially tried client-side only, but added server-side validation for security.

Suggested keywords: [BACKEND] [API] [COMPONENTS] [UI] [TESTING]
Modify keywords (or press Enter to accept):
> [add: FEATURE]

Final keywords: [BACKEND] [API] [COMPONENTS] [UI] [TESTING] [FEATURE]

Dependencies changed:
  Added: multer@1.4.5-lts.1 (file upload middleware)

Testing notes (what was tested):
> Tested avatar upload with various file sizes and formats. Verified bio field validation (max 500 chars). Checked social link URL validation.

What wasn't tested? (optional)
> Edge cases for international characters in bio field

Next steps (tasks remaining):
> - Add internationalization for bio field
> - Implement avatar image optimization
> - Update API documentation

✅ Created changelog/2025-01-15-1430-user-profile-customization.md
✅ Updated changelog/README.md (3 total entries)
✅ Staged 10 files (code + changelog)

Commit message:
"feat: Add user profile customization feature

- Added avatar upload with validation (client + server)
- Implemented bio field with 500 char limit
- Added social links section with URL validation
- Integrated with existing auth system

Added multer dependency for file uploads."

Create commit? (Y/n): y

✅ Committed as a7f3c9e

Push to origin/main? (Y/n): y

✅ Pushed successfully

📝 Changelog updated: changelog/2025-01-15-1430-user-profile-customization.md
🔍 Search keywords: [BACKEND] [API] [COMPONENTS] [UI] [TESTING] [FEATURE]

Files Created by Skill

On First Use

changelog/.changelog-keywords.txt:

# Common Keywords
[FRONTEND]
[BACKEND]
[DATABASE]
[API]
[UI]
[COMPONENTS]
[MODELS]
[ROUTING]
[HOOKS]
[STYLING]
[TESTING]
[BUG_FIX]
[FEATURE]
[REFACTOR]
[PERFORMANCE]
[SECURITY]
[DEPLOYMENT]
[INFRA]
[DOCUMENTATION]
[DEPENDENCIES]
[CONFIG]
[MIGRATION]

# Project-Specific (auto-appended as used)

changelog/README.md: Auto-generated index (regenerated after every commit)

After Each Commit

changelog/YYYY-MM-DD-HHMM-descriptive-slug.md: Filled template with session details (timestamp prevents collisions across branches)

Configuration

Skip Changelog (for trivial changes)

Say: "Commit without changelog: Fix typo in README"

Commits without creating changelog entry (use sparingly).

Amend Last Entry

Say: "Amend the last changelog entry with these changes"

Updates most recent changelog entry instead of creating new one (if continuing same session).

Tools Used

• •Bash - Git operations (status, diff, add, commit, push)
• •Read - Parse existing changelog entries
• •Write - Create new entries and update index
• •Grep - Search for keywords in existing entries (for duplicate detection)

Error Handling

No changes to commit:

❌ No changes detected. Nothing to commit.

Merge conflict in changelog:

⚠️ Merge conflict in changelog/README.md
Resolve manually and ask to commit again

Push failed:

❌ Push failed (branch not up to date)
Pull latest changes and try again

Best Practices

DO:

• •✅ Create entry for every feature, bug fix, or meaningful change
• •✅ Be specific in "What Changed" (file paths, function names)
• •✅ Explain "Why" decisions were made
• •✅ Document failed experiments (valuable context!)
• •✅ Add new keywords to vocabulary when needed

DON'T:

• •❌ Use for typo fixes (say "commit without changelog")
• •❌ Use generic descriptions ("made changes")
• •❌ Skip "Why" section (most important for future you)
• •❌ Forget to test before committing

Future Enhancements

Planned:

• •Search functionality: "Search changelog for [keyword]"
• •Stats reporting: "Show changelog statistics"
• •PR integration: Copy changelog to PR description
• •Auto-detect WIP commits and suggest skipping changelog

Notes

• •Changelog entries are immutable - never revised after creation
• •README is auto-generated - do not edit manually
• •Keywords are case-sensitive by convention (use UPPERCASE)
• •One entry per work session (not per commit if doing multiple quick commits)
• •If continuing work on same feature same day, ask to amend the last entry to update it
• •Merge-friendly: Timestamps in filenames prevent collisions across branches
• •After merging branches, ask Claude to regenerate the index if needed