Botfile manages your AI agents' custom context the way dotfiles manage the rest of your tools. You curate skills (invocable context) and instructions (ambient context) in git repositories, and botfile symlinks them into each agent's native directories.
Currently opencode, claude-code, codex-cli, pi, crush, copilot-vscode, copilot-cli are all supported.
Botfile is a magic-free symlink farm, in the spirit of GNU Stow, but it understands AI agents (where agent = harness + model): it knows where each one reads skills and instructions, and fans one source out to all the agents on your device.
The fan-out is botfile's unique feature. It means that one source reaches multiple destinations. In this case, one agent skill, instruction or command can be made available all the agents on the user's device. If the skill is in a git repo, it can be shared across teams. If it's updated, botfile can sync the updated skill so everyone stays on the same page.
Botfile's goal is to bring some structure to the sometimes chaotic internals of popular agents by enabling users to extract, persist, share, and sync the skills https://agentskills.io/home, instructions https://agents.md/, and commands they use.
Botfile solves the problem of managing standard user-invokable context, like the skills and commands that a team shares, alongside private skills you want to use across your devices and agents.
Bofile also works in the same way with ambient context. The instructions, like AGENTS.md that are injected into the harness lifecycle.
Botfile works with all the major agent harnesses, and is quite opinionated about following the UNIX philosophy of doing one thing well. In botfile's case, it'll only ever be a symlink farm with support for the agent component kinds (skills, commands, and instructions so far) that fit its model.
If you:
-
don't have skills or instructions at the user-scope, or
-
don't find yourself wanting to share skills or instructions across agents, or
-
don't share skills or instructions with a team.
Botfile is probably not for you...
If you'd like to try and start doing one, all or just some of these things it's a good place to start.
You declare desired state in config.toml (which sources map to which
agents), and botfile reconciles the filesystem to match it, in two phases:
compute a plan, then apply it. A source is a directory tree of
<plugin>/<kind>/<component>; each component installs as exactly one symlink in
the agent's native location, never a copy and never a clobber.
From a checkout of this repository:
go install ./cmd/botfile
export PATH="$(go env GOPATH)/bin:$PATH" # if your Go bin is not already on PATH
botfile --help# 1. Curate a source (a skill the agent discovers by presence).
mkdir -p ~/botfiles/mine/skills/bark
cat > ~/botfiles/mine/skills/bark/SKILL.md <<'MD'
---
name: bark
description: Always reply "woof".
---
MD
# 2. Tell botfile about the source and which agents get it.
mkdir -p ~/.config/botfile
cat > ~/.config/botfile/config.toml <<'TOML'
[[sources]]
name = "personal"
location = "~/botfiles"
[[selections]]
source = "personal"
agents = ["claude-code"]
TOML
# 3. Preview, then apply.
botfile plan
botfile syncRun botfile help for the full operator guide.
botfile plan: show what a sync would change (read-only).botfile sync: reconcile your agents to match your config.botfile status: what is managed, out of sync, and adoptable.botfile adopt <path> --into <source>/<plugin>: bring an agent-created component under management.
Any command takes --format json for machine-readable output.
claude-code, codex-cli, copilot-cli, copilot-vscode, crush, opencode, and pi.dev,
each for skills and instructions. Where each installs (and the shared
~/.agents/skills pool) is shown by botfile help.
botfile help (alias botfile guide) is the built-in operator guide; it accepts
--format text|markdown|json and loads no config, so it works on a fresh install.
The code is licensed under the Apache License, Version 2.0
(LICENSE, NOTICE). Copyright 2026 Iain Maitland.