Bootstrap 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: //.
• 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.

Config

Path: ~/.config/botfile/config.toml

[[sources]]
name = "personal"
location = "~/botfiles/personal"

[[selections]]
source = "personal"
agents = ["claude-code"]

Scope

• 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 /, 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.

1. botfile status: See what is managed, out of sync, and adoptable. Read-only, safe to run anytime.
2. botfile plan: Preview the exact symlinks a sync would create or remove. Read-only; changes nothing.
3. confirm with the user: Show the plan and get the user's agreement before changing anything on disk.
4. botfile sync: Apply the plan only after the user agrees: create and remove symlinks to match the config.
5. 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 --into / | 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// | ~/.claude/rules/.md | ~/.claude/commands/.md | | codex-cli | ~/.agents/skills// | ~/.codex/AGENTS.md | ~/.codex/prompts/.md | | copilot-cli | ~/.agents/skills// | ~/.copilot/copilot-instructions.md | - | | copilot-vscode | ~/.agents/skills// | ~/.copilot/instructions/.instructions.md | - | | crush | ~/.agents/skills// | ~/.config/crush/CRUSH.md | - | | opencode | ~/.agents/skills// | ~/.config/opencode/AGENTS.md | ~/.config/opencode/commands/.md | | pi.dev | ~/.agents/skills// | ~/.pi/agent/AGENTS.md | ~/.pi/agent/prompts/.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).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: listfold
• Source: listfold/botfile
• License: Apache-2.0
• Homepage: https://botfile.org

Install and usage instructions live in the source repository linked above.