README.md (5085B)
1 # Commit Work 2 3 A comprehensive skill for creating high-quality, production-ready git commits that are easy to review, safe to ship, and follow best practices. 4 5 ## Purpose 6 7 This skill helps you create well-crafted git commits by: 8 - Ensuring only intended changes are included 9 - Splitting work into logically scoped commits 10 - Writing clear, descriptive commit messages that explain what changed and why 11 - Following Conventional Commits format 12 - Preventing common mistakes (secrets, debug code, unrelated changes) 13 14 ## When to Use 15 16 Use this skill when you need to: 17 - Commit your work with proper staging and review 18 - Craft meaningful commit messages 19 - Split mixed changes into multiple logical commits 20 - Follow Conventional Commits format 21 - Ensure commits are review-ready and safe to merge 22 23 **Trigger phrases:** 24 - "commit this work" 25 - "create a commit" 26 - "split these changes into commits" 27 - "help me commit" 28 - "write a commit message" 29 30 ## How It Works 31 32 The skill follows a rigorous 8-step workflow: 33 34 1. **Inspect** - Review working tree with `git status` and `git diff` 35 2. **Decide boundaries** - Determine if changes should be split into multiple commits 36 3. **Stage selectively** - Use patch staging (`git add -p`) for granular control 37 4. **Review staged changes** - Verify with `git diff --cached` 38 5. **Describe changes** - Articulate what changed and why in 1-2 sentences 39 6. **Write message** - Craft Conventional Commits format message 40 7. **Verify** - Run relevant tests/checks before committing 41 8. **Repeat** - Continue until working tree is clean 42 43 ## Key Features 44 45 ### Smart Commit Splitting 46 47 Automatically identifies when to split commits by: 48 - Feature vs refactor 49 - Backend vs frontend 50 - Formatting vs logic 51 - Tests vs production code 52 - Dependency bumps vs behavior changes 53 54 ### Conventional Commits Format 55 56 All commits follow the standard: 57 ``` 58 type(scope): short summary 59 60 Detailed body explaining what changed and why. 61 62 BREAKING CHANGE: if applicable 63 ``` 64 65 ### Safety Checks 66 67 Reviews staged changes for: 68 - Secrets or tokens 69 - Accidental debug logging 70 - Unrelated formatting changes 71 - Mixed or overly broad scope 72 73 ### Patch Staging 74 75 Uses `git add -p` for fine-grained control when changes within a single file need to be split across commits. 76 77 ## Usage Examples 78 79 ### Example 1: Simple Single Commit 80 81 ```bash 82 # User asks: "commit this bugfix" 83 84 # Skill workflow: 85 git status 86 git diff 87 git add src/api/auth.js 88 git diff --cached 89 git commit -m "fix(auth): resolve token expiration edge case 90 91 Previously tokens would fail validation within 1 second of expiry 92 due to clock skew. Now includes 5-second grace period." 93 ``` 94 95 ### Example 2: Splitting Mixed Changes 96 97 ```bash 98 # User has: formatting changes + new feature + test updates 99 100 # Skill creates 3 commits: 101 # Commit 1: chore: format code with prettier 102 # Commit 2: feat(api): add user profile endpoint 103 # Commit 3: test: add coverage for profile endpoint 104 105 # Uses git add -p to stage selectively 106 ``` 107 108 ### Example 3: Interactive Patch Staging 109 110 ```bash 111 # Single file has refactor + bugfix mixed 112 113 git add -p src/components/Header.js 114 # Stages only bugfix hunks for first commit 115 116 git commit -m "fix(ui): correct mobile menu z-index" 117 118 git add src/components/Header.js 119 # Stages refactor hunks for second commit 120 121 git commit -m "refactor(ui): extract menu logic to custom hook" 122 ``` 123 124 ## Inputs 125 126 The skill may ask for: 127 - **Commit strategy**: Single commit or multiple logical commits? 128 - **Commit style**: Conventional Commits (required by default) 129 - **Project rules**: Max subject length, required scopes, etc. 130 131 If not provided, defaults to: 132 - Multiple small commits when changes are unrelated 133 - Conventional Commits format 134 - Standard best practices 135 136 ## Deliverables 137 138 After running, the skill provides: 139 - Final commit message(s) used 140 - Short summary per commit (what/why) 141 - Commands used for staging and review 142 - Test/verification results 143 144 ## Best Practices 145 146 1. **Review before staging** - Always inspect `git diff` first 147 2. **Stage intentionally** - Never use `git add .` or `git add -A` 148 3. **Use patch mode** - Leverage `git add -p` for mixed changes 149 4. **Verify staged changes** - Check `git diff --cached` before committing 150 5. **Keep commits focused** - One logical change per commit 151 6. **Write for reviewers** - Explain what/why, not implementation details 152 7. **Test before committing** - Run relevant checks after each commit 153 154 ## Related Resources 155 156 - See `references/commit-message-template.md` for message templates 157 - Uses Conventional Commits specification: https://www.conventionalcommits.org/ 158 - Integrates with standard git workflow and hooks 159 160 ## Notes 161 162 - This skill enforces Conventional Commits format 163 - It encourages small, focused commits over large monolithic ones 164 - Patch staging (`git add -p`) is used extensively for granular control 165 - Each commit should pass basic verification (tests, lint, build) 166 - The goal is commits that are safe to review, bisect, and cherry-pick