atrium — Docs
docs/agents/sigils.md

Sigils: inject a skill or agent with + and ++

Type +skill or ++agent in any prompt and atrium injects the body at submit time — resolution order, scope pinning, skill modes, and autocomplete pickers.

atrium ships two prompt-time shorthands that any in-pane agent (or human) can drop into a message:

  • +skill-name — auto-injects a skill's body into the current turn.
  • ++agent-slug — auto-injects a named agent's prompt and attached skills, respecting each skill's mode.
In chat panes, atrium resolves both forms when you submit a prompt and adds the resolved bodies to the model's turn context. Terminal panes depend on the tool's prompt hooks; see How injection happens.

+skill-name

The bare form auto-resolves against the skills registry using a caller-aware priority order:

  1. The caller's own harness, project scope.
  2. The caller's own harness, user scope.
  3. atrium-project (cross-harness, this project).
  4. atrium-user (cross-harness, global).
  5. Every other installed harness, in your configured adapter order.
  6. vercel-labs/skills.
The first match wins. If you want to skip the priority and pin a specific source, use +skill-name@scope — for example +atrium@harness-claude-code to pull the canonical atrium skill from Claude Code's directory, or +code-review@atrium-project to force the project-scoped variant. Available scope tokens: atrium-user, atrium-project, harness-<adapter>, harness-project-<adapter>, vercel-labs-skills.

