botfile

botfile is a CLI for managing AI-agent components (skills and instructions).

It reads a config.toml that declares local source directories and which agents should receive their components. It then creates symlinks from those sources into each agent's native config paths.

It is inspired by Stow: under the hood it is a symlink farm that follows the Unix philosophy of doing one thing well, and is strictly guided by its tenets.

Use botfile if you have user-scoped agent components (like skills or instructions) you use across projects, teams, agents, or devices. botfile-managed components can be:

• kept in version control like git
• synced across machines
• publicly shared with a team, kept private in a personal dir, or a mix
• installed into multiple agents from one config

botfile manages two kinds:

• skill (skill/<name>): invokable on demand, a directory like skills/meow/SKILL.md, described in detail at agentskills.io
• instruction (instruction/<name>): ambient context injected at harness runtime, a file like instructions/favorite-food.md, following agents.md

Other agentic components exist, like hooks, memory, and MCP config. botfile will support them if there's demand. For now skills and instructions are the most standardized components and the best fit for the project tenets.

A source is a local directory that holds botfile components, usually a git repo. Its layout is:

<source>/
  <plugin>/
    skills/
      <skill-name>/
        SKILL.md
    instructions/
      <instruction-name>.md

For example:

~/botfiles/personal/
  cats/
    skills/
      meow/
        SKILL.md
    instructions/
      favorite-food.md

In ~/.config/botfile/config.toml you give the source a name and location:

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

A declared source needs a selection that declares the symlink destination. Add one and the file reads:

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

[[selections]]
source = "personal"
plugin = "cats"
agents = ["claude-code", "codex-cli"]

That installs the selected components on the next botfile sync. Meaning:

• source: personal
• plugin: cats
• agents: claude-code, codex-cli
• every component in the cats plugin (the meow skill and favorite-food instruction) installs for both agents

plugin and component are optional: omit plugin to select every plugin in the source, or add component to pin the selection to one component.

Seven, each for both skills and instructions:

• claude-code
• codex-cli
• copilot-cli
• copilot-vscode
• crush
• opencode
• pi.dev

Skill paths vary by agent: most share ~/.agents/skills, while Claude Code uses ~/.claude/skills. Instructions install to each agent's native instruction path.

See the support matrix for the exact paths.

No. botfile is scoped to user-level agent skills and instructions:

~/.claude/skills
~/.claude/rules
~/.agents/skills
~/.codex/AGENTS.md

It does not manage project-local files such as:

./AGENTS.md
./CLAUDE.md
./.github/copilot-instructions.md
./.vscode/settings.json

Keep project instructions in the project repo directly. botfile is for shared personal and team agent context across projects and machines.

Yes, mostly at the file-format level.

skills.sh distributes agent skills as SKILL.md packages, and botfile's skill component is also a directory containing SKILL.md. So a skill from skills.sh can be managed by botfile if it is placed in a botfile source tree.

Typical flow:

• Install/download a skill into a botfile source, then botfile sync.

Sources: skills.sh

Yes. Each piece has a clear owner, so nothing is managed twice:

• git owns the source repos: you clone, pull, and push each one (such as ~/botfiles/personal)
• your dotfile manager (Stow, chezmoi) owns ~/.config/botfile/config.toml
• botfile owns the agent-native symlinks it creates

Yes. botfile's CLI can respond with structured JSON that makes it easy for an agent to use:

1. Run botfile status --format json.
2. Inspect managed, out-of-sync, and adoptable components.
3. Run botfile plan --format json.
4. Explain the planned changes.
5. Only run botfile sync after your approval.
6. Use botfile adopt <path> --into <source>/<plugin> to bring an existing agent-created skill or instruction into a source.

The agent can help edit source files and config.toml, then use botfile to preview and apply the symlinks.

Still require your approval before:

• running botfile sync
• running botfile adopt
• editing shared or team source repos
• changing selections that affect multiple agents

botfile is built so agents do not scrape text: use --format json.

Use it if you have a real need for versioned, reusable agent context.

Good fit:

• you use multiple agents
• you use multiple machines
• you want skills/instructions in git
• you want team-shared agent components
• agents create useful skills locally and you want to adopt them into a repo

Probably not worth it:

• you use one agent on one machine
• you rarely customize skills or instructions
• you are happy letting each agent/tool manage its own files
• you scope agent components at the project level and rarely across projects
• you mainly want MCP/settings/plugin management

So: yes for managing portable skills and instructions; no if you only need a one-off local setup.