Skill: Creating a Commit

When to Use This Skill

Use this skill for commit requests: "commit these changes", "create a commit", "save my work", "commit with message X".

Use other skills for: creating PRs (creating-pull-request), viewing history (git log directly).

Workflow Description

Enhances the standard Claude Code commit workflow with pre-flight checks and repository-aware enhancements. This skill adds mainline protection, conventional commits detection, and atomic context gathering, then delegates execution to Claude Code's default commit behavior.

This skill provides:

• Mainline branch protection (auto-creates feature branches)
• Conventional commits format detection
• Atomic context gathering scripts
• Repository type awareness (fork vs origin)

Claude Code default workflow handles:

• Commit message formatting (HEREDOC, line wrapping)
• Co-Authored-By footer (auto-enforced)
• Pre-commit hook failure handling
• Secrets detection warnings
• Git Safety Protocol enforcement

Extract from user request: commit message format ("use conventional commits" → force, default auto-detect), explicit message (if provided, else delegate to default for generation)

---

Phase 1: Gather Context (Optimized)

Objective: Collect all commit context in a single atomic operation.

Steps:

1. Run ${CLAUDE_PLUGIN_ROOT}/scripts/gather-commit-context.sh to collect all commit context

2. Parse the JSON response and handle results:

IF success: false:

Handle error based on error_type:

• clean_working_tree:

  • STOP: "Working tree is clean, nothing to commit"
  • Display: message field from response
  • EXIT workflow

• not_git_repo:

  • STOP: "Not in a git repository"
  • Display: message and suggested_action from response
  • EXIT workflow

• git_status_failed:

  • STOP: "Failed to retrieve git status"
  • Display: message from response
  • Suggested action: "Check repository integrity"
  • EXIT workflow

• Other errors:

  • STOP: Display error details
  • EXIT workflow

IF success: true:

Extract and store context:

{
  "current_branch": "branch name",
  "mainline_branch": "main",
  "is_mainline": false,
  "uses_conventional_commits": true,
  "conventional_commits_confidence": "high",
  "working_tree_status": {...},
  "staged_files": [...],
  "unstaged_files": [...],
  "untracked_files": [...],
  "file_categories": {...},
  "recent_commits": [...],
  "diff_summary": {...}
}

Validation Gate: Branch Protection

IF `is_mainline: false` (on feature branch):
  Continue to Phase 2

IF `is_mainline: true` (on mainline):
  Check user request and context:

  IF user explicitly stated commit to mainline is acceptable:
    Examples: CLAUDE.md allows mainline commits, request says "commit to main"
    INFORM: "Proceeding with mainline commit as authorized"
    Continue to Phase 2

  IF no explicit authorization:
    INVOKE: creating-branch skill
    WAIT for creating-branch skill to complete

    IF creating-branch succeeded:
      VERIFY: Now on feature branch (not mainline)
      RE-RUN Phase 1 (gather context again on new branch)
      Continue to Phase 2

    IF creating-branch failed:
      STOP immediately
      EXPLAIN: "Branch creation failed, cannot proceed with commit"
      EXIT workflow

Phase 1 complete. Continue to Phase 2.

---

Phase 2: Prepare Context for Delegation

Objective: Prepare hints and context to pass to the default Claude Code commit workflow.

Context to provide to default workflow:

• Conventional Commits Format: If uses_conventional_commits: true, note that this repository uses Conventional Commits format (<type>[scope]: <description>)

  • Common types: feat, fix, docs, style, refactor, perf, test, chore
  • Example: feat(auth): add JWT token refresh

• File Categories: From context - types of files changed (code, tests, docs, config)

• Recent Commit Style: From recent_commits - show 1-2 recent commits for style consistency

• Change Summary: From diff_summary - scale of changes (files, insertions, deletions)

Note: The default Claude Code commit workflow will:

• Generate the commit message (or use user-provided message)
• Apply proper formatting (HEREDOC, line wrapping, imperative mood)
• Add Co-Authored-By footer (auto-enforced by Claude Code)
• Detect and warn about potential secrets

Continue to Phase 3.

---

Phase 3: Delegate to Default Commit Workflow

Objective: Execute commit using Claude Code's default commit workflow with the context and hints from Phase 2.

System Workflow Delegation:

Proceed with the standard Claude Code commit workflow as defined in the system prompt. The system workflow includes:

1. Run git commands in parallel:

   • git status to see untracked files
   • git diff to see changes
   • git log to see recent commits for style

2. Analyze changes and draft commit message:

   • Consider the hints from Phase 2 (conventional commits format, file categories, recent style)
   • If repository uses Conventional Commits (uses_conventional_commits: true), use format <type>[scope]: <description>
   • Generate concise message (subject <50 chars, imperative mood, optional body wrapped at 72 chars)

3. Don't commit secrets:

   • Check for files like .env, *credentials*, *secret*, *.pem, *.key
   • Warn user if suspicious files detected

4. Stage and commit:

   • Run git add . (or specific files if user requested selective staging)

   • Create commit with HEREDOC format for proper multi-line handling:

     git commit -m "$(cat <<'EOF'
     <commit message>
     
     Co-Authored-By: Claude <noreply@anthropic.com>
     EOF
     )"
     

   • Note: Co-Authored-By footer is auto-enforced by Claude Code

5. Run git status after commit to verify success

Plan Mode: Auto-enforced read-only if active

Git Safety Protocol: Auto-enforced by Claude Code

• Hooks execute normally (--no-verify never used unless explicitly requested)
• If pre-commit hook fails, fix issue and create NEW commit (never amend)
• Git config never modified

This skill provided: Mainline protection, conventional commits detection, atomic context gathering

Continue to Phase 4 (Verification).

---

Phase 4: Verification

Objective: Confirm commit was created successfully and provide standardized report.

Steps:

1. Parse the git commit output from Phase 3, which has the format:

   [branch-name abc1234] Commit subject
    N files changed, M insertions(+), P deletions(-)
   

2. Extract commit details:

   • Branch name: From first line (between [ and first space after ))
   • Short hash: From first line (between branch name and ])
   • Subject: From first line (after ])
   • File stats: From second line

3. Display standardized report to user:

   ✓ Commit Completed Successfully
   
   **Commit:** <short_hash> \
   **Branch:** <branch_name> \
   **Subject:** <subject> \
   **Files Changed:** <file_count>
   

4. Verify: Compare subject to approved message from Phase 3; warn if differs (indicates hook modification)

5. Run git status to confirm working tree is clean

Workflow complete.