Skills & agents

A skill is a SKILL.md file (markdown body + YAML frontmatter) that any agent inside atrium can load on demand. A named agent is a saved bundle of an adapter, a system prompt, and a list of attached skills — addressable by a kebab-case slug like qa or code-reviewer. Together they're the reusable building blocks of agent workflows: write a runbook once, attach it to any agent, spawn that agent in one keystroke.

Both live in the Skills & Agents view of either sidebar (left or right — both sides accept any of the five modes, and the mode picker is a row of icon buttons in the header instead of a dropdown).

The skills registry

atrium scans three sources on startup and watches them for changes:

• atrium-managed. ~/.atrium/skills/ (user scope, available across every workspace) and <workspace>/.atrium/skills/ (project scope, scoped to one repo). Cross-adapter — every installed adapter can read them.
• Harness-installed. ~/.claude/skills/, ~/.codex/skills/, ~/.gemini/skills/, ~/.cursor/skills/, plus the per-workspace variants (<workspace>/.claude/skills/ etc.). These are the tool-native skill directories — when you install a skill into Claude Code's own catalog, atrium picks it up automatically.
• vercel-labs/skills. The published vercel-labs/skills catalog. Skills here aren't installed until you ask atrium to fetch them — they're browse-only entries in the registry until then.

Each row in the Skills view carries: name, description, body size, byte count of any sibling scripts/ / references/ / assets/ directories, and a provenance overlay (the colored accent strip on the section header tells you which source the skill came from).

When the same skill name appears under multiple adapters at the same scope, atrium collapses them into a single composite row with adapter chips — so a code-review skill installed in Claude Code _and_ Codex shows up once, not twice, with both adapter icons in the row.

The Skills & Agents sidebar mode

Both sidebars share a row of five mode buttons in the header — Workspaces, Overview, Skills & Agents, Activity, and Timeline. Click a button to switch that side; picking a mode already mounted on the other side atomically swaps the two so you never end up with the same view on both sides. The collapsed rail keeps a compact dropdown form of the same picker. See Panes overview for the sidebar shells.

The Skills & Agents mode has its own header strip:

• Active-workspace switcher — a workspace icon + name pinned above the Skills/Agents subtabs. Click to open a dropdown of every visible workspace (worktree children indent under their parents); selecting an item switches the active workspace.
• Skills / Agents subtabs — flip between the two registries.

Skills subtab

Search filters by name and description live. A source-filter dropdown lets you hide entire sources (e.g. show only atrium-managed skills, hide vercel-labs catalog entries). A workspace-scope chip filters project-scoped entries to the active workspace.

Sections render in this order: atrium (cross-adapter), then one section per adapter (Claude Code, Codex, Gemini, Cursor Agent) for harness skills, then vercel-labs/skills at the bottom. Each section header has an adapter brand icon, a count, and a chevron to collapse it.

Right-clicking a row (or clicking the ⋮ kebab) opens the row menu with six actions:

• View metadata — opens a read-only modal showing the skill's frontmatter, file path, body size, and bundle size.
• Mention in active session — inserts a +name sigil into the focused agent pane's composer.
• Open in editor — opens the SKILL.md in a Markdown editor pane. Disabled for harness and vercel-labs skills, since those are managed by their installer's own tools.
• Copy invocation command — copies the universal $ATRIUM_CLI_PATH skills load <name> --provenance <scope> form.
• Copy composite id — copies the {scope}:{name} identifier you can paste anywhere atrium accepts a skill reference.
• Reveal in Finder — opens the skill's directory in macOS Finder.

Agents subtab

