commit Skill

Cross-runtime: follow runtime compatibility for invocation, delegation, configuration precedence, state paths, and permissions.

You are helping commit changes for a pull request. Your task is to stage changes, generate a properly formatted commit message following project conventions, and handle pre-commit hooks.

Step 1: Load Configuration

Check for configuration and context:

# Check for config and context files
if [ -f ".git-workflow/config.yaml" ]; then CONFIG_PATH=".git-workflow/config.yaml"; elif [ -f ".claude/config.yaml" ]; then CONFIG_PATH=".claude/config.yaml"; else CONFIG_PATH=""; fi
if [ -f ".git-workflow/pr-context.json" ]; then CONTEXT_PATH=".git-workflow/pr-context.json"; elif [ -f ".claude/.pr-context.json" ]; then CONTEXT_PATH=".claude/.pr-context.json"; else CONTEXT_PATH=""; fi

Load from the resolved CONFIG_PATH (canonical first, legacy read-only fallback):

commits:
  format: "[{type}] {message} ({ticket})"
  types: [Feature, Fix, Hotfix, Refactor, Docs, Test, Chore]
  requireTicket: false
  ticketPattern: "^[A-Z]+-\\d+$"
attribution:
  enabled: false
  format: ""

Load from the resolved CONTEXT_PATH (canonical first, legacy read-only fallback):

{
  "ticket_id": "PROJ-1234",
  "type": "fix",
  "branch": "fix/proj-1234-description"
}

Default Values (when no config):

commits:
  format: "[{type}] {message} ({ticket})"
  types: [Feature, Fix, Hotfix, Refactor, Docs, Test, Chore]
  requireTicket: false
attribution:
  enabled: false

Step 2: Gather Context

If .pr-context.json doesn't exist or is incomplete, ask for missing information:

Missing Ticket ID

If commits.requireTicket: true or no ticket found in context:

Question: "What is the ticket ID for this commit?"

• Example: PROJ-1234, ENG-456
• Allow skipping if requireTicket: false

Missing Change Type

If type not found in context:

Question: "What type of change is this?"

Options: Feature, Fix, Hotfix, Refactor, Docs, Test, Chore

Step 3: Show Changed Files

Display what will be staged:

# Show git status
git status --short

# Show detailed diff stats
git diff --stat
git diff --cached --stat

Present to user:

Changes to be committed:

Staged:
  M src/file1.ts
  A src/file2.ts

Unstaged:
  M src/file3.ts
  M tests/file1.test.ts

Do you want to stage all changes, or select specific files?

Options:

1. Stage all changes (default)
2. Stage only unstaged changes
3. Select specific files
4. Review diff before staging

If user wants to review diff:

git diff

Step 4: Stage Files

Based on user's choice:

Stage All

git add -A

Stage Specific Files

git add {file1} {file2} ...

Confirmation

# Show what's staged
git diff --cached --name-only

Step 5: Generate Commit Message

Ask for Summary

Question: "What is the summary of your changes?"

Guidelines:

• Use imperative mood ("Add feature" not "Added feature")
• Be concise (50-72 characters)
• Focus on what and why, not how

Examples:

• "Add user authentication with OAuth2"
• "Fix memory leak in connection pool"
• "Update dependencies to latest versions"

Format Message

Apply commit format from config (default: [{type}] {message} ({ticket})):

Variable	Source	Example
{type}	Context or user input	Fix
{message}	User-provided summary	Fix login timeout
{ticket}	Context or user input	PROJ-1234

Type Capitalization:

• fix -> Fix
• feature -> Feature
• hotfix -> Hotfix

Result Examples:

• [Fix] Standardize token_info schema (PROJ-1234)
• [Feature] Add holder analysis endpoint (ENG-456)
• [Chore] Update dependencies (no ticket)

Handle Missing Ticket

If no ticket and format includes ({ticket}):

• If requireTicket: true: Prompt for ticket
• If requireTicket: false: Omit the ({ticket}) part

Without ticket: [Fix] Update dependencies
With ticket: [Fix] Update dependencies (PROJ-1234)

Step 6: Commit Changes

Create Commit

git commit -m "{formatted_commit_message}"

Important: Let pre-commit hooks run. Do NOT use --no-verify.

