git-commit-with-auto-changelog

Automatically documents code changes in a searchable changelog when committing to git. Creates structured entries with what/why/issues. Use when user asks to commit changes to git.

⭐2stars🔀1forks📁View on GitHub🕐Updated Oct 22, 2025

When & Why to Use This Skill

The Git Commit with Auto-Changelog skill streamlines the software development lifecycle by automating the creation of structured, searchable changelogs during the git commit process. It leverages AI to analyze code diffs and capture critical context—including the rationale behind changes, encountered issues, and dependencies—ensuring project history is meticulously documented and easily navigable through an auto-generated index.

Use Cases

  • Automated Project History: Maintain a professional and detailed changelog without manual effort, ensuring every commit is accompanied by a clear explanation of 'what' and 'why'.
  • Technical Debt & Decision Tracking: Document the rationale behind specific implementation choices and workarounds, providing invaluable context for future maintenance and team handovers.
  • Searchable Knowledge Base: Utilize the auto-generated README and keyword indexing to quickly locate past features, bug fixes, or architectural changes using simple search tools.
  • Streamlined Workflow: Consolidate git staging, diff analysis, documentation, and committing into a single interactive AI-driven session to increase developer productivity.
nameGit Commit with Auto-Changelog
descriptionAutomatically documents code changes in a searchable changelog when committing to git. Creates structured entries with what/why/issues. Use when user asks to commit changes to git.

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:

File Pattern Suggested Keywords
**/migrations/*.sql [DATABASE] [MIGRATION]
**/models/** [DATABASE] [MODELS]
**/api/**, **/functions/** [BACKEND] [API]
**/components/** [COMPONENTS] [UI]
**/pages/**, **/routes/** [FRONTEND] [ROUTING]
**/hooks/**, **/composables/** [FRONTEND] [HOOKS]
**/styles/**, *.css, *.scss [STYLING] [UI]
package.json, requirements.txt, Cargo.toml [DEPENDENCIES]
.env*, *.config.* [CONFIG]
*.test.*, *.spec.*, **/__tests__/** [TESTING]
README*, docs/** [DOCUMENTATION]
Dockerfile, *.yml, *.yaml [DEPLOYMENT] [INFRA]

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