pitzcarraldo/commit

Conventional Commit Skill

Overview

This skill automatically analyzes staged Git changes and creates commits following the Conventional Commits specification. It examines the changes, determines the appropriate commit type and scope, and generates a well-structured commit message without requiring user input.

Supported Commit Types

| Type | Purpose | Example | |------|---------|---------| | feat | New feature | Adding user authentication | | fix | Bug fix | Fixing null pointer exception | | docs | Documentation | Updating README | | style | Formatting changes | Code style, whitespace | | refactor | Code restructuring | Extract function to module | | perf | Performance | Optimize database queries | | test | Testing | Add unit tests | | build | Build system | Update dependencies | | ci | CI/CD | Modify GitHub Actions | | chore | Maintenance | Update tooling |

Commit Message Format

<type>(<scope>): <description>

[optional body explaining WHY the change was made]

[optional footer(s)]

Format Rules:

• Type: Required, lowercase, from supported types table
• Scope: Optional, component/module name in parentheses
• Description: Required, imperative mood, lowercase, no period, under 72 chars
• Body: Optional, wrapped at 72 characters, explains motivation
• Footer: Optional, for references or metadata

Author Policy:

• Do NOT add Co-Authored-By: Only the current user should be the author
• Claude assistance should not be credited in commit metadata

Workflow

1. Verify Git Repository

Check if we're in a git repository:

git rev-parse --git-dir 2>&1

Expected output:

• Success: .git or path to git directory
• Failure: "not a git repository" error

Error message format:

Error: Not in a git repository
Please initialize git with: git init

2. Check Staged Changes

Run these commands in parallel to gather context:

git diff --cached --stat
git diff --cached
git log --oneline -5

Purpose:

• --cached --stat: Summary of staged files
• --cached: Detailed line-by-line changes
• log --oneline -5: Recent commit messages for style consistency

If no staged changes:

No files are staged for commit.

Stage files with:
  git add <file>           # Stage specific file
  git add .                # Stage all changes
  git add -p               # Stage interactively

3. Analyze Changes

Determine commit type based on:

1. File patterns:

   • README.md, *.md in docs/ → docs
   • package.json, Gemfile → build
   • .github/workflows/ → ci
   • *_test.js, *_spec.rb → test

2. Change patterns:

   • New files/functions → feat
   • Bug keywords (fix, bug, issue) → fix
   • Refactor keywords (extract, move, rename) → refactor
   • Performance keywords (optimize, cache) → perf
   • Style keywords (format, lint) → style

3. Scope determination:

   • Extract from file paths (e.g., src/auth/ → auth)
   • Use module/component names
   • Omit if changes span multiple components

4. Description generation:

   • Use imperative mood: "add", "fix", "update"
   • Start with verb, lowercase
   • Be specific but concise
   • No period at end
   • Keep under 72 characters

4. Generate Commit Message

Basic commit (no body needed):

git commit -m "$(cat <<'EOF'
<type>(<scope>): <description>
EOF
)"

Complex commit (with body):

git commit -m "$(cat <<'EOF'
<type>(<scope>): <description>

Detailed explanation of WHY this change was made.
Wrap at 72 characters for readability.
Use multiple paragraphs if needed.
EOF
)"

When to include body:

• Complex refactoring that needs context
• Bug fixes requiring explanation of root cause
• Breaking changes that need migration notes
• Non-obvious design decisions

5. Create and Verify Commit

Create the commit:

git commit -m "$(cat <<'EOF'
[generated message]
EOF
)"

Verify the commit:

git log -1 --pretty=format:"%h - %s%n%n%b"

Display to user:

✓ Commit created successfully

[short hash] - [commit subject]

[commit body if present]

Output Format

All commit operations follow this consistent format:

Analyzing staged changes...

Files changed:
  [file list from git diff --cached --stat]

Creating commit with message:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
<type>(<scope>): <description>

[body]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Commit created: [hash]

Examples

Example 1: Simple Feature Addition

Staged changes:

+ src/auth/passwordReset.ts (new file)
+ 45 lines

Generated commit:

feat(auth): add password reset functionality

Example 2: Bug Fix with Context

Staged changes:

M src/api/userProfile.ts
- return user.profile
+ return user.profile || defaultProfile

Generated commit:

fix(api): handle null values in user profile endpoint

Previously the endpoint would crash when users had incomplete profiles.
Added fallback to default profile object to prevent null reference errors.

Example 3: Documentation Update

Staged changes:

M README.md
+ Installation section
+ 20 lines added

Generated commit:

docs: add installation instructions to readme

Example 4: Refactoring

Staged changes:

M src/utils/validation.ts
M src/components/Form.tsx
+ src/utils/validators.ts (new file)

Generated commit:

refactor(utils): extract validation logic into separate module

Moved reusable validators to dedicated module for better code organization
and to enable reuse across multiple components.

Example 5: Multiple File Changes

Staged changes:

M src/components/Button.tsx
M src/components/Input.tsx
M src/styles/global.css

Generated commit:

style: apply consistent formatting to component files

Technical Requirements

Required Tools

| Tool | Purpose | Check Command | |------|---------|---------------| | Git | Version control | git --version | | Git Config | User identity | git config user.name && git config user.email |

Minimum Versions

• Git: 2.0 or higher
• Bash: 4.0 or higher (for HEREDOC support)

Best Practices

1. Analyze recent commits to match repository's commit style
2. Keep descriptions concise but meaningful
3. Use scope consistently within a project
4. Add body for complex changes to explain reasoning
5. Group related changes in a single commit when logical
6. Review the generated message before confirming

Limitations

1. Single commit only: Creates one commit for all staged changes
2. No interactive editing: Commit message is generated automatically
3. English descriptions: Generates descriptions in English by default
4. No push operation: Only creates local commit, does not push to remote
5. No commit signing: Does not add GPG signatures automatically

Error Handling

Common Errors and Solutions

Error: Not a git repository

• Cause: Current directory is not initialized with git
• Solution: Run git init or navigate to a git repository

Error: No staged files

• Cause: No files added to staging area
• Solution: Stage files with git add <file> or git add .

Error: User identity unknown

• Cause: Git user.name or user.email not configured
• Solution: Configure with:

  git config --global user.name "Your Name"
  git config --global user.email "[email protected]"
  

Error: Empty commit message

• Cause: Commit message generation failed
• Solution: Ensure staged changes are readable with git diff --cached

Error: Hook failed

• Cause: Pre-commit hook or commit-msg hook rejected the commit
• Solution: Fix issues reported by hook or use --no-verify if appropriate

Advanced Usage

Breaking Changes

For breaking changes, add an exclamation mark after type/scope and include BREAKING CHANGE in footer.

Multiple Scopes

If changes affect multiple scopes but are tightly related, use comma-separated scopes.

Issue References

Include issue references in body or footer (e.g., Fixes #123 or Closes #456).

References

• Conventional Commits: https://www.conventionalcommits.org/
• Git Documentation: https://git-scm.com/doc
• Commit Message Guidelines: https://cbea.ms/git-commit/

Notes

• Commits are created locally only; use separate command to push
• Only the current user is credited as the author (no Co-Authored-By)
• Scope is optional but recommended for larger projects
• Description must use imperative mood (not past tense)
• Multi-line descriptions are not allowed (use body instead)
• The skill operates autonomously without prompting for input