Handle Pre-commit Failures

If commit fails due to pre-commit hooks:

1. Identify the issue:

   # Check hook output for errors
   # Common issues: linting, formatting, type errors
   

2. Auto-fix if possible:

   # For ESLint/Prettier
   npm run lint:fix 2>/dev/null || pnpm lint:fix 2>/dev/null || yarn lint:fix 2>/dev/null
   
   # For Python
   black . 2>/dev/null || ruff format . 2>/dev/null
   

3. Re-stage fixed files:

   git add -A
   

4. Retry commit:

   git commit -m "{formatted_commit_message}"
   

5. If still failing:

   • Show the error to the user
   • Ask if they want to fix manually or skip hooks (not recommended)

Attribution (If Enabled)

If attribution.enabled: true in config, append the configured prose note to the commit body. The note must comply with repository commit rules and must not impersonate or add another commit author.

git commit -m "{message}

{attribution.format}"

Example:

[Fix] Update token schema (PROJ-1234)

This commit was created with assistance from an AI coding agent.

Note: Attribution is disabled by default.

Step 7: Update Context

Update .git-workflow/pr-context.json:

mkdir -p .git-workflow

{
  "ticket_id": "PROJ-1234",
  "ticket_url": "https://...",
  "branch": "fix/proj-1234-description",
  "type": "fix",
  "description": "Short description",
  "started_at": "2025-01-17T12:00:00Z",
  "commits": [
    {
      "hash": "abc123",
      "message": "[Fix] Summary (PROJ-1234)",
      "timestamp": "2025-01-17T12:30:00Z"
    }
  ],
  "last_commit_at": "2025-01-17T12:30:00Z"
}

Step 8: Confirm

Output a confirmation message:

Staged: {N} files
Committed: {commit_hash_short}
Message: {commit_message}

Next step: Run /finish to create the pull request

If there were pre-commit fixes:

Pre-commit hooks auto-fixed some issues:
- Formatted 3 files with Prettier
- Fixed 2 ESLint warnings

Staged: 5 files
Committed: abc1234
Message: [Fix] Update token schema (PROJ-1234)

Configuration Reference

Setting	Default	Description
commits.format	[{type}] {message} ({ticket})	Commit message format
commits.types	Feature, Fix, Hotfix...	Allowed commit types
commits.requireTicket	false	Require ticket ID
attribution.enabled	false	Add an AI assistance note
attribution.format	empty	Optional prose note

Error Handling

Scenario	Action
No changes to commit	Inform user, suggest checking git status
Pre-commit hook fails	Attempt auto-fix, show errors if still failing
Ticket required but missing	Prompt for ticket ID
Invalid commit type	Show allowed types, ask again
Context file missing	Proceed with user input, create new context
Git not in repo	Error with clear message

Common Commit Formats

The command supports various commit format patterns:

Conventional Commits

commits:
  format: "{type}: {message}"
  # Result: fix: update token schema

With Scope

commits:
  format: "{type}({scope}): {message}"
  # Result: fix(api): update token schema

Ticket Prefix

commits:
  format: "{ticket}: {message}"
  # Result: PROJ-1234: Update token schema

Custom Format

commits:
  format: "[{ticket}] {type} - {message}"
  # Result: [PROJ-1234] Fix - Update token schema

Examples

Standard Flow

User: /commit
Agent: [Shows staged/unstaged files]
Agent: Stage all changes? -> Yes
Agent: What is the summary? -> "Fix login timeout issue"
Result: Committed abc1234
        Message: [Fix] Fix login timeout issue (PROJ-1234)

With Auto-fix

User: /commit
Agent: [Stages files]
Agent: Summary? -> "Update API response"
[Pre-commit fails - ESLint errors]
Agent: Auto-fixing lint errors...
Agent: Fixed 3 files, retrying commit...
Result: Committed def5678
        Message: [Fix] Update API response (PROJ-1234)

No Context File

User: /commit
Agent: No context found. What's the ticket ID? -> "ENG-789"
Agent: What type of change? -> "Feature"
Agent: Summary? -> "Add dark mode support"
Result: Committed ghi9012
        Message: [Feature] Add dark mode support (ENG-789)