Commit Changes Skill Skill

Commit Changes Skill

Purpose

Create well-structured git commits following conventional commits format with project-aware module emojis. This skill analyzes changes, crafts meaningful commit messages, and ensures commits are atomic and purposeful.

Natural Language Triggers

This skill activates when the user says things like:

"Commit these changes"
"Create a commit"
"Commit this"
"Save my changes"
"Make a commit for this work"
After completing a scratchpad task: "Done with this task, commit it"

Workflow Execution

Phase 1: Gather Context (Parallel)

Execute these in parallel for efficiency:

Project Context:
- Read project's CLAUDE.md for module emojis and conventions
- Identify current development phase/priorities
Git Context:
- git status - See staged/unstaged changes
- git diff --cached - Review staged changes (if any)
- git diff - Review unstaged changes
- git branch --show-current - Current branch
- git log --oneline -5 - Recent commits for style reference

Phase 2: Analyze Changes

Categorize Changes:
- Which files are modified/added/deleted?
- Which module(s) are affected?
- What type of change is this? (feat, fix, refactor, docs, etc.)
Staging Decision:
- If nothing staged but changes exist: Determine what should be staged together
- Group logically related changes
- Don't mix unrelated changes in one commit
- If multiple logical changes exist, use AskUserQuestion to ask which to commit first
Exclude Workflow Artifacts:
- NEVER stage or commit SCRATCHPAD_*.md files (working implementation plans)
- NEVER stage or commit SESSION_LOG_*.md files (session transcripts)
- If these appear in git status, ignore them — they are ephemeral workflow files
Validate Commit-Worthiness:
- Ensure changes represent one logical unit of work
- Check for debugging code, console.logs, temp files
- Verify no secrets or sensitive data included

Phase 3: Craft Commit Message

Format:

{module emoji}{change type emoji} {type}({scope}): {description}

{optional body explaining what and why}

Components:

Module Emoji: From project's CLAUDE.md
- Check ## Project Modules section for project-specific emojis
- Default examples: 🌐 api, 🎨 frontend, 🗄️ database, 🔐 auth, 📚 docs
- Use the most specific module that applies
Change Type Emoji:
- ✨ feat: New feature
- 🐛 fix: Bug fix
- 📝 docs: Documentation
- 💄 style: Formatting/style
- ♻️ refactor: Code refactoring
- ⚡️ perf: Performance improvements
- ✅ test: Tests
- 🔧 chore: Tooling, configuration
- 🚀 ci: CI/CD improvements
- 🔥 fix: Remove code or files
- 🎨 style: Improve structure/format
- 🚑️ fix: Critical hotfix
- 🎉 chore: Begin a project
- 🏗️ refactor: Architectural changes
- 🏷️ feat: Add or update types
- ⚰️ refactor: Remove dead code
Type: Conventional commit type (feat, fix, docs, style, refactor, perf, test, chore, ci)
Scope: Module name from CLAUDE.md (e.g., api, frontend, skills)
Description:
- Imperative mood ("Add feature" not "Added feature")
- No period at end
- Under 50 characters
- Focus on capability/value added
Body (optional):
- Explain what and why, not how
- Context for the change
- Reference issue numbers if applicable

Phase 4: Confirm with User

Use AskUserQuestion to confirm the commit:

AskUserQuestion:
  question: "Ready to commit with this message?"
  header: "Commit"
  options:
    - label: "Yes, commit"
      description: "Create the commit with this message"
    - label: "Edit message"
      description: "I want to modify the commit message"
    - label: "Stage more files"
      description: "I need to include additional files"
    - label: "Cancel"
      description: "Don't commit right now"

Display the proposed commit message clearly before asking.

Phase 5: Execute Commit

Stage files (if not already staged):
```
git add <files>
```
Create commit using HEREDOC for proper formatting:
```
git commit -m "$(cat <<'EOF'
{module emoji}{type emoji} {type}({scope}): {description}

{body if present}
EOF
)"
```
IMPORTANT: Do NOT add Claude attribution (e.g., "Co-Authored-By: Claude") to commit messages.
Confirm success:
```
git log -1 --oneline
```

Phase 6: Report Result

Display:

✓ Committed: {short hash} {commit message first line}

📊 Stats: {files changed}, {insertions}+, {deletions}-

🌿 Branch: {branch-name}

Smart Staging Logic

When unstaged changes exist across multiple areas:

Single logical change: Stage all related files automatically

Multiple logical changes: Present options via AskUserQuestion:

question: "Multiple changes detected. Which to commit first?"
options:
  - "Module A changes (3 files)"
  - "Module B changes (2 files)"
  - "All changes together"
  - "Let me specify"

Mixed concerns: Warn and suggest splitting:
- "These changes span unrelated modules. Recommend separate commits."

Quality Checks

Before committing, verify:

[ ] No SCRATCHPAD_*.md or SESSION_LOG_*.md files staged
[ ] No console.log or debug statements (unless intentional)
[ ] No TODO comments that should be addressed first
[ ] No secrets, API keys, or sensitive data
[ ] Changes are complete (no half-finished work)
[ ] Commit message accurately describes changes

Error Handling

Nothing to Commit

If no changes exist:

ℹ️ No changes to commit.
   Working tree is clean.

Merge Conflicts

If conflicts exist:

⚠️ Cannot commit: merge conflicts present.
   Resolve conflicts first, then commit.

Detached HEAD

If in detached HEAD state:

⚠️ Warning: You're in detached HEAD state.
   Consider creating a branch before committing.

Integration with Other Skills

Called by:

do-work skill - After completing each scratchpad task
User directly via natural language

Works with:

Project CLAUDE.md - Module emojis and conventions
Scratchpad - Context for what was being worked on

Project-Specific Adaptations

The skill reads the project's CLAUDE.md to determine:

Module names and their emojis
Commit message conventions (if custom)
Scope naming patterns

Example from a project CLAUDE.md:

## Project Modules
- **api** 🌐: REST API endpoints
- **frontend** 🎨: React UI components
- **database** 🗄️: Database layer

This skill would then use 🌐 for api changes, 🎨 for frontend changes, etc.

Best Practices

✅ DO:

Create atomic commits (one logical change)
Write meaningful commit messages
Reference issues when applicable
Stage related files together
Use project-specific module emojis

❌ DON'T:

Commit unrelated changes together
Use vague messages like "updates" or "fixes"
Include debugging code
Commit secrets or credentials
Skip the body when context is needed
Add Claude attribution to commit messages
Commit SCRATCHPAD_.md or SESSION_LOG_.md files

Version: 1.0.0 Last Updated: 2025-12-29 Maintained By: Escapement Converted From: commands/commit.md

Agent Skills: Commit Changes Skill

Install this agent skill to your local

Skill Files