Instruction files

An AI coding assistant reads its instruction file, such as CLAUDE.md, at the start of every session, with no tool calls. You can keep that file in Symbol as one capsule that lists other capsules, and export it to a plain file whenever it changes. The instructions then live only in Symbol, and the local file is a generated copy you can refresh at any time.

A worked exampleCopy Anchor Link

Write each capsule's summary as a "when to use this" line:

Then make an index capsule, @agents/claude-md, whose body lists them as pointer references:

~@agents/sync

~@design/web

~@design/flutter

Exporting the index capsule produces the following. Each reference is replaced where it stands and the lines around it are kept as written, so the blank lines between the references become the blank lines between the summaries:

The source of truth for this file is symbol.chat. Update it via Symbol MCP. (`@agents/sync`)

When you need to design something for web, fetch these design guidelines. (`@design/web`)

When you need to design something for Flutter, fetch these design guidelines. (`@design/flutter`)

You maintain only the list in the index capsule and the summaries of the capsules it names.

What each reference exports asCopy Anchor Link

• A pointer reference (~@type/ref) becomes the target's summary, followed by the ref in a code span. You do not have to write the ref into the summary. A summary that runs over several lines is joined into one, so it cannot break a list.
• An ordinary reference (@type/ref) becomes the target's full body, the same text an assistant receives when it reads the capsule.
• The same capsule referenced both ways exports each occurrence by how you wrote it: a summary line where you wrote ~@, the full body where you wrote @.
• A note that was converted into a log entry exports its entry: the entry's fields where you referenced it inline, and a short excerpt of them where you used a pointer.
• Everything else in the index capsule, such as headings, prose, lists and code blocks, exports unchanged. A reference inside a code span or code block is left as it is.

An ordinary reference works best on a line of its own, or first in a list item or quote: its body is inserted there and indented to match, so it stays inside the item. In the middle of a sentence, the body is inserted where the reference stands and the sentence carries on after it. When a body would otherwise swallow what follows, for example because it ends in a code block, the export starts the body or the rest of the line on a new line, and closes a code block the body leaves open.

Expansion goes one level deep. A reference inside an exported summary or body becomes a code span and is not expanded in turn, so an export never loops and never includes a capsule you did not choose. A Type or project reference also becomes a code span.

Every ref in the export sits inside a code span. Claude Code reads a bare @path in CLAUDE.md as a file import, and skips anything inside a code span. To import a local file, write @./path or @~/path in the index capsule: that is not a Symbol reference, so it exports untouched.

The reportCopy Anchor Link

Every export lists each reference it could not expand, and why. None is dropped without a word. A reference that is not expanded stays in the text as a code span of the ref.

Some references are expanded with a warning:

The export only ever includes what you can read. Two members of a team can get different exports of the same index capsule.

An export larger than 512 KiB is refused rather than cut short, and so is one whose capsules included in full hold more than 4 MiB of text between them. Use pointer references for long capsules.

An export that would take too much work to lay out is refused as well. Long runs of ordinary references that include whole capsules on one line cause this. Use pointer references for some of them, or put them on separate lines.

Export from the web appCopy Anchor Link

1. Open the capsule.
2. In its menu, choose Export as instruction file.
3. Check the preview and the report, then choose Copy or Download.

Include refresh markers is on by default. It wraps the export in the markers the Symbol CLI uses to refresh the file later. Turn it off for a file that cannot hold them. The dialog also shows the CLI command that refreshes the file.

Refresh a file from the CLICopy Anchor Link

Run the Symbol CLI with the capsule and the file:

symbol capsule export @agents/claude-md CLAUDE.md

• If the file does not exist, it is created holding the export between refresh markers.
• If the file already holds the markers for this capsule, only the text between them is replaced. Everything above and below is kept byte for byte, so you can add your own lines around the section.
• If the file exists without the markers, nothing is written. Choose --replace to replace the whole file, or --append to add a marked section at the end.

The markers name the capsule by its id, so one file can hold sections from several capsules:

<!-- symbol:export begin id=… (generated from Symbol; edit the capsule, not this section) -->
…
<!-- symbol:export end id=… -->

Edit the capsule, not the section: the next refresh replaces it. If an exported capsule contains a line that looks like one of these markers, the export rewrites it to symbol:export-quoted and lists it as marker_line, so the file can always be refreshed.

--bare writes the export with no markers. A later refresh of that file then needs --replace.

Check for drift in a hookCopy Anchor Link

--check compares the file with a fresh export and writes nothing. It exits 0 when the file is current and 3 when it is out of date, so a hook can tell "out of date" from "could not check" (exit 1, for example when offline):

symbol capsule export @agents/claude-md CLAUDE.md --check
status=$?
if [ "$status" -eq 3 ]; then
  echo "CLAUDE.md is out of date: run symbol capsule export @agents/claude-md CLAUDE.md"
elif [ "$status" -ne 0 ]; then
  echo "Could not check CLAUDE.md against Symbol"
fi

Encrypted capsulesCopy Anchor Link

The summary and title of an encrypted capsule are not encrypted, so a pointer to an encrypted capsule exports its summary from the web app and the CLI alike. An ordinary reference to an encrypted capsule is reported as encrypted, because its body cannot be decrypted outside your devices. An encrypted index capsule cannot be exported.