Agent Skills

git-gud follows the open Agent Skills standard. AI coding agents with shell access — including Codex, Claude Code, Cursor, Gemini CLI, VS Code integrations, and others — can use gg for stacked-diff workflows.

What’s included

The integration provides one unified skill:

The gg skill is a compact, CLI-first intent router. It keeps the agent’s authority and safety boundaries close at hand, then routes each goal to only the operational guidance needed for that phase.

Each skill includes:

• SKILL.md — compact CLI-first intent router, agent rules, and safety boundaries
• references/ — phase-specific operational guidance loaded on demand

CLI help (gg <command> --help) is the source of truth for installed flags. For exhaustive user documentation and command examples, use the mdBook command pages.

Installation

1) Generic install (recommended)

npx skills add mrmans0n/git-gud

The skills CLI installs the skill into the agent setup it detects. If it cannot decide, it prompts you to choose where to install it.

2) Install for a specific agent

Use --agent when you already know the host you want to target:

npx skills add mrmans0n/git-gud --agent codex
npx skills add mrmans0n/git-gud --agent claude-code
npx skills add mrmans0n/git-gud --agent cursor
npx skills add mrmans0n/git-gud --agent gemini-cli

For a shared repository setup, run the command from the project root. For a user-level install, add --global.

3) Claude Code marketplace

Claude Code users can also install git-gud as a plugin:

claude plugin marketplace add https://github.com/mrmans0n/git-gud
claude plugin install git-gud

4) Claude Code local checkout

Use this when launching Claude Code directly from a local git-gud checkout:

claude --plugin-dir /path/to/git-gud

5) Claude Code project-level config (.claude/settings.json)

Use this when you want the local checkout enabled by default for a repository:

{
  "plugins": [
    {
      "name": "git-gud",
      "path": "/path/to/git-gud"
    }
  ]
}

6) Manual setup for compatible tools

Tools that support Agent Skills can also load the repo’s skills/gg/ directory directly. Use this fallback if your agent does not use the skills CLI yet, or if you want to manage skill files yourself.

How agents typically use gg

A practical AI-assisted stacked-diff workflow looks like this:

1. Agent creates or switches to a stack (gg co ..., ideally with a worktree)
2. Agent makes small commits and keeps each commit focused
3. Agent syncs the stack (gg sync) so PRs/MRs are created/updated in order
4. Agent iterates on review feedback (amend/reorder/re-sync)
5. Agent asks for explicit user confirmation before gg land

This keeps work reviewable while preserving user control over merges.

JSON output for tool-driven agents

For machine-readable parsing, gg supports --json on key commands:

• gg ls --json
• gg sync --json
• gg land --json
• gg clean --json
• gg lint --json

Use these outputs in agents and automation for reliable state checks and decisions. Use CLI help and the mdBook command pages for complete user-facing command documentation.

Safety model (required behavior)

When using AI agents with gg, keep these rules:

1. Never land without explicit user confirmation
2. Never run git add -A blindly (stage only reviewed/intended files)
3. Prefer worktrees for isolation (gg co --wt)
4. Use structured output (--json) when automation must parse command results

Skill references

For the compact router and phase-specific operational guidance:

• Unified skill: skills/gg/SKILL.md

File structure

skills/
  gg/
    SKILL.md
    references/
      setup-and-inspection.md
      editing-stacks.md
      syncing-and-reviews.md
      landing-and-cleanup.md
      recovery.md
      native-clients.md