Drive the botfile CLI to manage AI-agent skills, instructions, and commands. Use when asked to sync, plan, adopt, or check the status of agent components managed by botfile.
Drive the botfile CLI to manage AI-agent skills, instructions, and commands. Use when asked to sync, plan, adopt, or check the status of agent components managed by botfile.
botfile
botfile manages AI-agent skills, instructions, and commands as symlinks from source repositories you control.
This skill carries botfile's operator guide. The CLI prints the same guide: run botfile guide (or botfile guide --format markdown|json); it is also published at botfile.org/agents.html. If botfile is not on PATH, install it first (with the user's agreement) per botfile.org.
Model
source: A local directory, often a git checkout, holding curated components. botfile reads it in place; git does any fetching.
plugin: A named bundle inside a source. Even a single-bundle source has an explicit plugin directory: <source>/<plugin>/.
component: A typed artifact under a plugin. Kinds today: a skill (a directory with a SKILL.md), an instruction (a .md file), and a command (a .md file the agent exposes as a slash command).
selection: A config rule mapping a source (and optionally one plugin or component) to one or more agents that should receive it.
botfile operates at user scope only: the per-user paths under your home directory. It never writes into a project checkout (a repo's .claude/ or an in-repo AGENTS.md); project-scoped components belong to the project.
Selections fan out: one component reaches every agent its selections name, one symlink per agent's native path, and agents reading the shared ~/.agents/skills pool are served by a single link. Symlinks, not copies, so an edit to the source is live through every agent at once.
The kinds differ in how they reach the model: an instruction is ambient (the harness injects it into every session), so it matters that instructions can be scoped to all, some, or one agent; a skill is on-demand: its name and description always sit in context and its body loads when the model matches it to the task or the user invokes it; a command is a prompt file the user runs explicitly (/name). On-demand kinds are cheap when idle, not free. Not every agent supports commands; the agents table shows a dash where a kind has no native surface.
A selection picks any depth of source > plugin > component: omit plugin and component for the whole source, set plugin for one bundle, set both for a single component (component is <kind>/<name>, like skill/review).
An omitted plugin or component is a wildcard; an unknown config key is rejected rather than ignored, so a typo cannot silently widen a selection.
Workflow
Run in this order; only run sync after the user agrees.
botfile status: See what is managed, out of sync, and adoptable. Read-only, safe to run anytime.
botfile plan: Preview the exact symlinks a sync would create or remove. Read-only; changes nothing.
confirm with the user: Show the plan and get the user's agreement before changing anything on disk.
botfile sync: Apply the plan only after the user agrees: create and remove symlinks to match the config.
botfile adopt --into /: If sync reports a conflict (a real file where botfile wants a link), adopt that file into a source instead of overwriting it. botfile never clobbers.
Commands
Command
Does
botfile plan
show what a sync would change
botfile sync
reconcile your agents to match your config
botfile status
show what is managed, out of sync, and adoptable
botfile adopt <path> --into <source>/<plugin>
bring an agent-created component under management
botfile guide
print this guide (text, markdown, or json)
botfile version
print the version
botfile upgrade [--check]
replace this binary with the latest release, checksum-verified (--check: report only)
Agents
Agent
Skills
Instructions
Commands
claude-code
~/.claude/skills/<name>/
~/.claude/rules/<name>.md
~/.claude/commands/<name>.md
codex-cli
~/.agents/skills/<name>/
~/.codex/AGENTS.md
~/.codex/prompts/<name>.md
copilot-cli
~/.agents/skills/<name>/
~/.copilot/copilot-instructions.md
-
copilot-vscode
~/.agents/skills/<name>/
~/.copilot/instructions/<name>.instructions.md
-
crush
~/.agents/skills/<name>/
~/.config/crush/CRUSH.md
-
opencode
~/.agents/skills/<name>/
~/.config/opencode/AGENTS.md
~/.config/opencode/commands/<name>.md
pi.dev
~/.agents/skills/<name>/
~/.pi/agent/AGENTS.md
~/.pi/agent/prompts/<name>.md
JSON for agents
Every command accepts --format json. Prefer it: parse the structured report rather than scraping text.
The JSON envelope carries schemaVersion, command, phase, outcome, exitCode, plus ops, notes, issues, and summary counts.
exitCode is authoritative: 0 ok, 1 blocked (a conflict or broken config refused the change), 2 a usage or effect error.
plan and status never modify anything; only sync and adopt change the filesystem, and upgrade replaces botfile's own binary (checksum-verified, never in the background).