Sigils inside fenced code blocks ( ` ) or inline backtick spans are ignored, so prose like "use +atrium in a code review" doesn't trigger resolution.

What the user sees

Tools that support hook status messages can show a confirmation after submit:

↻ loaded `atrium` from Claude Code adapter — Interact with the atrium workspace

Multiple resolved sigils stack into a bulleted block. Unresolved names are reported alongside the resolved context; hook status messages can show ⚠ unresolved: +typo, +missing-skill. The prompt still goes through, without extra context for the missing entries. In chat, use the context chip to inspect the injected context.

++agent-slug

++ is the agent shorthand. Agent slugs are globally unique within an atrium install, so there's no @scope form. When you submit ++qa explain the failing test, atrium:

  1. Looks up the agent definition by slug.
  2. Builds an expanded body from its system prompt + every attached skill, partitioned by mode (see below).
  3. Adds the body to the current turn's context.
Your prompt text stays unchanged. Repeating the same sigil within one message loads it once; mentioning it in a later message resolves it again.

Skill modes

A skill attached to an agent has one of three modes:

  • always-loaded — the full skill body is inlined into the agent's system prompt at launch. Counts against the model's context budget; use sparingly for short, high-value skills.
  • discovery — only a one-line bullet (name, description, and the exact atrium skills load … command to fetch the body) goes into the system prompt. The model reads the bullet, decides whether the skill is relevant for the current turn, and pulls the full body on demand by running the command itself.
  • disabled — the skill is attached to the agent but contributes nothing. Useful for staging a skill before you trust it enough to flip on.
Toggle the mode per skill in the agent editor's attached-skills list. Discovery is the default — it keeps the initial system prompt small and pays for skill bodies only when the agent actually needs them.

The expanded body the agent receives on a ++slug injection looks like this:

You are a QA engineer reviewing automated test runs…

# Always-loaded skills (1)

--- BEGIN SKILL: atrium (atrium-user) ---
…full SKILL.md body…
--- END SKILL: atrium (atrium-user) ---

# Discovery-mode skills (2) — load on demand

- code-review (harness-claude-code) — Review a PR against project conventions
  $ATRIUM_CLI_PATH skills load code-review --provenance harness-claude-code
- pipeline-report (atrium-user) — Generate weekly pipeline analysis
  $ATRIUM_CLI_PATH skills load pipeline-report --provenance atrium-user

Always-loaded sections are delimited with --- BEGIN/END SKILL --- markers so the model can tell where each runbook starts and ends. Discovery rows give the model everything it needs to fetch the body when the turn actually warrants it.

Autocomplete pickers

An inline autocomplete dropdown opens when you type a trigger in a composer. Agent terminal panes also offer the skill, agent, and entity pickers; their native tool handles / and @ directly.

Active triggers:

  • + — skills picker. Filters the registry as you type. Rows group by adapter applicability (a code-review skill that exists under multiple harnesses — say Claude Code, Codex, and Grok — collapses to a single row with an adapter facepile header). vercel-labs/skills appears as its own group.
  • ++ — agents picker. Filters named agents by name and slug.
  • ATR-<number> — tasks picker. Search by task number or title across known local and remote cards. Remote references include their location, such as ATR-42@server.
  • CAP-<number> — captures picker.
  • pane: / note: / room: / workspace: — entity pickers. Search by title and insert a stable reference, with a location breadcrumb where applicable. The workspace: token refers to a project. Unlike a skill or agent sigil, these add pointers the agent can resolve rather than injecting the object's full body.
  • cmd: / profile: — run-command and launch-profile pickers.
  • @ — the universal reference finder. One trigger that spans everything the others cover plus files, run commands, and launch profiles. If you only remember one trigger, remember this one.
  • / — slash commands. In a chat pane this surfaces the commands the engine itself discovered; in the launcher it also finds launch-config commands.
Results are relevance-ranked, and the popover can be filtered and section-jumped when a query spans several kinds at once.

The + and ++ pickers include a Create row after their matches. Creating a skill opens the scaffold modal with your query pre-filled; creating an agent opens its editor with the typed name. With matching entries available, Enter or Tab selects the highlighted match rather than creating a new entry.

The dropdown keeps a small contract:

  • Arrow keys navigate. Enter or Tab commits the selection. Esc dismisses that trigger occurrence and keeps it closed while you edit its query; start a new reference to reopen it.
  • Mouse hover wins over keyboard selection while the cursor is moving — keyboard nav reclaims focus the moment you press an arrow key.
  • Auto-flips above the caret when there's no room below; stays attached to the caret rect when scrolling.
  • Browser-pane click-through is paused while the dropdown is open (the overlay-suspend bridge) so picking a row doesn't get eaten by a CEF surface underneath.

How refs look in the composer

A committed reference appears inline with an icon and color indicating its kind. It can display a readable name while keeping the full path or identifier for submission. Deleting a reference removes it as one item. Attached files appear as removable chips above the input.

Selecting a skill or agent preserves the same +name / ++slug text you could type yourself. The reference's readable appearance does not change what is submitted.

How injection happens

Chat panes resolve sigils for every supported chat adapter, including Cursor Agent, Muse, and Goose. Claude Code uses its SDK prompt hook; atrium supplies the context directly for the other chat transports. A terminal tool's hook limitations do not limit its chat pane.

Terminal panes use the installed tool's hooks or extensions. Claude Code, Codex, Antigravity, OpenCode, Pi, Grok, Kimi, omp, and Hermes wire prompt-time sigil resolution through those integrations. Cursor Agent and Goose do not provide same-turn sigil injection through their terminal hooks; Muse currently has no installable terminal hook integration. Use the CLI fallback to load bodies explicitly in those terminals.

If the atrium daemon is unavailable, the terminal resolver leaves the sigils as plain text and allows submission to continue.

Seeing what was injected

Sigils aren't the only thing atrium feeds an agent — it can also surface ambient context like which background commands are already running, so the agent doesn't relaunch a server that's up. Every agent pane carries a context chip answering "what did my agent get told": click it for a popover that lists each injected piece with what triggered it, plus per-source on/off controls.

How much atrium volunteers is governed by an awareness level in settings:

  • Off — inject nothing ambient; only what you explicitly sigil.
  • Minimal — a tight, high-signal context bundle.
  • Full — the broadest ambient context atrium can assemble.

CLI fallback

Both halves of the system are reachable from the CLI for scripts, Bash-tool agents, and anyone outside the hook path:

# Load a skill body to stdout (frontmatter stripped).
"$ATRIUM_CLI_PATH" skills load atrium

# Pin a specific scope when the name is ambiguous.
"$ATRIUM_CLI_PATH" skills load code-review --provenance harness-claude-code

# Load an agent's expanded body (prompt + attached skill bodies).
"$ATRIUM_CLI_PATH" agent definition load qa

atrium skills load is what the discovery-mode bullet lines tell the model to run. atrium agent definition load (alias atrium agent def load) expands an agent's prompt and attached skills in a terminal or any environment without prompt injection.

Composite ids

Some surfaces (configuration files, telemetry, the Copy composite id menu action) need to address a skill by its full {scope}:{name} identifier. Examples:

  • atrium-user:atrium
  • atrium-project:code-review
  • harness-claude-code:pipeline-report
  • harness-project-codex:incident-postmortem
  • vercel-labs-skills:typescript-pr-review
Composite ids are what gets stored when you attach a skill to an agent, so an agent keeps working even if a same-named skill later appears under a different source.