Agents

Create specialized agent personas invoked with @mentions in chat — code reviewers, documentation writers, custom subagents with their own instructions and model overrides.

Agents are specialized subagent definitions — focused personas you invoke with @ in chat. Each agent is a single .md file with optional YAML frontmatter and markdown instructions that get injected into the conversation when the agent is mentioned.

Typical uses: a code reviewer that enforces your team's quality checks, a documentation writer that matches your house style, or a quick-answer agent pinned to a cheaper model.

Quick Start

Create an agent file in your workspace and mention it in chat:

mkdir -p ~/.fabric-agent/workspaces/{ws}/agents
cat > ~/.fabric-agent/workspaces/{ws}/agents/code-reviewer.md <<'EOF'
---
name: "Code Reviewer"
description: "Reviews code for quality, security, and best practices"
color: "green"
---

You are a meticulous code reviewer. When reviewing code:
- Verify consistent style and naming.
- Flag unnecessary complexity or duplication.
- Identify injection vulnerabilities or missing input validation.
- Be constructive and specific — suggest fixes with code examples.
EOF

Then in any chat:

@code-reviewer Please review the changes in my last commit.

The agent's instructions are injected into the conversation context, guiding the model's behavior for that interaction.

File Format

Each agent is a single .md file. The filename (without .md) becomes the agent's slug.

---
name: "Agent Display Name"     # required
description: "Short tagline"   # required — shown in @ mention menu
color: "blue"                  # optional — colored dot in UI
model: "inherit"               # optional — model override, or "inherit"
icon: "🤖"                     # optional — emoji or URL
---

# Agent Instructions

Your instructions go here. Everything below the frontmatter is injected
into the conversation when the agent is mentioned.

Required fields

name — Display name shown in the sidebar and @ mention menu.
description — One-line tagline explaining what the agent specializes in.

Optional fields

color — Visual color identifier (red, yellow, blue, green, purple, orange, …).
model — Model identifier to override the session default (e.g., claude-sonnet-4-20250514). Set to "inherit" or omit to use the current session model.
icon — Emoji character or URL to a remote image. Inline SVG and relative paths are not supported.

Storage Locations

Agents come from two places, merged at runtime:

Workspace agents

~/.fabric-agent/workspaces/{workspaceId}/agents/{slug}.md

Available in every session of that workspace. Not shared with teammates unless you explicitly commit them elsewhere.

Project agents

Live in your repository — so they ship with your code and teammates get them automatically:

{projectRoot}/.agents/agents/{slug}.md
{projectRoot}/.codex/agents/{slug}.md
{projectRoot}/.claude/agents/{slug}.md

Fabric Agents reads all three directories to stay compatible with repos already using Codex or Claude Code conventions.

Priority order

When a project agent and a workspace agent share the same slug, the project agent wins. This lets teams override workspace defaults with repo-specific agents without touching individual developer machines.

Examples

Documentation writer

---
name: "Doc Writer"
description: "Writes clear, comprehensive documentation"
color: "blue"
icon: "📝"
---

You specialize in writing clear, well-structured documentation.

- Use plain language; avoid jargon unless necessary.
- Include code examples for technical concepts.
- Structure content with clear headings and sections.
- Keep paragraphs short (3-4 sentences max).

Project manager

---
name: "PM Assistant"
description: "Helps with project planning, task breakdown, and status tracking"
color: "purple"
icon: "📋"
---

You help with project management tasks.

- Break down features into actionable tasks with effort estimates.
- Flag risks and blockers prominently.
- Draft status updates and progress reports.
- Be concise and action-oriented.

Quick helper with model override

---
name: "Quick Helper"
description: "Fast responses for simple questions using a lighter model"
color: "yellow"
model: "claude-sonnet-4-20250514"
---

You provide fast, concise answers to straightforward questions.

- Keep responses brief (1-3 sentences when possible).
- Skip preamble and get straight to the answer.
- Ask for clarification only when truly ambiguous.

When this agent is mentioned, it runs on the specified model instead of the session default — useful for routing low-stakes interactions to a cheaper model.

Subagent sessions (parent-child tree)

When you @mention an agent, Fabric Agents spawns a child session with its own conversation context, system prompt, and tools — not just an injected prompt in the parent session. The agent runs to completion and a structured summary flows back as a tool result in the parent.

What this means in practice:

The child session shows up under the parent in the sidebar's tree view with progress + completion state. Click into a child to see its full conversation, tool calls, and intermediate output.
The child session inherits permission mode, working directory, and the LLM connection from the parent. The model can be overridden via model: frontmatter on the agent.
The child's chat input is disabled — it runs autonomously until done. To intervene, cancel the child and let the parent take over, or branch the child into its own top-level session.
Multi-task spawning: Fabric Agents detects multi-task user messages ("one for X, another for Y") and spawns parallel subagent instances — one per task. Results merge back into the parent in order.
Cascade lifecycle: cancelling or deleting the parent cancels/deletes children. Cancelling a child only stops that subtree.
Cross-machine considerations: subagent sessions are first-class on disk under the same workspace, so they sync with workspaces and remote sessions identically to top-level sessions.

You'll see this in the sidebar as nested rows beneath the parent session. The child session header has a back-to-parent breadcrumb so you can pop back without losing your place.

Best Practices

One agent, one role. Narrow focus beats broad generalists.
Show, don't tell. Include example outputs so the agent matches your expectations.
Define tone explicitly. "Be concise and action-oriented" is more reliable than hoping for it implicitly.
Color by category. Assign distinct colors to agents you invoke often so they're easy to spot in the UI.
Commit high-signal agents to the repo. Anything your team should share belongs in .agents/agents/ rather than a workspace folder.

Troubleshooting

Agent doesn't appear in the mention menu

Confirm the file ends with .md and lives in one of the supported directories.
Verify frontmatter is delimited by --- on its own lines.
Check that both name and description are present and non-empty.

Agent loads the wrong version

Project agents override workspace agents with the same slug.
Check for duplicate slugs across .agents/agents/, .codex/agents/, and .claude/agents/.

Model override is ignored

The model field expects a canonical model ID. Typos fall back to inherit.
If the current session already uses a different backend that doesn't know that model, the override is skipped.