Each agent row shows its name, slug, attached-skill count, last-used relative time, and a strip of provenance dots (one per attached skill, color-coded to that skill's source). Row actions: Edit (opens the agent editor), Duplicate (creates a copy with a -copy suffix), ⎘ (copies the slug for use in a ++slug mention), ▶ (opens the Launch Agent modal), and the ⋮ kebab.

Creating a skill

The + New skill button in the Skills toolbar opens a two-stage scaffold modal.

Stage 1 — Where should the new skill live? Three radio options:

• atrium:user — writes to ~/.atrium/skills/<slug>/SKILL.md, available across every workspace.
• atrium:project — writes to <workspace>/.atrium/skills/<slug>/SKILL.md, scoped to the active workspace. Disabled when no workspace is open.
• install via vercel-labs/skills — punts to the install dialog (see below).

Stage 2 — Name + description. atrium derives a kebab-case slug from the name and enforces namespace uniqueness inside the chosen scope. A ScopeIndicator chip at the top of the stage shows the chosen scope and target directory verbatim (SCOPE atrium:user ~/.atrium/skills/) so you don't have to infer it from the slug-preview path. A ← Back button returns to Stage 1 with the chosen scope pre-selected and your typed name and description preserved, so changing scope after the fact is a round trip — not a fresh start. After save, the new SKILL.md opens in a Monaco editor pane with frontmatter validation: missing name or description keys, malformed YAML, or a name that doesn't match the directory all surface inline. Skills that fail frontmatter parsing still appear in the registry with a warning badge — they just can't be invoked until the issue is fixed.

The autocomplete dropdowns described in Sigils also pin a Create row at the top of the + skills picker and ++ agents picker — pick it to jump straight into Stage 2 with the typed query as the seed name, or to open the agent editor pre-filled.

Installing a skill from vercel-labs/skills

Pick vercel-labs in the scaffold modal (or hit the Browse vercel-labs/skills entry point) to open the install dialog. Search the catalog, then check one or more target scopes before clicking a skill's Install button:

• atrium (user) — installs to ~/.atrium/skills/<slug>/. Available everywhere.
• atrium (workspace) — installs to <workspace>/.atrium/skills/<slug>/. Disabled when no workspace is open.
• Claude Code — installs to ~/.claude/skills/<slug>/.
• Claude Code (workspace) — installs to <workspace>/.claude/skills/<slug>/.
• One row each for Codex, Gemini, and Cursor Agent, with matching (workspace) variants for installed adapters.

Each row shows the actual destination path under the label, so you can verify exactly where the skill will land before you click. Per-row retry handles partial failures — if Codex fails but Claude Code succeeds, you can retry just the failed target without re-running everything.

Named agents

An agent is { slug, name, description, adapter, prompt, attachedSkills }, saved as an editable agent.md file under ~/.atrium/agents/<slug>/. Every field except the slug is editable from the editor (or by editing the file directly); the slug is the immutable identifier you reference with ++slug (see Sigils & auto-injection). On first launch after upgrading, atrium offers to migrate any agents from the older single-directory layout into this per-agent agent.md shape.

The agent editor

Opens from + New agent or Edit on a row. The header is Name / Slug / Description; the body is split into:

• Prompt — a markdown editor with the agent's system prompt. Loaded once at launch.
• Attached skills — a search-first picker. Type to filter the entire registry; the dropdown shows composite rows (one row per skill across all adapters where it exists, with adapter chips inline) so you can pick code-review once and have it resolve to whichever adapter the spawned agent uses. Already-attached skills appear in a list below the picker; each row has a Discoverable | Pre-loaded segmented control (discovery mode vs always-loaded — see Skill modes) and an × to remove. Each row footer shows the skill's provenance in pretty form (atrium · user, Claude Code · project) and a per-row token estimate; the editor sums those alongside the prompt body for an aggregate context-cost number at the top.

Launching a named agent

The ▶ button on a row opens the Launch Agent modal. It reuses the same adapter-tile picker as the task launcher, plus an execution mode selector:

• Current branch — spawns the agent in the active workspace, on whatever branch is currently checked out.
• Fresh worktree — creates a new git worktree off a base branch, opens it as a new workspace, and spawns the agent inside it. Useful for running an agent in isolation without disturbing your current branch state.

On launch atrium prefixes the agent's first prompt with ++<slug> so the UserPromptSubmit hook expands the agent body in-place (or, on Cursor, the agent reads the fallback context note and pulls it via atrium agent definition load <slug>).

Where this fits

• Skills are runbooks — instructions the agent reads.
• Agents are pre-configured CLI sessions — system prompt + skills + adapter, bundled.
• The sidebar is how you browse and manage both.
• The +skill and ++agent sigils are how an in-pane agent (or you) actually loads them.

See Sigils & auto-injection for how mentions become real injected content at submit time, and Adapters → Overview for the canonical skill that ships with every installed adapter as the agent's atrium-CLI runbook.