Git Conventional Commits

Git Conventional Commits Skill

Professional git commit workflow that enforces best practices and conventions.

Features

• Conventional Commits Format: Categorize commits by type (feat, fix, docs, style, refactor, perf, test, build, ci, chore)
• Message Validation: Adheres to the 7 rules of great git commits:
• Separate subject from body with a blank line
• Limit the subject line to 50 characters
• Capitalize the subject line
• Do not end the subject line with a period
• Use the imperative mood in the subject line
• Wrap the body at 72 characters
• Use the body to explain what and why vs. how
• Auto-Detection: Intelligently detects commit type based on file changes
• Preview & Confirmation: Shows formatted commit message before committing
• Multi-Language Support: English and Traditional Chinese (繁體中文)

Commit Types

When to Use

Reference this skill when you need to:

• Create a git commit with proper conventional format
• Ensure commit messages follow best practices
• Auto-detect the type of change being committed
• Preview and confirm commit messages before finalizing
• Support multiple commit message languages

Example Usage

# Invoke the skill when you have staged or unstaged changes
# The skill will:

# 1. Analyze git status and changes
#    - Shows what files are modified/added/deleted
#    - Automatically stages appropriate files

# 2. Auto-detect commit type based on changes
#    - feat: New features (new files, new APIs)
#    - fix: Bug fixes (fixes existing functionality)
#    - docs: Documentation changes only
#    - style: Formatting changes (no logic change)
#    - refactor: Code restructuring (no logic change)
#    - perf: Performance optimizations
#    - test: Test additions/fixes
#    - build: Build system/dependency changes
#    - ci: CI/CD configuration changes
#    - chore: Maintenance tasks

# 3. Generate commit message
#    - Subject line: "{type}: {description}" (max 50 chars)
#    - Body (optional): Explains what and why
#    - Follows all 7 rules of great commit messages

# 4. **DISPLAY PREVIEW** - Saves to session temporary directory
#    Location: ~/.copilot/session-state/{session_id}/commit_preview.txt
#    
#    Content (plain text, fully readable):
#    ════════════════════════════════════════════════════════════
#    feat: Add user authentication
#    
#    Implement JWT-based auth system with secure token handling
#    and automatic refresh logic. Prevents users from being logged
#    out unexpectedly during long sessions.
#    
#    ────────────────────────────────────────────────────────────
#    Files: 3 changed | +145 insertions | -8 deletions
#    ════════════════════════════════════════════════════════════
#    
#    Benefits of using session temp directory:
#    - Does NOT pollute your project directory
#    - Will NOT be tracked by git
#    - Automatically cleaned up when session ends

# 5. **REQUEST USER CONFIRMATION**
#    - User is asked: "Please review the commit message in
#      ~/.copilot/session-state/{session_id}/commit_preview.txt
#      Do you want to proceed?"
#    - Mandatory: User must explicitly approve
#    - Options: ✅ Yes, confirm and commit | ❌ No, cancel commit

# 6. **EXECUTE COMMIT** (Only if confirmed)
#    If user approves:
#    git commit -m "feat: Add user authentication" \
#               -m "Implement JWT-based auth system..."
#    
#    If user declines:
#    Commit cancelled by user. (No changes made)

Important: Preview & Confirmation

This skill ALWAYS shows a preview and waits for explicit user confirmation before committing.

This prevents accidental commits and ensures quality control. The preview step is mandatory and cannot be skipped.

Preview File Location: ~/.copilot/session-state/{session_id}/commit_preview.txt

• Automatically cleaned up when session ends
• Not tracked by git
• Easy to find in your session folder

Configuration

• Default Language: English
• Commit Body: Optional (automatically included when explaining "why" for complex changes)
• Message Validation: All messages validated against 7 rules before committing
• Preview Storage: Session temporary directory (not project directory)

Important: Preview & Confirmation

This skill ALWAYS shows a preview and waits for explicit user confirmation before committing.

This prevents accidental commits and ensures quality control. The preview step is mandatory and cannot be skipped.

Configuration

• Default Language: English
• Commit Body: Optional (automatically included when explaining "why" for complex changes)
• Message Validation: All messages validated against 7 rules before committing

Git Conventional Commit Handler (with Preview & Confirmation)

This handler implements the complete Conventional Commits workflow with mandatory preview before submission.

Workflow

Phase 1: Analyze Current State

Gather git status and determine what needs to be committed.

git status --short
git diff --cached
git diff

Phase 2: Stage Changes

Based on analysis, stage the appropriate files:

git add [files]

Phase 3: Determine Commit Type

Using the rules in rules/commit-types.md, detect the appropriate commit type from the staged changes:

• feat: New features (new files, new APIs)
• fix: Bug fixes (changes to existing functionality)
• docs: Documentation only (README, .md files)
• style: Formatting changes (no logic change)
• refactor: Code restructuring (no logic change)
• perf: Performance optimizations
• test: Test additions/fixes
• build: Build system changes (package.json, tsconfig, etc.)
• ci: CI/CD changes (.github/workflows)
• chore: Maintenance, configuration, no functional change

Phase 4: Generate Commit Message

Create the commit message following Conventional Commits format:

Format: {type}: {subject}

Rules (from rules/message-validation.md): 1. Subject line: max 50 characters (including type prefix) 2. Capitalize first letter after type 3. No period at end of subject 4. Use imperative mood (Add, Fix, not Added, Adds) 5. Optional body: explain WHAT and WHY, not HOW 6. Body: wrap at 72 characters 7. Blank line between subject and body

Examples:

• ✅ feat: Add user authentication system
• ✅ fix: Prevent race condition in event handler
• ❌ feat: add user authentication system (not capitalized)
• ❌ feat: Added user authentication system. (not imperative, has period)

Phase 5: Display Preview and Request Confirmation

Save the formatted preview to the session temporary directory, then request user confirmation.

File Storage Location: ~/.copilot/session-state/{session_id}/commit_preview.txt

Why session temporary directory?

• ✅ Does NOT pollute the project directory
• ✅ Will NOT be tracked by git
• ✅ Automatically cleaned up when session ends
• ✅ User can easily find it in their session folder
• ✅ Prevents accidental commits into version control

Preview Format:

════════════════════════════════════════════════════════════
                     COMMIT MESSAGE PREVIEW
════════════════════════════════════════════════════════════

{type}: {subject}

{body line 1}
{body line 2}
{body line 3}

────────────────────────────────────────────────────────────
Files: X changed | +Y insertions | -Z deletions
  • file1
  • file2
════════════════════════════════════════════════════════════

Display Implementation: 1. Write preview file to: ~/.copilot/session-state/{session_id}/commit_preview.txt 2. Show full subject line at the top 3. Show complete body text (all lines visible, no truncation) 4. Show statistics about changed files 5. Leave adequate whitespace so text is readable 6. Plain text format (no box drawing that might be truncated)

Then use ask_user tool with explicit choices and the file location in the question:

• Question: "Please review the commit message in ~/.copilot/session-state/{session_id}/commit_preview.txt. Do you want to proceed?"
• ✅ Yes, confirm and commit
• ❌ No, cancel commit

The user must be able to READ the entire commit message clearly before being asked to confirm.

Phase 6: Execute Commit (Only if Confirmed)

If user confirms, execute:

git commit -m "{type}: {subject}" -m "{body}"

If user cancels, abort with clear message without committing.

Example Flow

$ git status
  Changes not staged for commit:
    modified: src/auth.js

$ [Tool analyzes] → Detects "fix" type

$ [Tool generates]
  fix: Resolve token expiration bug

  Added refresh token logic to handle expired
  sessions automatically. This prevents users
  from being logged out unexpectedly.

$ [Tool displays preview and asks]
  ✅ Confirm and commit
  ❌ Cancel and edit

$ [User confirms]

$ git commit -m "fix: Resolve token expiration bug" -m "Added refresh token logic..."
  [main abc1234] fix: Resolve token expiration bug

Implementation Notes

• Always show preview before committing
• Wait for explicit user confirmation via ask_user tool
• Never auto-commit without user approval
• Validate message against all 7 rules before preview
• Support both English and Traditional Chinese message language

Commit Message Display and Preview Handler

This handler is responsible for formatting and displaying the commit message in a way that users can clearly see and understand before confirmation.

Display Format and Storage

File Storage Location: ~/.copilot/session-state/{session_id}/commit_preview.txt

Why session temporary directory?

• Does NOT pollute the project directory
• Will NOT be tracked by git
• Automatically cleaned up when session ends
• User can easily locate it in their session folder

The commit message MUST be displayed in a clear, readable format that shows: 1. The complete subject line 2. The complete body (if present) 3. Statistics about the changes

Plain Text Format (User-Friendly)

════════════════════════════════════════════════════════════
                     COMMIT MESSAGE PREVIEW
════════════════════════════════════════════════════════════

TYPE: SUBJECT

BODY TEXT LINE 1
BODY TEXT LINE 2
BODY TEXT LINE 3
... (all body text visible)

────────────────────────────────────────────────────────────
Files: 3 changed | +167 insertions | -6 deletions
  • .agents/skills/git-conventional-commits/SKILL.md
  • .agents/skills/git-conventional-commits/handlers/...
  • TEST.md
════════════════════════════════════════════════════════════

Display Rules

