README.md
1,327 tokens · o200k_base · 6,183 bytes
Source excerpt starting at line 1.# GitButler CLI Skill Agent skill for working with the GitButler CLI (`but` command) in workspace mode. ## Installation Install this skill using the GitButler CLI: ```bashbut 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: ```bashbut skill install --detect``` Alternatively, re-run the install command and select the same location: ```bashbut 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: ```bashbut skill # SKILL.md bodybut skill --full # plus every reference documentbut skill reference # command reference, rendered from the CLI's own command treebut skill concepts # references/concepts.mdbut 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-writtenfile 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: ```textcrates/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 needed3. **references/concepts.md** - Loaded when deeper understanding required4. **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 work2. Creates branches before making changes3. Commits changes to the right branches at logical points4. Uses `but` commands instead of `git` ## References - [Agent Skills Best Practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices)- [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)- [GitButler CLI Documentation](https://docs.gitbutler.com/cli-overview)