but skill

Skills provide enhanced AI capabilities for working with GitButler through Claude Code, Codex, and other AI assistants.

Use but skill install to install the GitButler skill files. By default, it prompts for scope (repository or global home directory) and then format. When run outside a git repository, local scope is unavailable and the default install location is global (home directory). You can still install to a custom location with --path using an absolute or ~ path.

Examples

Install interactively (prompts for scope and format):

but skill install

Install the skill globally:

but skill install --global

Usage: but skill <COMMAND>

Subcommands

but skill install

Install the GitButler CLI skill files for Coding agents

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

Use --global to install the skill in a global location instead of the current repository.

In non-interactive mode, specify --path or --detect.

Examples

Install interactively (prompts for scope and format):

but skill install

Install globally (prompts for format):

but skill install --global

Install to a custom path:

but skill install --path .agents/skills/gitbutler

Auto-detect installation location (update existing installation):

but skill install --detect

Usage: but skill install [OPTIONS]

Options:

• -g, --global — Install the skill globally instead of in the current repository
• -p, --path <PATH> — Custom path where to install the skill (relative to repository root or absolute). Outside a repository, relative paths require --global
• -d, --detect — Automatically detect where to install by finding existing installation

but skill check

Check if installed GitButler skills are up to date with the CLI version

Scans for installed skill files and compares their version with the current CLI version. By default, checks both local (repository) and global installations.

Examples

Check all installed skills:

but skill check

Check and automatically update outdated skills:

but skill check --update

Check only global installations:

but skill check --global

Usage: but skill check [OPTIONS]

Options:

• -g, --global — Only check global installations (in home directory)
• -l, --local — Only check local installations (in current repository)
• -u, --update — Automatically update any outdated skills found