1. Storage: Save to ~/.copilot/session-state/{session_id}/commit_preview.txt 2. Header: Section label "COMMIT MESSAGE PREVIEW" 3. Subject Line: {TYPE}: {SUBJECT} on single line 4. Body Text: Plain text, each line fully visible, no truncation 5. Statistics: File counts and line changes 6. File List: Simple bullet list of changed files 7. Format: Plain text with simple line separators (no box drawing) 8. Whitespace: Adequate line breaks for scannability

Validation Before Display

Before displaying, validate:

• ✅ Subject line exists and is ≤ 50 characters
• ✅ Subject line is capitalized
• ✅ Subject line does not end with period
• ✅ Subject uses imperative mood
• ✅ Subject starts with valid commit type

Confirmation Mechanism

After clear display, use ask_user with these choices:

Question: "Please review the commit message saved in 
~/.copilot/session-state/{session_id}/commit_preview.txt
Do you want to proceed with this commit?"

Choices:
  - ✅ Yes, confirm and commit
  - ❌ No, cancel commit

Implementation Example

When the user sees the display, they must be able to: 1. Read the entire subject line clearly 2. Read the entire body (no truncation or "..." indicators) 3. See what files are being changed 4. Make an informed decision to confirm or cancel

Only proceed with git commit if user selects "✅ Yes, confirm and commit".

If user selects "❌ No, cancel commit", return control without executing git commit.

Commit Type Detection Rules

Auto-Detection Logic

Based on the git diff, automatically detect the most appropriate commit type:

feat (New Feature)

• New files added to src/, features/, or components/
• New functions or classes with significant functionality
• New exports or APIs added

fix (Bug Fix)

• Changes to existing src/ or component files
• Modifications to error handling
• Changes that fix broken functionality

docs (Documentation)

• Changes to .md files (README, docs/, etc.)
• Changes to code comments or docstrings
• JSDoc/TypeDoc updates
• No changes to actual source code

style (Formatting)

• Changes to formatting (spaces, tabs, semicolons)
• Changes to linting configuration
• No changes to code logic or meaning

refactor (Code Refactoring)

• Restructuring code without changing functionality
• Renaming variables/functions without changing behavior
• Reorganizing imports or file structure

perf (Performance)

• Optimizations to algorithms
• Caching implementations
• Bundle size reductions
• Performance-specific changes

test (Tests)

• Changes to test files (.test.ts, .spec.ts, __tests__/)
• Adding new test cases
• Fixing existing tests

build (Build Changes)

• Changes to package.json, package-lock.json
• Changes to build scripts (webpack, vite, tsconfig, etc.)
• Changes to dependency versions

ci (CI/CD Changes)

• Changes to .github/workflows/
• Changes to CI configuration files
• Changes to deployment configurations

chore (Maintenance)

• Changes to .gitignore
• Changes to configuration files that don't fit other categories
• Routine maintenance tasks
• Dependency updates that don't affect functionality

Detection Fallback

If auto-detection is uncertain, ask the user to select from the list above.

Message Validation Rules

The 7 Rules of a Great Git Commit Message

1. Separate subject from body with a blank line

• Subject line and body must be separated by exactly one blank line
• If no body, this rule is automatically satisfied

2. Limit the subject line to 50 characters

• Hard limit: 50 characters
• Warn if approaching limit (>45 chars)
• Format: {type}: {subject}
• Include the type and colon in the character count

3. Capitalize the subject line

• First letter after the type and colon must be capitalized
• Examples:
• ✅ feat: Add user authentication
• ❌ feat: add user authentication

4. Do not end the subject line with a period

• Subject line must NOT end with .
• Examples:
• ✅ feat: Add user authentication
• ❌ feat: Add user authentication.

5. Use the imperative mood in the subject line

• Use commands, as if requesting an action
• Present tense, not past tense
• Examples:
• ✅ feat: Add user authentication
• ✅ fix: Prevent race condition
• ❌ feat: Added user authentication
• ❌ feat: Adds user authentication

6. Wrap the body at 72 characters

• Each line in the body should not exceed 72 characters
• Helps with viewing in terminals and git log
• Only applies if body is present

7. Use the body to explain what and why vs. how

• Explain the motivation for the change
• Explain the impact/consequences
• Do NOT explain how the code works (that's what code is for)
• Use body for "what changed" and "why" - not implementation details

Validation Messages

• Subject too long: "Subject line exceeds 50 characters (current: {length}). Please shorten."
• Missing imperative mood: "Subject should use imperative mood (e.g., 'Add' not 'Added')"
• Period at end: "Subject line should not end with a period (.)"
• Not capitalized: "Subject line should start with a capital letter"
• Body too long: "Body line {line_number} exceeds 72 characters (current: {length})"

Language-Specific Rules

English (en)

• Standard English grammar and conventions
• Capitalize proper nouns

Traditional Chinese (zh-TW)

• Use simplified Chinese characters when appropriate
• No period (。) at the end of subject line (though Chinese typically uses it)
• Can use full-width punctuation in body