botfile: manage AI agent skills, instructions, and commands

Prompt

prompt your agent

Fetch https://botfile.org/agents.html (curl or wget) and follow it to
install botfile and manage skills, instructions, and commands I can
share privately with different agents across devices, or publicly with
my team.

Install botfile

install · macOS / Linux

curl -fsSL https://botfile.org/install.sh | sh

install · Windows (PowerShell)

# symlink creation needs Developer Mode enabled

irm https://botfile.org/install.ps1 | iex

Create a skill, share it with your agents

Start simple. Keep a skill in a dotfiles repo and let botfile symlink it into the agents you use. Here a meow skill in ~/botfiles/personal goes to both Claude Code and Codex.

create a skill

mkdir -p ~/botfiles/personal/cats/skills/meow
cat > ~/botfiles/personal/cats/skills/meow/SKILL.md <<'MD'
---
name: meow
description: Always reply with "meow", and nothing else.
---

# Meow

When this skill is used, respond with exactly:

meow
MD

Tell botfile where the source is and which agents get it. botfile reads config.toml from ~/.config/botfile/:

add the personal botfile

mkdir -p ~/.config/botfile
cat > ~/.config/botfile/config.toml <<'TOML'
[[sources]]
name = "personal"
location = "~/botfiles/personal"

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

Apply it. One source file becomes a symlink in each agent's native path:

botfile sync

$ botfile sync
  create   ~/.agents/skills/meow -> ~/botfiles/personal/cats/skills/meow
  create   ~/.claude/skills/meow -> ~/botfiles/personal/cats/skills/meow
  note     skills for [codex-cli] also reach [copilot-cli copilot-vscode crush opencode pi.dev] via ~/.agents/skills (selection personal)

synced: 2 operation(s) applied

Claude Code reads ~/.claude/skills/; Codex reads the cross-agent ~/.agents/skills/ pool, which the note flags is shared with the other terminal agents. botfile installs symlinks, not copies, so editing the source file is live through every agent at once.

Import skills from a team repo

Your team keeps shared skills, instructions, and commands in a git repo. Clone it, declare it as a second source, and select it for your agents. botfile does the symlinks; git does the fetching. As a stand-in for the team repo, use botfile_example, the example source tree that ships in botfile's own repo:

clone the team repo

git clone https://github.com/listfold/botfile ~/botfiles/botfile

The example is a source tree with the <plugin>/<kind>/<component> grammar, two plugins here. The team standards live in standards; the botfile plugin waits for the advanced section:

~/botfiles/botfile/examples/botfile_example

botfile/
  skills/bootstrap-botfile/SKILL.md
standards/
  skills/echo/SKILL.md
  instructions/no-em-dashes.md
  commands/changelog.md

Declare the example as a second source, named botfile, next to the personal one, and select its standards plugin for three agents; a selection can name a whole source, one plugin, or one component. Your config.toml now has both sources:

~/.config/botfile/config.toml

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

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

[[sources]]
name = "botfile"
location = "~/botfiles/botfile/examples/botfile_example"

[[selections]]
source = "botfile"
plugin = "standards"
agents = ["claude-code", "codex-cli", "copilot-vscode"]

Then apply it. The team's echo skill, no-em-dashes instruction, and changelog command land at each agent's native path:

botfile sync

$ botfile sync
  create   ~/.agents/skills/echo -> ~/botfiles/botfile/examples/botfile_example/standards/skills/echo
  create   ~/.claude/commands/changelog.md -> ~/botfiles/botfile/examples/botfile_example/standards/commands/changelog.md
  create   ~/.claude/rules/no-em-dashes.md -> ~/botfiles/botfile/examples/botfile_example/standards/instructions/no-em-dashes.md
  create   ~/.claude/skills/echo -> ~/botfiles/botfile/examples/botfile_example/standards/skills/echo
  create   ~/.codex/AGENTS.md -> ~/botfiles/botfile/examples/botfile_example/standards/instructions/no-em-dashes.md
  create   ~/.codex/prompts/changelog.md -> ~/botfiles/botfile/examples/botfile_example/standards/commands/changelog.md
  create   ~/.copilot/instructions/no-em-dashes.instructions.md -> ~/botfiles/botfile/examples/botfile_example/standards/instructions/no-em-dashes.md
  note     skills for [codex-cli copilot-vscode] also reach [copilot-cli crush opencode pi.dev] via ~/.agents/skills (selection botfile/standards)
  note     skills for [codex-cli] also reach [copilot-cli copilot-vscode crush opencode pi.dev] via ~/.agents/skills (selection personal)
  skipped  command/changelog on copilot-vscode (no resolved config root for this agent and kind)

synced: 7 operation(s) applied

That is a Claude rule, slash command, and skill, the Codex AGENTS.md singleton and /prompts:changelog, and a Copilot VS Code drop-in file, all from the one shared source. VS Code has no command surface, so its changelog is skipped and reported, never silent.

Adopt a skill your agent made

Skills also turn up in your agent dirs on their own: a tool like skills.sh installs one, or an agent writes one, into the shared ~/.agents/skills/ pool. That review skill is not in any source, so it is not version-controlled or shared. botfile reports it as adoptable:

botfile status

$ botfile status
managed (9)
  ~/.agents/skills/echo
  ~/.agents/skills/meow
  ~/.claude/commands/changelog.md
  ~/.claude/rules/no-em-dashes.md
  ~/.claude/skills/echo
  ~/.claude/skills/meow
  ~/.codex/AGENTS.md
  ~/.codex/prompts/changelog.md
  ~/.copilot/instructions/no-em-dashes.instructions.md
