---
url: https://clusto.app/docs/agent-docs.md
description: >-
  Write AI instructions, skills, subagents, and commands once, render them per
  node, OS, and account with variables and conditional blocks, and roll them out
  to Claude Code, Codex, Gemini CLI, opencode, Copilot, and other tools.
---

# Agent Docs

The **Agent Docs** view keeps one reviewed Clusto version of your AI coding
configuration and writes it to every tool you use, on every node, for every OS
account. You write the instructions once. Each node renders them for itself,
with its own home directory, paths, and operating system, before writing the
file each tool reads.

Clusto replicates the saved version between daemons. In project scope, files on
disk change only when you apply. In user scope, nodes also keep the files and
the saved version in step on their own; see [Automatic sync](#automatic-sync-user-scope).

## Scopes

Choose a scope at the top of the view:

* **User (all nodes)** holds one user-level version for the whole cluster. Its
  files go into each tool's user config directory on every node, and
  [automatic sync](#automatic-sync-user-scope) keeps them current.
* **Project** holds one version for the selected project. Its files go into the
  project's working directory on the node that owns the project.

## Supported tools and file locations

User-scope paths are relative to the tool's user config directory. Project
paths are relative to the project's working directory. A dash means the tool
has no location for that item in that scope.

| Tool | User config directory | User instructions | Project instructions |
|------|-----------------------|-------------------|----------------------|
| Claude Code | `~/.claude` | `CLAUDE.md` | `CLAUDE.md` |
| Codex | `~/.codex` | `AGENTS.md` | `AGENTS.md` |
| Gemini CLI | `~/.gemini` | `GEMINI.md` | `GEMINI.md` |
| opencode | `~/.config/opencode` | `AGENTS.md` | - (reads `AGENTS.md`) |
| GitHub Copilot | `~/.copilot` | `copilot-instructions.md` | `.github/copilot-instructions.md` |
| Cursor | `~/.cursor` | - | `.cursorrules` |
| Windsurf | - | - | `.windsurfrules` |
| Cline | - | - | `.clinerules/clusto.md` |
| JetBrains Junie | - | - | `.junie/guidelines.md` |

Skills, subagents, and commands:

| Tool | User skills | User subagents | User commands | Project skills | Project subagents | Project commands |
|------|-------------|----------------|---------------|----------------|-------------------|------------------|
| Claude Code | `skills/` | `agents/` | `commands/` | `.claude/skills/` | `.claude/agents/` | `.claude/commands/` |
| Codex | `skills/` | - | `prompts/` | `.agents/skills/` | - | - |
| Gemini CLI | `skills/` | - | `commands/` (TOML) | `.gemini/skills/` | - | `.gemini/commands/` (TOML) |
| opencode | `skills/` | `agents/` | `commands/` | `.opencode/skills/` | `.opencode/agents/` | `.opencode/commands/` |
| GitHub Copilot | `skills/` | `agents/` (`.agent.md`) | - | `.github/skills/` | `.github/agents/` (`.agent.md`) | - |
| Cursor | - | - | `commands/` | - | - | `.cursor/commands/` |
| Windsurf | - | - | - | - | - | `.windsurf/workflows/` |
| Cline | - | - | - | - | - | `.clinerules/workflows/` |

Notes:

* The project `AGENTS.md` is one shared file. It is listed under Codex, and
  opencode, Copilot, Cursor, and other tools read it too, so only one target
  writes it.
* Cline instructions live in `.clinerules/clusto.md`, one file inside Cline's
  rules directory, so Clusto never replaces your other Cline rule files. A
  project that still has a single `.clinerules` file must turn it into a
  directory before Clusto can write there.
* Directory overrides come from the `env` table of the daemon configuration
  (the environment sessions run with): `CLAUDE_CONFIG_DIR` moves the Claude
  Code directory, `CODEX_HOME` moves the Codex directory, and
  `XDG_CONFIG_HOME` moves opencode to `$XDG_CONFIG_HOME/opencode`.
* `clusto agents tools` prints this catalog from the connected daemon.

## Instructions: one shared body

The **Instructions** card holds one **Shared body** that you write once. Each
tool target then picks a mode:

* **Shared body** writes the shared body as-is.
* **Shared + extra** writes the shared body followed by extra content for that
  tool only.
* **Custom only** ignores the shared body and writes only that tool's own
  content.

Tick only the tools Clusto should manage. A fresh version starts with every
tool unticked, so an empty draft can never erase existing files. Clusto never
writes an instruction file whose rendered content is empty: when a tool's
instructions render to nothing on a node (for example a body wrapped in an
`os=linux` block, seen on Windows), that tool's file is left exactly as it is,
the target shows `Agent Docs has no instructions for <tool> on this node;
nothing written`, and sync does not count it as an error.

Each target also has a **Where it applies** setting (see below).

## Templates: variables and blocks

Instructions, skills, subagents, and commands are templates. Each node resolves
them before writing, so the file a tool reads contains no Clusto syntax.

### Variables

Write `{{clusto:name}}` to insert a value. Built-in variables:

| Variable | Value on the target node |
|----------|--------------------------|
| `home` | Home directory of the OS account |
| `user` | OS account name |
| `os` | `linux`, `windows`, or `macos` |
| `arch` | CPU architecture, for example `x86_64` or `aarch64` |
| `node` | Node name |
| `shell` | Default shell |
| `sep` | Path separator: `\` on Windows, `/` elsewhere |
| `provider` | Tool key being written: `claude`, `codex`, `gemini`, ... |
| `provider_home` | That tool's user config directory (tools that have one) |
| `skill_dir` | Directory of the skill being written (skills only) |

Custom variables live in the **Variables** card. Each has a cluster-wide
default and optional per-node values, for example `repos` set to `/data/Repos`
by default and `C:\Repos` on a Windows node. Names use lowercase letters,
digits, and `_`, start with a letter, and cannot reuse a built-in name. From a
shell use `clusto agents vars`.

An unknown or unset variable is a render error: the file is not written, and
status shows **Render error** with the line number. Clusto never writes a blank
in place of a missing value.

### Conditional blocks

Whole-line blocks keep or drop the lines between them:

```markdown
Repositories live in {{clusto:repos}}.

<!-- clusto:if os=windows -->
Use PowerShell. Paths use backslashes.
<!-- clusto:else -->
Use bash.
<!-- clusto:end -->
```

Scripts and TOML files can use the comment form instead:

```bash
# clusto:if os=linux,macos
export PATH="$HOME/.local/bin:$PATH"
# clusto:end
```

Condition rules:

* Keys: `os`, `arch`, `node` (node name or node id), `user`, `provider`.
* `key=value` matches, `key!=value` excludes.
* A comma means OR within a term: `os=linux,macos`.
* Space-separated terms are AND: `os=windows provider=codex`.
* `clusto:else` is optional. Blocks do not nest.

The template editor has buttons that insert each variable and an OS-specific
block.

## Where it applies

Every instruction target and every skill, subagent, or command can be limited
to:

* **Operating systems**
* **Nodes**
* **OS accounts** (comma separated)

Leave everything empty to apply everywhere. On a node, account, or OS that is
excluded, the item shows **Not applicable** and is skipped.

In user scope, a tool whose user config directory does not exist on a node
(for example `~/.gemini` on a machine that never ran Gemini CLI) shows **Tool
not installed** and is skipped there. Clusto does not create a tool's config
directory. Project scope always writes into the project.

## Skills, subagents, and commands

The **Skills, subagents and commands** card stores each item once and writes it
for every tool listed under **Written for**:

* A **skill** is a whole directory: `SKILL.md` plus any scripts and references.
  Files marked **Executable** are written with the executable bit on Unix.
  Skill directories hold up to 200 files.
* A **subagent** or **command** is one Markdown file, with optional
  frontmatter in Claude Code's dialect.

Clusto converts the format where a tool differs:

* Gemini CLI commands are written as TOML with `description` and `prompt`;
  `$ARGUMENTS` becomes `{{args}}`. Import converts them back.
* opencode subagents get `description` and `mode: subagent`; GitHub Copilot
  subagents get `name` and `description` and the `.agent.md` suffix. The
  `tools` and `model` fields are dropped for these tools because tool and model
  ids are not portable between them.

Skills can hold binary files such as images, fonts, and audio. They are stored
in the record as base64, written byte for byte, and never templated. A binary
file is limited to 1 MiB and a skill to 8 MiB in total; text files keep the
256 KiB limit. A larger file is listed as **not synced** and stays local. In the
asset editor, binary files show as read-only **binary** rows. The manual
**Review node changes** import takes text only: a copy that contains binary
files cannot be imported there, but automatic sync carries them.

**Stop tracking** removes the item from Clusto and, through sync, from every
node. See [Deleting an item](#deleting-an-item).

If two tools share one directory through a symbolic link (for example a tool's
`skills` directory linked to another tool's) and the rendered content differs
between them, the write is blocked with a message naming the other tool.
Remove the link so each tool gets its own copy, or make the content identical.

## Automatic sync (user scope)

In user scope, every node keeps your Agent Docs and the files of its agent
account in step, in both directions, with no review step. It runs as part of the
[Knowledge](/knowledge) reconcile: on start, after any knowledge or Agent Docs
change, and every 5 minutes. A pass that finds nothing changed does not read
the tool files again, so the 5-minute check costs almost nothing on an idle node.
Project scope is unchanged: it stays manual
(review, import, apply), and repositories carry their own files through git.

Automatic sync is always on. Each node's [sync mode](#sync-modes) decides what
it does: two-way, receive-only, or manual. In manual mode items move only when
you send and apply them, so a node that must stay apart is set to manual.

**Capture.** A skill, subagent, or command file you edit on a node, a new one
you place in a tool's folder, or one you delete becomes the replicated record.
A new item is written for every tool that supports that kind, the same as a
manual user-scope import. Node paths are turned into variables on capture, the
same as **Replace node paths with variables**.

**Write.** Every record is rendered for the node's OS, account, and custom
variables and written into every installed tool's folder where the file is
missing or out of date. A tool whose config directory does not exist is skipped,
as before.

**Conflicts.** Sync compares three things for each file: the file on disk, the
record, and what this node last wrote.

* An edit the record has not moved past is captured.
* When both sides changed, or a file Clusto never wrote differs, the newer
  modification wins.
* A file that loses is first copied to
  `~/.clusto/agent-sync/replaced/<path relative to home>` (the latest copy only),
  then overwritten. If no copy can be kept, because the file is outside the home
  or over 1 MiB, it is not overwritten and shows under **needs review**.
* A file modified in the last 30 seconds is left for the next pass, since an
  agent may still be editing it.

**What can be captured.** An edit is captured only when it can be turned back
into the template exactly:

* The template has no `clusto:if` blocks. A node sees only its own OS branch.
* It uses only variables that map back from paths: `home`, `provider_home`,
  `skill_dir`, and custom variables whose value is a path.
* The tool stores the canonical format: Claude Code format for subagents and
  Markdown for commands. Edits to opencode or Copilot subagents and to Gemini
  TOML commands are not captured.
* Rendering the captured template again reproduces the file.

Otherwise the file is left alone and listed as **needs review in Agent Docs**.
Sync never overwrites it. Use **Review node changes** to import it by hand.

**OS handling.** A change that only alters line endings, such as CRLF from a
Windows editor, is not captured. Windows has no executable bit, so there the bit
comes from the record, or is set for files that start with `#!`.

**Instructions.** An edit to a tool's instruction file goes into the shared body
(**Shared body** mode), the tool's custom content (**Custom only**), or the
shared part when the tool's own extra text is unchanged (**Shared + extra**).
Only enabled targets are synced, and sync never ticks a new tool on. The managed
Knowledge section is ignored, as before.

### Deleting an item

* Deleting a skill, subagent, or command in Agent Docs (**Stop tracking**)
  removes it from every node. Only files Clusto wrote and nobody edited are
  removed; edited copies are kept.
* Deleting the item's folder or file from every tool on one node deletes it
  everywhere once it has stayed gone for about a minute.
* A copy edited after the deletion brings the item back. A copy edited before
  it is kept on disk but not revived.

A deletion replicates as a tombstone record, so a node that was offline cannot
bring the item back when it reconnects.

### Status and safety

The Knowledge view **AI setup** card shows an **Agent Docs sync** row with counts
for items tracked, captured, newly tracked, deleted, files written, files
removed, needs review, not synced, and errors. [`clusto doctor`](/knowledge#clusto-doctor)
shows the same check. The daemon log records a failing check once, and again
only when its detail changes, not on every 5-minute pass.

Files are read without following links out of the account's home, and a file
with more than one hard link is refused, so a planted link never makes the
daemon capture a file outside the account. Text that looks like a secret is not
captured.

Sync is free on every plan, Personal included. `[knowledge] enabled = false`
turns it off completely on a node. To change how a node takes part, pick a sync
mode.

### Sync modes

Each node has its own mode. Set `[knowledge] agent_sync` in `config.toml` to
`"two_way"` (the default), `"receive_only"`, or `"manual"`. You can also pick it
in the Knowledge view's **AI setup** card with **Skills and instructions sync**
(shown while knowledge is on), or from F1 while the Knowledge view is open:
**Agent sync on this node: Two-way**, **... Receive only**, **... Manual**.

```toml
[knowledge]
agent_sync = "receive_only"
```

* **Two-way.** Everything described above: the node captures edits, new items
  and deletions, writes the cluster's items, and removes deleted ones.
* **Receive only.** The cluster's items are written to this node, but nothing
  from the node is captured or sent. New items there are not tracked, edits are
  not captured, and deleting an item's folder there deletes nothing elsewhere
  (the cluster copy is written back). A file Clusto did not write, for example
  a company skill with the same name, is never overwritten. An edit to a file
  Clusto wrote stays until the cluster record changes; then the newer side wins
  as usual and the losing copy is kept in `~/.clusto/agent-sync/replaced/`.
  These files show under **needs review in Agent Docs** with the reason
  "edited on this node, which only receives" or "not written by Clusto, and
  this node only receives".
* **Manual.** Nothing is automatic and the node is isolated. Items move only on
  demand from Agent Docs, on that node: **Review node changes** then **Save to
  Clusto** sends an item to the cluster, and **Apply** (or a row's **write**)
  pulls items to it. **Apply to all nodes** skips manual nodes. The AI setup
  row **Agent Docs sync** shows Off with the detail "manual: send and apply
  items from Agent Docs".

Use Manual or Receive only for a machine with a different login, for example a
work laptop signed in to a company Claude account. Its skills stay apart from
your others, and you still move single items when you choose.

The first-run import of a node's existing setup into Agent Docs (see
[Knowledge](/knowledge)) runs only on a two-way node, so a receive-only or
manual node never sends its setup on first start.

## Review and import from a node

Select **Review node changes** on the Instructions card or the skills card,
choose an online node, and in user scope an OS account. Clusto scans every
supported location and marks each file **Same**, **Changed**, or **New**
(skills) or **Not found** (instructions).

**Replace node paths with variables** turns the node's literal paths back into
variables before you import: the account's home directory becomes
`{{clusto:home}}`, a tool directory becomes `{{clusto:provider_home}}`, a skill
directory becomes `{{clusto:skill_dir}}`, and path-like values of your custom
variables become those variables. A file imported this way renders correctly
on every other node.

For an instruction file:

* **Diff** compares the **Unsaved Clusto draft** with the **Node version**.
* **Use as shared body** puts the node file into the shared body.
* **Use for *tool* only** stores it as that tool's custom content.
* **Smart merge** previews a three-way merge into the shared body or the
  tool's custom content.

For skills, subagents, and commands, the scan groups the same item across tools
into one row and notes when the tools' copies differ. Pick which copy to
compare with, then use **Diff**, **Edit draft**, **Smart merge**, **Use node
version**, and **Save to Clusto**. Tick several rows and choose **Save to
Clusto** to import them in bulk. A user-scope import is written for every tool
that supports that kind of item; a project-scope import is written for the
tools that already hold it. Change the list later under **Written for**.

Discovery also scans older directory layouts (opencode's singular `agent/` and
`command/` directories, Codex's project `.codex/skills/`) and labels those
copies **old layout**. Clusto always writes to the current locations listed
above.

Discovery and editing change only the unsaved draft. **Save Clusto version**
replicates it between daemons but still writes nothing to disk.

## Smart merge and line diffs

**Smart merge** never changes the draft immediately. It opens a diff from
**Current draft** to **Merged preview**. Choose **Apply merge to draft** or
**Cancel**. If both sides rewrote the same lines, the preview reports the
conflict count and the applied draft contains `<<<<<<<` conflict markers to
resolve before saving.

Every diff in Agent Docs uses one synchronized line view. Both sides scroll
together and keep their own line numbers. Row markers:

* `-` **removed**: the line exists only on the left
* `+` **added**: the line exists only on the right
* `~` **changed**: a line and its replacement, aligned on one row

## Preview on a node

**Preview on a node** renders the unsaved draft for a chosen node and, in user
scope, OS account. It shows the context used (node, OS, account, home), the
state of each tool's file, and a diff of **On disk (current)** against the
**Rendered draft**, including render errors and why a target does not apply.
Use it to check variables and blocks before saving. Each skill, subagent, or
command editor has its own **Preview**.

## Roll out to nodes

The rollout card lists every node. Offline nodes stay visible but cannot be
checked or written. Save the Clusto version before checking or applying.

On a root daemon, an account picker chooses which OS account to render and
write for: the default session account plus every run-as user of the node's
projects. An unprivileged daemon writes only for its own account. Project scope
renders for the project's run-as user, or the default account.

Select **Check** to compare. Each file reports one state:

| State | Meaning |
|-------|---------|
| **In sync** | The file matches what Clusto would write |
| **Missing** | The file does not exist yet |
| **Outdated** | Clusto wrote the file and the saved version has changed since |
| **Edited on node** | Clusto wrote the file and someone changed it afterwards |
| **Diverged** | The file differs and Clusto never wrote it |
| **Not applicable** | The item is limited to another OS, node, account, or tool |
| **Tool not installed** | The tool's user config directory does not exist for this account |
| **Unsupported** | The tool has no location for this item in this scope |
| **Render error** | A variable is unknown or a block is malformed |

Open **diff** on a row to compare **On disk (current)** with **Clusto would
write**. **write** on a row writes only that file; **Apply** writes every
enabled instruction file and every tracked item for the node.

Missing and outdated files are written directly. Files that are **Edited on
node** or **Diverged** are only replaced after confirmation: the dialog lists
them and offers **Overwrite** or **Skip edited files**.

**Apply to all nodes** (user scope) writes to every online node, rendered for
each node's default account. It always skips edited and diverged files, offline nodes, and nodes in
[manual sync mode](#sync-modes). A manual node refuses the bulk write ("this
node syncs agent docs manually; apply on this node directly") and counts as
skipped. Apply on a single node to review and overwrite edited files, or to
write to a manual node.

**Clean up** removes files that Clusto wrote, that nobody edited since, and
that no saved instruction or item renders any more, for example after you
untick a tool. It shows the file list first and deletes
only after you confirm.

### Symbolic links

Status shows when a file is a symbolic link and where it points. A safe link
whose final target stays inside the managed root (the account's home directory
or the project directory) is preserved: Clusto writes through it, and the
confirmation says so. Clusto blocks the write when the link is broken, points
outside the managed root, or a parent directory is a link that escapes it. Fix
the link and check again. Paths are revalidated at write time, so a link
changed after review cannot redirect a write.

An absolute link, such as `~/.claude/CLAUDE.md` pointing into a dotfiles
checkout, can also be refused at write time even when its target is inside the
home. The error names the link and its target: replace the link with a regular
file (or a relative link that stays inside the home), or set
[Agent Docs sync to Manual](#sync-modes) on that node so Clusto stops trying.

When two tools reach the same file through a link (for example `CLAUDE.md`
linked to `AGENTS.md`), Clusto writes it only if both render the same content.
If they differ, the second tool is blocked with a reason: give each tool its
own file, or set both to the same content.

## From the CLI

`clusto agents` offers the same operations from a shell, including from inside
a Clusto session where the connection comes from the environment. See
[CLI Reference](/cli#clusto-agents-agent-instructions-skills-and-commands).

```bash
clusto agents status                 # user scope, this node, default account
clusto agents render --tool codex    # print what would be written
clusto agents apply --overwrite      # write, replacing edited files
clusto agents vars set repos 'C:\Repos' --node <NODE_ID>
```

[Knowledge](/knowledge) keeps a Clusto-managed section, fenced by the
`clusto:knowledge:start` and `clusto:knowledge:end` HTML comment markers, in
each tool's user instruction file. Agent Docs ignores that section when
comparing or importing and keeps it when writing, and on a fresh cluster the
node's existing user-scope setup is imported automatically once.

## Upgrading from earlier versions

Existing Agent Docs records migrate automatically and without loss:

* **Instructions**: the body most targets used becomes the **Shared body**;
  targets that held it switch to **Shared body**, and targets with different
  content keep it as **Custom only**.
* **Skills, subagents, and commands**: the old per-file entries are grouped
  into one item per name, a skill becoming one bundle with all its files. When
  tools held different copies of the same item, the most recently updated copy
  is kept and every tool stays listed under **Written for**. The older copies
  on disk then show as **Diverged** and are never overwritten without your
  confirmation.

The migration writes nothing to disk. Check a node and apply when you are
ready.
