GitButler CLI Skill

Agent skill for working with the GitButler CLI (but command) in workspace mode.

Installation

Install this skill using the GitButler CLI:

but skill install    # Prompts for scope and format

The command prompts you to choose local (repository) or global (home directory) scope first, then prompts you to select a skill format (Agent Skills / .agents/skills, Claude Code, OpenCode, Codex, GitHub Copilot, Cursor, Windsurf, or Poolside) and installs to the appropriate location. When run outside a git repository, local scope is unavailable and the default install location is global (home directory), but you can still install to a custom location with --path using an absolute or ~ path.

Options:

• --path <path> - Install to a custom path (outside a repository, relative paths require --global)
• --global - Install globally (in home directory) instead of current repository
• --detect - Auto-detect installation location from existing installation (useful for updates) In non-interactive mode, use --path or --detect.

Requirements:

• GitButler CLI installed (refer to the docs for installation instructions)
• An AI assistant with skills support such as Agent Skills / .agents/skills, Claude Code, OpenCode, Codex, GitHub Copilot, Cursor, Windsurf, or Poolside
• A Git repository. Managed-workspace mode uses but setup; when experimental single-branch mode is enabled, but registers the repository and infers its target on first use.

Updating:

To update the skill to the latest version, use the --detect flag to automatically detect and update your existing installation:

but skill install --detect

Alternatively, re-run the install command and select the same location:

but skill install

This will overwrite the existing skill files with the latest version.

Printing the skill from the CLI

The same content is embedded in the binary and can be read without installing anything:

but skill                # SKILL.md body
but skill --full         # plus every reference document
but skill reference      # command reference, rendered from the CLI's own command tree
but skill concepts       # references/concepts.md
but skill examples       # references/examples.md

but skill reference is generated from clap (crates/but/src/command/skill/reference.rs) and always matches the binary; the installed references/reference.md is the hand-written file it is replacing and the two are expected to differ.

Pointers inside the skill files use these commands rather than file paths, so they resolve whether the agent loaded an installed copy or read the CLI output.

Skill Structure

The skill directory contains both distributable skill files and development documentation:

crates/but/skill/
├── SKILL.md                   ← Skill entry point (INSTALLED)
├── AGENTS.md                  ← Rules for editing these files (NOT installed)
├── README.md                  ← This file - development docs (NOT installed)
└── references/                ← Additional skill documentation (INSTALLED)
    ├── reference.md           - Command reference
    ├── concepts.md            - Deep concepts
    └── examples.md            - Workflow examples

What gets installed: The but skill install command only copies the distributable files to the user's system:

• SKILL.md - Main skill entry point
• references/ - All reference documentation files

What stays in the repository: Development documentation remains in the source tree and is not installed:

• AGENTS.md - Rules for anyone editing the skill files (symlinked as CLAUDE.md)
• README.md - This file (development and maintenance docs)

When This Skill Is Invoked

Claude automatically invokes this skill when:

• Checking version control state (status, diffs, commits)
• Starting new work (should create branch/stack for each task)
• After making code changes (should commit them to the right branches)
• Committing work (when logical units complete)
• Editing history (amend, squash, move changes)
• Any git-like operation

Progressive Disclosure

Claude loads files on-demand:

1. SKILL.md - Always loaded when skill activates (lean overview)
2. references/reference.md - Loaded when detailed command syntax needed
3. references/concepts.md - Loaded when deeper understanding required
4. references/examples.md - Loaded when workflow examples needed

Files in references/ directory are only loaded when explicitly referenced, keeping context lean while providing comprehensive documentation when needed.

Key Design Principles

Trigger-Rich Description

The YAML description field contains all triggering information so Claude knows when to use this skill before loading the body.

Lean Entry Point

SKILL.md acts as a "table of contents" that points to detailed materials.

Domain Separation

Separate files by domain (commands, concepts, examples) so Claude only loads relevant context.

Active Language

Uses directive language ("do this") rather than passive ("this might happen").

Maintaining This Skill

When to Update SKILL.md

• New high-level workflow patterns
• Changes to core concepts
• Updates to quick reference commands

When to Update REFERENCE.md

• New but commands
• Changed command syntax
• New flags or options

When to Update CONCEPTS.md

• New conceptual models
• Changes to workspace behavior
• New architectural patterns

When to Update EXAMPLES.md

• New workflow patterns
• Common user questions
• Real-world scenarios

Testing the Skill

Test that Claude:

1. Invokes skill when starting new work
2. Creates branches before making changes
3. Commits changes to the right branches at logical points
4. Uses but commands instead of git

References

• Agent Skills Best Practices
• Claude Code Skills Documentation
• GitButler CLI Documentation