agents.md

This page is botfile's AGENTS.md: everything an AI agent needs to drive botfile on a user's machine. The CLI ships the same guide; with botfile installed, run botfile guide (or botfile guide --format markdown|json) to read it locally.

botfile manages AI-agent skills and instructions as symlinks from source repositories you control. Source code is on GitHub.

Model

Term	Meaning
`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) and an instruction (a .md file).
`selection`	A config rule mapping a source (and optionally one plugin or component) to one or more agents that should receive it.

Config

One file declares everything: ~/.config/botfile/config.toml. The smallest config that does something is one source and one selection:

~/.config/botfile/config.toml

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

[[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 two kinds differ in reach: a skill is invoked at runtime when relevant, so scoping skills to a subset of agents is rarely critical; an instruction is ambient guidance the agent harness injects into every session, so it matters that instructions can be scoped to all, some, or one agent.
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. status and plan are read-only; 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 <path> --into <source>/<plugin>: 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

Where each supported agent receives skills and instructions is listed in the support matrix.

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.