notes (3)
  note     skills for [codex-cli copilot-vscode] also reach [copilot-cli crush opencode pi.dev] via ~/.agents/skills (selection botfile/standards)
  note     skills for [codex-cli] also reach [copilot-cli copilot-vscode crush opencode pi.dev] via ~/.agents/skills (selection personal)
  skipped  command/changelog on copilot-vscode (no resolved config root for this agent and kind)
adoptable (1)
  codex-cli,copilot-vscode skill/review     ~/.agents/skills/review

9 managed, 0 out of sync, 1 skipped, 1 adoptable

Adopt it into the team repo so everyone gets it. botfile moves the skill into the source and links it back where Codex still finds it:

botfile adopt

$ botfile adopt ~/.agents/skills/review --into botfile/standards
  move   ~/.agents/skills/review -> ~/botfiles/botfile/examples/botfile_example/standards/skills/review
  link   ~/.agents/skills/review -> ~/botfiles/botfile/examples/botfile_example/standards/skills/review
  select skill/review for copilot-cli,crush,opencode,pi.dev

adopted skill/review into source "botfile" (plugin "standards")

review lived in the shared ~/.agents/skills/ pool that six agents read. The standards selection already covered codex-cli and copilot-vscode, so adopt added the smallest selection to keep it for the other four. Your config.toml now ends with that precise block:

~/.config/botfile/config.toml

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

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

[[sources]]
name = "botfile"
location = "~/botfiles/botfile/examples/botfile_example"

[[selections]]
source = "botfile"
plugin = "standards"
agents = ["claude-code", "codex-cli", "copilot-vscode"]

[[selections]]
source = "botfile"
plugin = "standards"
component = "skill/review"
agents = ["copilot-cli", "crush", "opencode", "pi.dev"]

Commit the team repo and review syncs to every teammate. Every command also accepts --format json for agents and scripts.

Advanced: let an agent manage your botfiles

You do not have to run any of this yourself: botfile is built to be driven by an agent. Every command takes --format json and returns a structured report with an authoritative exit code, and status and plan are read-only, so an agent can inspect freely and only sync once you agree. The manual an agent needs is agents.html, and the CLI ships it too: botfile guide.

Better still, hand the guide to your agents as a skill, with botfile itself. The botfile source you cloned in the import section also ships a botfile plugin whose bootstrap-botfile skill packages that same guide. Select the plugin for every agent; one more block in config.toml:

~/.config/botfile/config.toml

[[selections]]
source = "botfile"
plugin = "botfile"
agents = ["claude-code", "codex-cli", "copilot-cli",
          "copilot-vscode", "crush", "opencode", "pi.dev"]

Sync, and botfile installs the skill that explains botfile:

botfile sync

$ botfile sync
  create   ~/.agents/skills/bootstrap-botfile -> ~/botfiles/botfile/examples/botfile_example/botfile/skills/bootstrap-botfile
  create   ~/.claude/skills/bootstrap-botfile -> ~/botfiles/botfile/examples/botfile_example/botfile/skills/bootstrap-botfile
  create   ~/.claude/skills/review -> ~/botfiles/botfile/examples/botfile_example/standards/skills/review
  note     skills for [codex-cli copilot-vscode] also reach [copilot-cli crush opencode pi.dev] via ~/.agents/skills (selection botfile/standards)
  note     skills for [copilot-cli crush opencode pi.dev] also reach [codex-cli copilot-vscode] via ~/.agents/skills (selection botfile/standards/skill/review)
  note     skills for [codex-cli] also reach [copilot-cli copilot-vscode crush opencode pi.dev] via ~/.agents/skills (selection personal)
  skipped  command/changelog on copilot-vscode (no resolved config root for this agent and kind)

synced: 3 operation(s) applied

Two links put bootstrap-botfile in front of all seven agents, since one symlink in the shared pool serves six of them. The third create is sync finishing the adoption above: the standards selection covers review for Claude Code, and sync always reconciles the whole config.

From then on, ask your agent to “adopt the review skill into the team repo” or “give every agent the no-em-dashes instruction”. The skill has it run status and plan first, show you the plan, and only sync after you agree.

Support matrix

Agent	Skills	Instructions	Commands
`claude-code`	`~/.claude/skills/<name>/`	`~/.claude/rules/<name>.md` drop-in	`~/.claude/commands/<name>.md` drop-in
`codex-cli`	`~/.agents/skills/<name>/` shared	`~/.codex/AGENTS.md` singleton	`~/.codex/prompts/<name>.md` drop-in
`copilot-cli`	`~/.agents/skills/<name>/` shared	`~/.copilot/copilot-instructions.md` singleton	-
`copilot-vscode`	`~/.agents/skills/<name>/` shared	`~/.copilot/instructions/<name>.instructions.md` drop-in	-
`crush`	`~/.agents/skills/<name>/` shared	`~/.config/crush/CRUSH.md` singleton	-
`opencode`	`~/.agents/skills/<name>/` shared	`~/.config/opencode/AGENTS.md` singleton	`~/.config/opencode/commands/<name>.md` drop-in
`pi.dev`	`~/.agents/skills/<name>/` shared	`~/.pi/agent/AGENTS.md` singleton	`~/.pi/agent/prompts/<name>.md` drop-in

shared: the six terminal agents read the cross-agent ~/.agents/skills pool, so one symlink there serves all of them; Claude Code is isolated in ~/.claude/skills. drop-in: a directory of one file per component, isolated per agent. singleton: a single fixed instruction file; precedence picks the occupant and a pre-existing file is a conflict you take over by adopting it, never a clobber. A dash means the agent has no native user-scope surface for that kind.