Git Commit Message Generator

Purpose

When This Skill Activates

• When

  /commit-msg

  command is invoked
• When invoked from a

  commit-msg

  /

  prepare-commit-msg

  hook (if installed)
• When user requests commit message suggestions
• When analyzing changes before creating a commit

Core Capabilities

• Parse

  git diff --staged

  output
• Identify modified, added, and deleted files
• Analyze code changes (additions, deletions, modifications)
• Detect patterns across multiple files

• Determine commit type from changes:

  • feat

    : New features or functionality

  • fix

    : Bug fixes

  • security

    : Security fixes or hardening

  • refactor

    : Code restructuring without behavior change

  • docs

    : Documentation changes

  • style

    : Formatting, whitespace, code style

  • test

    : Adding or modifying tests

  • chore

    : Build process, dependencies, tooling

  • perf

    : Performance improvements

  • ci

    : CI/CD configuration changes

  • build

    : Build system changes

  • revert

    : Reverting previous commits

• Infer scope from file paths and patterns:
  • Directory names (e.g.,

    api

    ,

    auth

    ,

    ui

    )
  • File name patterns (e.g.,

    *.test.js

    →

    tests

    )
  • Framework conventions (e.g.,

    components/

    ,

    services/

    )

• Format:

  type(scope): description

• Enforce tier limits: Tier 1 summary max 50 chars; Tier 2/3 summary max 72 chars (ideal 50)
• Use imperative mood ("add" not "added")
• Focus on "what" and "why", not "how"
• Provide 2-3 alternative suggestions

Tier System: Smart Format Enforcement

Tier 1: Critical Commits (feat, fix, perf, security)

type(scope): summary line (max 50 chars)

- Detailed description point 1
- Detailed description point 2
- Detailed description point 3

This change [impact statement describing user-facing benefit or risk addressed].

Affected files/components:
- path/to/file1
- path/to/file2

Tier 2: Standard Commits (refactor, test, build, ci)

type(scope): summary line (max 72 chars)

Brief explanation of what changed and why (1-2 sentences).

Files: path/to/file1, path/to/file2

Tier 3: Minor Commits (docs, style, chore)

type(scope): summary line (max 72 chars)

[Optional: Additional context if helpful]

Workflow

1. Get staged changes (staged only, not working tree):
   - git diff --staged --name-status
   - git diff --staged --stat
   - git diff --staged
2. Load config → frameworks/shared-skills/skills/git-commit-message/config.yaml
3. Analyze changes:
   - Count files modified/added/deleted
   - Identify primary change type using analysis patterns
   - Detect scope from project structure (config.yaml)
   - Determine tier (1/2/3) based on commit type
   - Extract key modifications
4. Generate commit messages:
   - Apply tier-appropriate format
   - Primary suggestion (best match)
   - Alternative 1 (different scope/angle)
   - Alternative 2 (broader/narrower focus)
5. Validate against rules:
   - Check forbidden patterns
   - Verify required elements present
   - Ensure length limits
6. Present to user with explanation and tier info

Optional Modes (If Supported By The Caller)

• --validate "<message>"

  : Validate a commit message without generating suggestions (format/type/scope/length/forbidden patterns; then report required Tier 1/2/3 elements if missing).

• --tier <1|2|3>

  : Force the tier format (overrides auto-detection).

• --interactive

  or

  -i

  : Ask for confirmation of type, scope, and summary before final output.

Output Format

[NOTE] Suggested Commit Messages (based on X files changed)

PRIMARY:
feat(api): add user authentication endpoints

ALTERNATIVES:
1. feat(auth): implement JWT token validation
2. feat: add user authentication system

ANALYSIS:
- 3 files modified in src/api/
- New functions: authenticateUser, generateToken
- Primary change: new feature (authentication)
- Scope detected: api/auth

Conventional Commits Quick Reference

• feat

  : User-facing features or API additions

• fix

  : Corrects incorrect behavior

• refactor

  : Improves code without changing behavior

• docs

  : README, comments, documentation files

• style

  : Formatting only (prettier, eslint --fix)

• test

  : Test files or test utilities

• chore

  : Build scripts, package updates, config

• perf

  : Measurable performance improvements

• ci

  : GitHub Actions, CircleCI, build pipelines

• Use lowercase
• Be specific but not too narrow
• Match your project's module structure
• Omit if changes span multiple unrelated areas

• Start with lowercase verb
• No period at the end
• Be specific and concise
• Focus on user impact for

  feat

  and

  fix

Edge Cases

• Suggest splitting into separate commits
• If forced to combine, use broader scope or omit scope

• Append exclamation mark after type/scope (example: feat(api)!: change auth flow)
• Include BREAKING CHANGE in body (handled by user)

• Use

  chore(wip): description

  or

  feat(experimental): description

• Detect and warn: "No staged changes detected"
• Suggest

  git add

  commands

Integration Points

/commit-msg

Best Practices

1. Analyze context: Look at file paths, function names, import statements
2. Prioritize clarity: Prefer obvious descriptions over clever ones
3. Respect conventions: Follow project's existing commit patterns if detected
4. Avoid hallucination: Only describe what's actually in the diff
5. Be concise: 50 chars is ideal, 72 is maximum for first line

Example Analyses

Files: src/components/UserProfile.tsx, src/components/UserProfile.test.tsx
Changes: +120 lines, component definition, props interface, tests
Message: feat(components): add UserProfile component

