ALWAYS invoke this skill when committing changes or when user says "commit". NEVER run git commit without this skill.
From legacynpx claudepluginhub outcomeeng/claude --plugin legacyThis skill uses the workspace's default tool permissions.
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Enables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
<quick_start>
just check, pnpm run check, etc.git status, git diffgit add path/to/file.ts (never git add .)type(scope): description (imperative, under 50 chars)</quick_start>
<success_criteria>
A successful commit has:
git add .)</success_criteria>
<capabilities>git add .)This skill does NOT:
<context_gathering>
Before creating any commit, gather context:
| Source | Gather |
|---|---|
| git status | Staged, unstaged, untracked files |
| git diff | Actual changes to commit |
| git log | Recent commit style for consistency |
| Project docs | Custom commit types (CLAUDE.md, CONTRIBUTING.md) |
| Conversation | User's intent - what story/issue does this commit solve |
</context_gathering>
<review_workflow_context>
When invoked from a reviewing skill (e.g., reviewing-python, reviewing-typescript):
This skill may be referenced during the commit phase of a code review. In that context:
spx/.../tests/)Refs: {capability}/{feature}/{story} in footerThe reviewing skill provides the specific file list and work item context. This skill provides the commit protocol mechanics.
</review_workflow_context>
<concern_separation>
MANDATORY: Analyze before staging. Never stage everything then ask about splitting.
After gathering context (git status, git diff), classify every changed and untracked file by concern before touching git add. A concern is one logical purpose that gets one commit type and one scope.
Classification procedure:
spec, feat, fix, refactor, docs, etc.).Split signals — if ANY of these are true, you MUST split into multiple commits:
spec for a design doc + feat for implementation)methodology/ spec + plugins/ code)Commit ordering:
When splitting, commit in dependency order:
Example:
Changed files:
methodology/skills/skill-structure.md → spec(spec-tree)
plugins/spec-tree/** → feat(spec-tree)
→ Two commits:
1. spec(spec-tree): define methodology
2. feat(spec-tree): add plugin implementation
Never ask the user whether to split. Apply the classification procedure. If the result is multiple groups, commit them separately. Separation of concerns is not a preference — it is a requirement.
</concern_separation>
<verification_protocol>
Step 0: Run Project-Specific Validation (BEFORE Staging)
Before staging any files, check CLAUDE.md for project-specific validation commands and run them. This prevents having to re-stage after auto-fixes.
# Check CLAUDE.md for commands like:
just check # Justfile task runner
just validate
pnpm run check # pnpm scripts
pnpm run validate
npm run check # npm scripts
make check # Makefile targets
make lint
Why before staging? Many project commands (formatters, linters with auto-fix) modify files. Running them after staging means you need to re-stage the fixed files. Run validation first, then stage.
Step 1: Selective Staging
# NEVER do this
git add .
# ALWAYS stage specific files
git add path/to/file1.ts path/to/file2.ts
Rules:
?? untracked file consciouslyStep 2: Diff Review
git diff --cached # Review actual changes
git diff --cached --name-only # Verify file list
Checklist:
Step 3: Atomic Commit Verification
Red Flags - DO NOT COMMIT IF:
</verification_protocol>
<message_format>
<type>[(scope)]: <description>
[optional body]
[optional footer(s)]
Subject Line (Required)
feat(auth): add OAuth2 token refresh
fix: handle empty response from API
refactor(db): extract query builder module
Body (Optional)
Footer (Optional)
BREAKING CHANGE: description - major version bumpRefs: #123 or Closes #456 - issue referencesRefs: feature-32/story-27</message_format>
<commit_types>
Standard Types
| Type | Purpose | SemVer |
|---|---|---|
| spec | Specification only | PATCH |
| test | Add/modify tests | PATCH |
| feat | Implementation of new functionality | MINOR |
| refactor | Code restructure (no behavior change) | PATCH |
| fix | Bug fix | PATCH |
| docs | Documentation only | PATCH |
| style | Formatting (no logic change) | PATCH |
| perf | Performance improvement | PATCH |
| ci | CI/CD changes | PATCH |
| build | Build system, dependencies | PATCH |
| revert | Revert previous commit | varies |
Domain-Specific Types
Projects may define custom types:
| Type | Domain | Purpose |
|---|---|---|
| draft | Writing projects | New or revised content |
| research | Academic/books | Research notes |
| meta | Process docs | Process/workflow documentation |
Check project's CLAUDE.md or commit-standards.md for custom types.
IMPORTANT: NEVER USE chore:. Everything has purpose; use specific type instead
</commit_types>
<breaking_changes>
Mark breaking changes with:
Exclamation suffix: "feat!: remove deprecated API"
Footer:
feat: change authentication flow
BREAKING CHANGE: JWT tokens now expire in 1 hour instead of 24
</breaking_changes>
<scope_guidelines>
Use Scope When:
feat(auth): add 2FA supportfix(api): handle rate limitingtest(db): add connection pool testsOmit Scope When:
fix: correct typo in error messagerefactor: consolidate error handlingdocs: update installation guide</scope_guidelines>
<description_guidelines>
Write for the reader, not the writer.
Someone scanning git log --oneline needs to understand what changed without opening the commit.
Principle 1: No State Words
Describe the action, not the prior problem:
# ❌ Describes prior state
fix: handle missing config file
spec(auth): add missing validation rules
# ✅ Describes the action
fix: return defaults when config absent
spec(auth): specify validation rules
Avoid: "missing", "broken", "wrong", "bad", "incorrect"
Principle 2: Content Over Container
Describe WHAT changed, not WHICH files:
# ❌ Describes the container
spec(session): add stories for timeout feature
docs: update README file
# ✅ Describes the content
spec(session): specify timeout and cleanup behaviors
docs: add installation prerequisites
Principle 3: Don't Repeat the Prefix
The type already tells you what kind of change:
# ❌ Redundant - prefix already says it's a spec
spec(session): add session management spec
spec(auth): define auth feature stories
# ✅ Just describe the content
spec(session): specify timeout and cleanup behaviors
spec(auth): specify OAuth2 token lifecycle
</description_guidelines>
<examples>Good Examples
feat(parser): add support for nested expressions
Enables users to write complex queries with unlimited nesting depth.
Previously limited to 3 levels.
Refs: #234
fix: prevent crash on empty config file
Return sensible defaults when config is missing or empty
instead of throwing unhandled exception.
refactor: extract validation logic into separate module
Prepares codebase for unit testing by isolating validation
from business logic.
Bad Examples
# Too vague
fix: bug fixes
# Multiple unrelated changes
feat: add parser and fix tests and update docs
# Contains attribution (NEVER do this)
feat: add export feature (by John)
# Not atomic
refactor: various improvements
# Describes prior state instead of action
fix: handle missing config
spec(auth): add missing validation
# Describes container instead of content
spec(session): add stories for advanced operations
docs: update README file
# Repeats the prefix
spec(session): add session spec
test(auth): add auth tests
</examples>
<decision_tree>
Is this a new user feature? → feat:
Is this fixing a bug? → fix:
Is this improving performance? → perf:
Is this code reorganization? → refactor:
Is this build/dependencies? → build:
Is this CI/CD? → ci:
Is this documentation? → docs:
Is this adding/changing tests? → test:
Is this context/workflow docs? → ctx: (if project uses it)
</decision_tree>
<critical_rules>
git add .</critical_rules>
<commands_reference>
# Check what will be committed
git status
git diff --cached
git diff --cached --name-only
# Stage selectively
git add path/to/specific/file.ts
# Commit with multi-line message
git commit -m "$(cat <<'EOF'
feat(scope): subject line here
Body explaining why this change was made.
Wrapped at 72 characters for readability.
Refs: #123
EOF
)"
# View recent commits for style reference
git log --oneline -10
</commands_reference>