Agent Skills for consistent Git workflows
A consistent Git history that's easy to read: for both humans and agents.
git-claw is an Agent Skill that keeps your commits, PRs, issues, and code reviews in a unified format. Install once, and every collaboration artifact follows the same conventions: whether you're working solo or in a team.
- Readable history: Structured commits, PRs, and issues that anyone (or any agent) can follow at a glance
- Multi-model code review: Domain agents, plus optional Codex adversarial analysis, cross-validated and severity-ranked
- Session continuity:
/handoffcaptures work context so the next session picks up where you left off
| Skill | What it does | |
|---|---|---|
| 📝 | /commit |
Conventional commits from your diff |
| 🔀 | /pr |
Structured PRs with auto-labeling |
| 📋 | /issue |
Templated issues with priority labels |
| 💬 | /review-reply |
Analyze and reply to review comments |
| 🔍 | /code-review |
Multi-agent severity-based code review |
| 🤝 | /handoff |
Session transfer prompt generation |
| 📖 | /explain-diff |
Interactive HTML explainer for understanding a diff |
| 🧪 | /micro-world |
Throwaway interactive simulation of a behavior |
| 📄 | /visual-doc |
On-brand interactive document from researched/analyzed content |
| 🖼️ | /eli5 |
Picture-first explainer for someone outside the domain |
# Add marketplace
/plugin marketplace add chanmuzi/git-claw
# Install plugin
/plugin install git-claw@git-clawnpx skills add chanmuzi/git-clawThe interactive installer lets you select skills, target agents, scope (project/global), and install method.
Install all skills at once without prompts
npx skills add chanmuzi/git-claw --skill commit --skill pr --skill issue --skill review-reply --skill code-review --skill handoff --skill explain-diff --skill micro-world --skill visual-doc --skill eli5 -gClaude Code Plugin:
/plugin update git-claw@git-clawOr enable auto-update: /plugin → Marketplaces tab → select marketplace → Enable auto-update
Skills CLI:
npx skills check # Check for updates
npx skills update # Update all installed skillsSymlink installs (recommended) apply updates to all agents at once. Copy installs require updating each copy individually.
Skill renames are not auto-tracked. When a skill is renamed upstream, the Skills CLI keeps the old folder around, so you may see two skills with the same description, or the skill may surface under its old name. Remove the stale folder manually: match the scope you installed with:
# Global install (npx skills add ... -g) → ~/.codex/skills/{old-name} npx skills remove {old-name} -g # or rm -rf ~/.codex/skills/{old-name} # Project install (npx skills add ... without -g) → ./.codex/skills/{old-name} npx skills remove {old-name} # or rm -rf ./.codex/skills/{old-name}Then restart your Codex CLI session so the skill list is re-cached.
Skill prefix by agent: Claude Code uses
/(e.g.,/commit), Codex CLI uses$(e.g.,$commit).
Analyzes your staged/unstaged changes and proposes conventional commit messages. Before staging, files are grouped by intent (infrastructure, agent config, app code, build tooling, docs, tests), and multi-intent changes are automatically split into separate commits with same-intent exceptions for tightly coupled changes (schema+code, signature+call-sites, code+validating tests). Messages never use the em-dash, the en-dash, or the middle dot.
/commit # Analyze and commit
/commit --amend # Amend the last commit
Types: feat, fix, refactor, style, docs, test, perf, chore, hotfix
Creates a PR with a structured template. Automatically detects Individual or Release mode. Titles and bodies never use the em-dash, the en-dash, or the middle dot, the usual markers of machine-written text; every skill follows the same rule.
/pr # Individual PR (Feat, Fix, Refactor, etc.)
/pr -g # Include Mermaid change-flow graph
/pr release # Release PR (dev → main integration)
After creating an individual PR, the skill offers a one-line opt-in to generate an /explain-diff explainer for the change (default No, never re-asked).
Creates a structured issue with the appropriate template and auto-assigns type/priority labels.
/issue # General issue (type inferred from context)
/issue bug # Bug report
/issue feature # Feature request
Collects review comments (CodeRabbit, Copilot, teammates, etc.) from a PR, analyzes their validity against the actual code, and discusses findings with you. Each item quotes the source verbatim and shows the proposed change as a diff, so you can accept or reject a suggestion without opening the files yourself: including dismissals, which quote the code that refutes the reviewer.
/review-reply # Review current branch's PR
/review-reply 42 # Review PR #42
Analyzes PR or local code changes using a multi-agent pipeline with domain-specific agents (Security, Performance, Architecture, Domain Logic). In PR mode, agents receive the PR's purpose as their primary review lens: catching incomplete implementations, consistency gaps, and purpose-misaligned changes. Cross-validates findings to filter false positives, with an out-of-diff causality filter that dismisses pre-existing issues unrelated to the PR. A Reporting Bar then separates "true" from "worth reporting": every surviving finding gets a disposition independent of its severity: ship-blocker and in-scope-gap are reported in full, pre-existing issues get one line under 밖으로 미룸 and never an inline comment, and style preferences are counted rather than written up. The cut appears as a single 기각 {n}건 line, so a short review reads as a judgment rather than a gap. Produces severity-based output (🔴 Critical, 🟡 Warning, 🟢 Info). Every finding quotes the offending code verbatim and shows the fix as a diff, so a report is readable on its own: no jumping to the file to work out what was wrong. When no changes are detected, automatically transitions to reviewing the current working directory. Conversation context is used to determine the optimal review scope.
/code-review # Auto-detect PR, review changes, or review cwd (context-aware)
/code-review 42 # Review PR #42
/code-review src/auth/ # Review specific path
In PR mode, findings are published as inline review comments on specific diff lines via the GitHub Review API.
Flags
--wd: Force working directory mode, even on a PR branch--domain security,perf: Override auto-detected domains-y/-f: Publish without approval-g: Generate Mermaid change-flow graph (PR mode only)-q/--quick: Quick mode: single-pass, max 2 domains, Critical/Warning first--full-scan: Include pre-existing out-of-diff issues in General Findings (PR mode only)-a/--all: Bypass the Reporting Bar and report every confirmed finding, dropped ones included (audit mode)--codex: Opt in to Codex adversarial review (off by default)--codex-general: Opt in to Codex general review only--codex-both: Run both Codex general review and adversarial review--no-codex: Force Codex off, overriding a natural-language Codex request
Codex integration (optional)
Codex is off by default. Pass --codex (or --codex-general / --codex-both) to run Codex in parallel with domain agents; findings are cross-validated and merged with source tags. Before running, the skill checks via the companion's setup --json that the Codex plugin is installed, the Codex CLI is present, and you are logged in. If any of those is missing, the review stops and prints the matching setup guidance (claude plugin add codex, npm install -g @openai/codex, codex login, /codex:setup) instead of silently reviewing without Codex.
Generates a copy-ready handoff prompt that transfers work context to a new session. Built on a single principle: write only what the next session cannot recover by reading the repo. The next session is a capable agent that will explore the code itself, so the handoff carries only decisions and their reasons, abandoned approaches, user constraints, and the first action. Everything else is referenced by path.
/handoff # Auto-detect and generate handoff prompt
/handoff -y # Skip confirmation, output directly
/handoff auth refactoring # Focus on a specific topic
Details
An order, not a briefing: The output is a prompt you paste to put the next agent to work immediately, written in your own conversational voice: not a status report you then have to act on by writing a second message. Every handoff ends in an action; even an undecided direction becomes "look into X first and tell me how you'd go."
Structure: A directive (what to do first, on which branch), up to 4 context bullets, and reference paths. 15 lines total, hard cap. Sections with nothing to say are omitted: an empty context section is a correct outcome.
Git: Branch name and whether uncommitted changes exist. Nothing more: no commit log, no diff stat, no file list. The next session runs git status itself.
No skill names: The handoff never suggests slash commands or plugin skills unless you explicitly ask for one. The next session may run in a different agent with different plugins installed, so it picks its own tools.
Output: Terminal text optimized for /copy. Never repeats file content: references paths instead.
Generates a self-contained interactive HTML explainer for a diff, commit, branch, or PR, so you genuinely understand the change before sharing or merging it. Inspired by Geoffrey Litt's explain-diff: understanding, not correctness, is the bottleneck of agent-written code. The document walks through the change as a literate diff (prose + verbatim code excerpts), shows an annotated directory tree of everything touched, and ends with a 5-question quiz. Wrong answers get a hint pointing back to the relevant section: never the answer: and the hint is a one-click jump to that section, with a "back to quiz" chip to return. The completion gate opens only at 5/5.
/explain-diff # Explain the working diff
/explain-diff 42 # Explain PR #42
/explain-diff src/ # Restrict the diff to a path
Details
Investigate first: Before writing, the skill reads every hunk plus its enclosing function, extracts stated intent from commits/PR body, explores callers and tests, and groups hunks into narrative themes: the document explains behavior, not lines.
Three-part structure: Overview (background + directory tree + optional interactive figure), Changes (one card per theme: prose, an optional before/after flow figure when the theme changes call order or call count, the verbatim diff excerpt, and a key-takeaway card), and Comprehension check (risk pointers + quiz).
Honest by design: Suspicions are framed as attention pointers, never verdicts; quoted code is verbatim only; the completion button states understanding: it never pretends to perform an action.
Reads naturally in Korean: Titles are short noun phrases, not sentences (with word-break: keep-all so Korean wraps at word boundaries, never mid-word), and the output avoids em-dashes and stiff translation-ese that mark machine writing.
Output: A single self-contained HTML file (no CDN, no webfonts) written to the repository root as explain-diff-<slug>.html. The absolute path is reported; nothing is auto-opened or committed. Light and dark are both supported: the page follows the system setting, and a button in the top-right corner switches it.
Builds a throwaway interactive HTML simulation of a specific behavior (a state machine, algorithm, data transform, or protocol flow), so you can feel how the code works by manipulating it (after Seymour Papert's "Mathland"). Sibling of /explain-diff: that one produces a consistent document; this one produces a bespoke one-off simulation sharing only the visual language. An applicability gate declines honestly when a sim adds nothing (config changes, renames, dependency bumps) and points you to /explain-diff instead. Every simulation models the actual code logic, and any simplification is disclosed in a footnote. Each world runs one guided scenario: a mission bar with goal chips, exactly one recommended action enabled at a time: with full step playback: snapshot-based back/forward controls where pressing the forward key from a fresh page walks the entire story (arrow keys and R to restart). Light and dark are both supported: the page follows the system setting, and a button in the top-right corner switches it. The terminal pane stays dark in both.
/micro-world # Simulate a behavior from the current change
/micro-world "retry logic in api.ts" # Simulate a described behavior
Generates a self-contained interactive HTML document from researched or analyzed content: a research brief, repo/code analysis, concept explainer, comparison, or design writeup. Sibling of /explain-diff and /micro-world (they share design tokens, never structure). Unlike /explain-diff it carries no quiz and no comprehension gate: it communicates, it doesn't test. Built in two layers: a locked layer (tokens, primitives, tone) keeps every document recognizably one family, while the composed layer builds a bespoke skeleton from a component palette (components.html) chosen by the content's kind and scale. When the content needs a block the palette lacks, a new one is authored from the same tokens (the palette is a cookbook of exemplars, not an exhaustive list). Long documents pick a navigation strategy by scale: top progress bar with a floating TOC, a slim chapter pager, or collapsible sections. Light and dark both supported: the page follows the system setting, and a button in the top-right corner switches it.
/visual-doc # Document the current conversation's content
/visual-doc src/ # Analyze and document a path
/visual-doc 42 # Analyze and document PR #42
Diagrams: Flows, sequences, and structures are hand-authored inline SVG that uses the document's own tokens, so they follow the light/dark toggle and render wherever the file is opened. Mermaid remains as a fallback for diagrams too large to lay out by hand.
Output: A single self-contained HTML file (no CDN, no webfonts) written to the repository root as visual-doc-<slug>.html. The absolute path is reported; nothing is auto-opened or committed.
Produces a self-contained HTML page where big hand-authored SVG diagrams carry the explanation and the prose is a short factual paragraph per picture. The fourth sibling of /explain-diff, /micro-world, and /visual-doc (shared design tokens, never shared structure), separated from them by its reader: this one is for someone outside the domain entirely, and it succeeds only if the idea comes through from the drawings alone. The page is storyboarded as a sequence of beats before any HTML is written, following a problem → obvious fix → the trap → real fix → cost → rule arc, where the trap beat is the point of the page. Simplification is by omission, never by stating something false, and the cost beat is never dropped to make the story end happily. Drawings are concrete by default: the boxes are the real tables, endpoints and flags under their real names, each with one plain sub-line, while explanation, file paths and line numbers stay out of the picture. Every label is sized by arithmetic before it is drawn (per-character width estimates, box-from-label sizing, a row budget and a layout-plan comment inside each SVG), so text does not overlap or run past a border even when the page is never rendered. Titles and beat headings state a fact about the subject in its real names (a terse list is fine); metaphors and translated idioms are kept out of them. The page has no footer; provenance is a single source-and-date line above the title, and the file paths it was built from are reported in the terminal instead.
/eli5 how does DNS work # Explain a topic
/eli5 42 # Explain PR #42 to a non-expert
/eli5 src/auth/ # Explain what a path does
/eli5 # Explain the current conversation's subject
Interactive only when needed: A page may carry one figure with a slider or switch, only when the reader has to move a value to see the point (the outcome changes across several values, or the point is where behavior flips). A plain before/after comparison stays a static two-row figure.
Structure: Each beat is one drawing with numbered badges, then notes (one line per badge) and a one-line conclusion. A badge marks only a box whose note adds what the label cannot; several same-shaped boxes that one note covers share one dashed group outline and one badge, and a drawing that is itself a list carries none. When the drawing cannot show the fact (a line missing from a config file, the columns of a table, a field missing from a request), an evidence card quotes the real file or table verbatim between the drawing and the notes, with the missing line drawn as a dashed ghost line and the badges sitting on the card's left border so the quoted lines keep their full width. Evidence cards and before/after comparisons stack as rows rather than side by side, so every line keeps the column width, and whether a side-by-side block fits is measured on the rendered page; a figure comparing states can open each row with a short state caption.
Output: A single self-contained HTML file (no CDN, no webfonts) written to the repository root as eli5-<slug>.html. The absolute path is reported; nothing is auto-opened or committed. Light and dark are both supported: the page follows the system setting, and a button in the top-right corner switches it.
All commands write output (commit messages, PR titles/body, issue titles/body) in the language configured in your project's AGENTS.md (or CLAUDE.md as fallback). If no language is set, the user's conversational language is used. Technical terms are kept in their original form.
| Item | Format | Example |
|---|---|---|
| Commit | {type}: {desc} (lowercase) |
feat: 멀티턴 컨텍스트 유지 기능 추가 |
| Branch | {type}/{kebab-case} (English) |
feat/multiturn-context-persistence |
| PR Title | {Type}: {desc} (capitalized) |
Feat: 멀티턴 컨텍스트 유지 기능 추가 |
| Issue Title | {desc} (no type prefix) |
E2E 실험에서 non-default retrieval index snapshot 지원 |
| Release PR | Release: dev → main 통합 (vX.Y.Z) |
Release: dev → main 통합 (v0.4.1) |
Add the following to your global ~/.claude/CLAUDE.md to reference these conventions:
## Git Conventions
- Commit: `{type}: {description}` (lowercase prefix: feat, fix, refactor, style, docs, test, perf, chore, hotfix)
- Branch: `{type}/{english-kebab-case}` (feat/, fix/, refactor/, docs/, hotfix/)
- PR title: `{Type}: {description}` (capitalized prefix: Feat, Fix, Refactor, Perf, etc.)
- Release PR: `Release: dev → main 통합 (vX.Y.Z)`
- Use `/commit`, `/pr`, `/pr release`, `/issue`, `/review-reply`, `/code-review`, `/handoff`, `/explain-diff`, `/micro-world`, `/visual-doc`, `/eli5` commands for full workflows/pr and /issue share a unified label scheme. Labels are auto-created on first use: if a label already exists, it is left unchanged.
Label reference
| Label | Color | Source |
|---|---|---|
bug |
🔴 d73a4a |
GitHub default |
feature |
🔵 0075ca |
GitHub default |
enhancement |
🩵 a2eeef |
GitHub default |
docs |
🟣 5319e7 |
GitHub default |
chore |
🟡 e4e669 |
Standard |
refactor |
🟪 d4c5f9 |
Standard |
style |
🩵 c5def5 |
Standard |
test |
🟢 bfd4f2 |
Standard |
perf |
🟠 f9d0c4 |
Standard |
hotfix |
🔴 b60205 |
Standard |
release |
🔵 1d76db |
Standard |
critical |
🔴 b60205 |
Priority |
high |
🟠 d93f0b |
Priority |
medium |
🟡 fbca04 |
Priority |
low |
🟢 0e8a16 |
Priority |
- No namespace prefix: clean, simple names (
buginstead oftype: bug) - GitHub-standard colors: matches GitHub's default palette where applicable
- Conflict-safe:
gh label create ... 2>/dev/null || true(create if missing, skip if exists)
MIT