Files: src/api/auth.ts
Changes: -5 +8 lines, fix token expiration check
Message: fix(auth): correct token expiration validation

Files: README.md, docs/api.md
Changes: +45 lines documentation
Message: docs: update API documentation and README

Files: package.json, package-lock.json
Changes: version bumps for eslint, typescript
Message: chore(deps): update eslint and typescript

Analysis Patterns: Smart Type Detection

feat Detection

• New files created (especially in src/, components/, api/)
• New functions/classes exported (

  export function

  ,

  export class

  )
• New API routes (

  app.get

  ,

  router.post

  , etc.)
• New assets/skills (in .claude/, custom-gpt/, etc.)
• Threshold: 20+ lines added typically indicates feature

fix Detection

• Test file changes (often indicates bug reproduction)
• New conditionals (validation fixes)
• Error handling additions (

  try

  ,

  catch

  ,

  throw

  )
• Input validation (

  validate

  ,

  sanitize

  ,

  check

  )
• Commit message hints: Words like "bug", "issue", "error", "crash"

refactor Detection

• Balanced changes (similar additions and deletions)
• Function renames/moves (same logic, different location)
• No new features or fixes
• Test coverage unchanged
• Keywords: "extract", "move", "rename", "reorganize"

docs Detection

• File patterns:

  .md

  ,

  .txt

  ,

  README

  ,

  CHANGELOG

  ,

  /docs/

• Pure documentation changes (no code modifications)
• Mixed code+docs: Prefer code type, note docs in description

test Detection

• File patterns:

  test.js

  ,

  spec.ts

  ,

  __tests__/

  ,

  /tests/

• Test framework patterns:

  describe

  ,

  it

  ,

  test

  ,

  expect

  ,

  assert

style Detection

• CSS/styling files:

  .css

  ,

  .scss

  ,

  .sass

  ,

  .less

• Formatter configs:

  prettier

  ,

  eslint

• Whitespace-only changes
• Keywords: "formatting", "indent", "whitespace"

chore Detection

• Dependency files:

  package.json

  ,

  requirements.txt

  ,

  Gemfile

• Lock files:

  package-lock.json

  ,

  yarn.lock

• Config files:

  .gitignore

  ,

  .env

• Keywords: "dependency", "deps", "upgrade", "bump"

Configuration

config.yaml

• Scope mapping: Maps directory patterns to scope names (e.g.,

  frameworks/claude-code-kit/**

  →

  claude-kit

  )
• Tier rules: Defines which commit types require which tier format
• Forbidden patterns: Blocks commits with generic messages or assistant/tool attribution
• Analysis patterns: Customizes type detection logic for your codebase
• Validation mode:

  strict

  (block),

  warning

  (warn), or

  disabled

Forbidden Patterns (Validation)

Generic/Vague Messages

• [FAIL] "Update files" → [OK] "docs: update API reference"
• [FAIL] "Fix stuff" → [OK] "fix(auth): correct token validation"
• [FAIL] "Change code" → [OK] "refactor(utils): simplify date formatting"

Assistant/Tool Attribution (Per Repository Policy)

• [FAIL] "Generated with Claude Code"
• [FAIL] "Co-Authored-By: Claude noreply@anthropic.com"
• [FAIL] Any assistant/tool attribution in commit messages

Work-in-Progress Markers

• [WARNING] "WIP: feature" (warning - should be squashed before merge)
• [WARNING] "temp: quick fix" (warning - should be squashed)

Missing Type

• [FAIL] Commits without type prefix (feat, fix, docs, etc.)

Error Handling

• No staged changes: Run

  git status

  and guide user to

  git add

  files
• Binary files only: Note that commit message should mention file types
• Merge conflicts: Detect and suggest

  chore: resolve merge conflicts

• Git not available: Graceful failure with helpful error message
• Forbidden pattern detected: Show error with examples and block commit (strict mode)
• Missing required elements: List what's missing based on tier requirements
• Length exceeded: Show character count and suggest shortening

Integration with Repository

• CLAUDE.md reference: Mandatory skill usage before commits
• config.yaml: Project-specific scope mappings and rules
• Pre-commit hook: Automatic activation before git commits
• CONTRIBUTING.md: Commit guidelines for contributors

Commit Message Template

type(scope): summary

Security-Sensitive Commits

Key Sections

• Pre-Commit Security Checklist — Secrets detection, prohibited patterns
• Security-Related Commit Types — Security fix, enhancement, configuration
• Accidental Secret Commits — Immediate response, rotation, history cleanup
• Sensitive File Patterns — .gitignore templates, files that should never be committed
• Audit Trail Requirements — CVE, CVSS, CWE metadata for security commits

Do / Avoid

GOOD: Do

• Run secrets scan before every commit
• Rotate secrets immediately if exposed
• Use environment variables for credentials
• Document security fixes with CVE/CVSS
• Require security team review for auth changes
• Keep .gitignore updated for secret patterns

BAD: Avoid

• Committing secrets "temporarily"
• Using hardcoded credentials in tests
• Storing real credentials in example files
• Assuming deleted secrets are safe
• Committing before secrets scan completes
• Using generic commit messages for security fixes

Anti-Patterns

Optional: AI/Automation

Note: AI suggestions should preserve human intent.

• Commit message suggestions — Draft from diff analysis
• Type detection — Pattern-based commit type inference
• Scope detection — Auto-detect from changed paths

Bounded Claims

• AI-generated messages need human review and modification
• Automated type detection may miss context
• Security commits always need human judgment