Agent file format

An agent in Rundock is a markdown file at <workspace>/.claude/agents/<slug>.md. The filename without .md is the agent’s slug. The file has two parts: YAML frontmatter at the top, and a markdown body underneath that becomes the agent’s system prompt. This page is the reference. For the concept, see Agents.

Field categories

Frontmatter fields fall into two categories:

Universal fields belong to the Claude agent format, and Claude Code reads them when it runs the agent. Rundock reads some of them too, and each row below says which.
Rundock-only fields are read by Rundock and silently ignored by other tools. They control how the agent looks in the org chart and how it relates to other agents.

The parser is intentionally lenient. It accepts standard YAML for the field types listed and silently ignores fields it does not recognise. Typos in field names do not raise an error. If your agent looks generic in the org chart, check field names against the table below.

Frontmatter fields

Field	Type	Scope	Required	Purpose
`name`	string	Universal	Yes	The agent’s slug. Should match the filename without the `.md` extension.
`description`	string	Universal	Yes	One-line description. Required by Claude Code: if absent, the agent is silently excluded from spawn.
`model`	string	Universal	No	The model this agent runs on, passed to the runtime unchanged. Rundock does not check it, so any identifier your runtime serves is valid, including a gateway’s or router’s own naming (`my-gateway/claude-model-id`). On a standard Claude Code setup that includes `opus`, `sonnet` and `haiku`. Leaving the field out and setting `inherit` do the same thing: Rundock asks for no particular model and your runtime uses whatever it already defaults to. `inherit` just says so explicitly, which is usually kinder to whoever reads the file next.
`tools`	array of strings	Universal	No	Allowed tools for this agent. Read by Claude Code at spawn. Not surfaced in the Rundock UI.
`displayName`	string	Rundock-only	No	Human-readable name shown in the org chart and conversation header. If omitted, Rundock title-cases the slug.
`role`	string	Rundock-only	No	Short role title shown beneath the display name on the org chart card. Two to four words.
`type`	enum	Rundock-only	No	One of `orchestrator`, `specialist`, or `platform`. Determines org chart position. Exactly one orchestrator per workspace.
`order`	number	Rundock-only	No	Numeric position on the org chart among siblings. Decimals (`1.1`, `1.2`) group sub-agents under a parent. `order: 0` does more than sort: it marks the agent as the workspace default, rewriting its id and letting `CLAUDE.md` fill in as instructions when the file has no body. Omitting it decides the agent’s status: see below.
`reportsTo`	string	Rundock-only	No, but recommended for every specialist	The slug of the agent this one reports to. Drives the org chart hierarchy and the delegation chain.
`icon`	string	Rundock-only	No	A single unicode character used as the agent’s avatar. Doc reserves `⬡`. Avoid characters that look similar at small sizes.
`colour`	string (hex)	Rundock-only	No	Accent colour for the org chart card. Hex with leading `#`. Quotes are optional: this is read with a line regex rather than YAML, so the unquoted form works and is what Rundock’s own scaffolded agents ship. UK spelling: the field is `colour`, not `color`.
`prompts`	array of strings	Rundock-only	No	Starter prompts shown in the conversation panel on first open. Two to four entries is typical.
`skills`	array of strings	Universal	No	Explicit list of skill slugs. Both the flow form (`skills: [a, b]`) and the block form parse. Rundock uses it to attach skills to the agent, and it adds to body-text scanning rather than replacing it: a slug mentioned in the body still attaches. Claude Code reads the same field and preloads each listed skill’s full content when the agent runs as a subagent.
`capabilities`	object	Rundock-only	No	Human-readable description for the profile page. Conventional keys: `does`, `reads`, `writes`, `connectors`.
`routines`	array of objects	Rundock-only	No	Scheduled tasks. Each routine has `name`, `schedule`, `prompt`, `enabled: true` to run, and an optional `description`.
`maxTurns`	number	Universal	No	Turn cap. Rundock does not read it or pass it on the command line. Claude Code reads it from the file itself.
`mcpServers`	array	Universal	No	Rundock does not read this key, and it does not appear on the profile. An earlier version of this page said it showed under connectors; it does not. Claude Code reads it from the file and connects the listed servers when the agent runs, alongside the workspace’s own `.mcp.json`.
`disallowedTools`	array of strings	Universal	No	Rundock does not read it: the disallowed-tools list Rundock passes at spawn comes from workspace mode, not from agent frontmatter. Claude Code reads the field from the file itself.

The capabilities object

The capabilities block is shown on the agent’s profile page. The parser accepts any string-valued keys, but the conventional structure is:

capabilities:
  does: One-line summary of what the agent does.
  reads: The data sources it reads from.
  writes: What it produces and where.
  connectors: Named integrations the agent uses.

Each value is a string. The convention is plain prose, not bullet lists.

The skills array

Both YAML forms parse. The flow form is tried first:

skills: [hook-generator, voice-editor, weekly-report]

and the block form, at any indent, is the fallback:

skills:
  - linkedin-hook-generator
  - voice-editor
  - readwise-highlights

Each entry is a skill slug as it appears in .claude/skills/<slug>/. Slugs are case-insensitive on the match, but write them lowercase to match directory names. The list only takes effect on an agent that is on the team: see the status table under Common pitfalls.

The routines array

Each entry is a YAML object with name, schedule, prompt, enabled, and an optional description. A routine needs enabled: true to run: without it, the routine is listed and waits to be turned on.

routines:
  - name: Morning briefing
    schedule: every day at 05:00
    prompt: Run the morning briefing
    enabled: true
    description: Triage today's tasks, calendar, and content pipeline at 5am.

The schedule field accepts only specific human-readable forms. Cron is not supported. Routines fire only while Rundock is running. A routine made in the form also carries skill, runOn, paused and plan-approval keys: see Routine format for every field, and ROUTINES.md on GitHub for the full source.

The prompts array

Starter prompts shown in the conversation panel on first open. Each entry is a complete sentence written as the user would phrase it.

prompts:
  - "Build the feature described in this spec..."
  - "Review this code before I merge it"
  - "Break this feature down into tasks"
  - "Write a spec for..."

The body

Everything after the closing --- of the frontmatter is the agent’s system prompt. Claude Code loads this verbatim when it spawns the agent. Write the body in the second person, addressing the agent as “you”. This is what Claude Code’s spawn loader expects. What goes in the body:

The agent’s identity (name, role, who they work for).
Scope: what the agent handles and what it does not.
Delegation rules: which specialists it routes to and for what.
Voice or tone guidance specific to the agent.
File path conventions, output formats, and skill usage instructions.
The “when out of scope, route back” instruction.

What does not need to go in the body:

The team roster. Rundock injects YOUR TEAMMATES at spawn time.
Delegation marker syntax. Rundock injects the delegation mechanics.
The scope boundary on what the agent can and cannot touch. Rundock and Claude Code inject this jointly.
Platform routing instructions for Doc. Rundock injects them.

Focus the body on the agent’s identity, voice, and unique instructions. Leave the team-shape and platform mechanics to Rundock.

Workspace modes

Workspace mode is a workspace-level setting, not an agent-level one. There is no per-agent override.

Mode	What it changes
Notes (default)	Restricts file writes for executable file types (`.js`, `.py`, `.sh`, etc) so agents cannot accidentally write code in a workspace of notes and documents. Commands that change something ask first.
Code	Removes the executable-file write restriction. Everyday development commands, such as git, installs, test runs and builds, run without a card in your workspace and working folders. Commands that can’t be undone, such as a force push or `sudo`, ask every time. A few that other people see first, such as pushing to the default branch, ask once and can be remembered; each is listed under Settings, Permissions, where you can revoke it.

Mode is set in Settings, under Permissions, where it is the question What are you working on?, or by editing .rundock/state.json directly:

{
  "workspaceMode": "code"
}

The stored values are notes and code. A workspace an earlier release stored as knowledge is read as Notes, and stays as it is until you change the mode. When a workspace is first opened, Rundock auto-detects the likely mode by looking at the file structure (presence of package.json, pyproject.toml, Cargo.toml, etc). Mode does not decide whether agents are kept inside the workspace. That is its own switch in the same pane, and changing mode never moves it: see Keep agents inside this workspace.

Complete worked example

Here is a complete agent file, lead-developer.md. There are no comments on the frontmatter lines, deliberately: see Common pitfalls.

---
name: lead-developer
displayName: Forge
role: Lead Developer
type: specialist
order: 4
reportsTo: chief-of-staff
icon: ⌘
colour: "#2ECC71"
model: opus
description: >
  Lead Developer responsible for all software projects, internal automations,
  and build tooling. Spec-first, incremental, quality-gated engineering.
prompts:
  - "Build the feature described in this spec..."
  - "Review this code before I merge it"
  - "Break this feature down into tasks"
  - "Write a spec for..."
---

# Forge: Lead Developer

You are Forge, the team's Lead Developer. You own all engineering work:
application code, automation scripts, and build tooling.

You report to Cos (chief-of-staff). You do not handle content creation,
research, strategy, or product decisions. If a request falls outside
engineering, route it back to Cos.

## Your scope

(rest of the body covers in-scope domains, working style, atomic commits,
project registry, and communication style)

Notes on this example:

name: lead-developer matches the filename lead-developer.md.
displayName and role are what the org chart card shows. type: specialist places it under the orchestrator.
order: 4 places Forge fourth on the chart, after the orchestrator (0) and three earlier specialists.
reportsTo: chief-of-staff puts Forge on the orchestrator’s direct line.
colour uses the UK spelling. The hex is quoted here by preference: the parser is a line regex, not YAML, so the unquoted form works too.
model takes any model your runtime serves, or inherit.
description uses YAML’s folded-scalar syntax (>) so the description spans lines while parsing as a single string.
prompts are written as the user would phrase them, not as commands.

Common pitfalls

A few specific things that go wrong silently, in roughly order of frequency. Filename does not match name. The filename is the slug. The frontmatter’s name should match. A mismatch can cause the agent to be invisible to the orchestrator’s delegation. Keep them the same. Two orchestrators in one workspace. Only one agent should have type: orchestrator. Rundock will surface both, but the delegation chain assumes a single root. The org chart and routing logic will pick one arbitrarily. reportsTo points to a slug that does not exist. The reference must resolve to another agent’s slug in the same workspace. The Workspace audit catches this. Frontmatter validates loosely. Typos in field names (displayname instead of displayName, colors instead of colour) are silently ignored. The agent loads with whatever defaults Rundock assigns. order collisions. Two specialists with the same order value appear in indeterminate sibling order. Pick a unique integer for each top-level specialist. Use decimals for sub-agents (1.1, 1.2). Comments after a value become part of the value. Rundock reads single-value fields with a line regex, not a YAML parser, so it does not strip a trailing # comment. model: opus # fast hands the runtime the model name opus # fast, and a comment after displayName shows on the org chart. Put comments on their own line. The same line regex is why a hex colour needs no quotes: colour: #E87A5A and colour: "#E87A5A" both read as #E87A5A. Status is three-state, and order alone does not decide it.

`type`	`order`	Status
any	present	`onTeam`
present	absent	`available`
absent	absent	`raw`

Skills attach only to onTeam agents. An available or raw agent gets none however it declares them, and nothing warns. If a skills: array seems to do nothing, check the status first. Other things that parse cleanly and do nothing. description: | leaves a literal pipe in the text, because only the folded > form is stripped. capabilities: needs exactly two spaces and word-character keys, or the whole block is dropped. The profile panel shows at most the first 20,000 characters of the body; the running agent still receives the whole file. Both skills: forms parse. The flow style skills: [a, b] is tried first and the block form with indented - slug lines is the fallback. An earlier version of this page said the flow form parsed as empty; it does not. Body says “you must delegate using this exact marker”. Do not write delegation marker syntax into the agent’s body. Rundock injects it at spawn time. The body should describe what to delegate and to whom, never the marker format. No “out of scope” instruction. Every specialist should include a short instruction on what to do when a request falls outside its domain: tell the user briefly, do not name other specialists, and emit  at the end of the response. Without this, the specialist will try to handle out-of-scope work itself.

Where to next

The Agents concept page covers what an agent is and how delegation works at the conceptual level.
The full source of truth is AGENTS.md in the Rundock GitHub repo. It includes the parser specifics and tracks any new fields as they ship.

Get Started

Concepts

Guides

Extending

Reference

Troubleshooting

Trust

Agent file format

Field categories

Frontmatter fields

The capabilities object

The skills array

The routines array

The prompts array

The body

Workspace modes

Complete worked example

Common pitfalls

Where to next

​Field categories

​Frontmatter fields

​The capabilities object

​The skills array

​The routines array

​The prompts array

​The body

​Workspace modes

​Complete worked example

​Common pitfalls

​Where to next

Field categories

Frontmatter fields

The capabilities object

The skills array

The routines array

The prompts array

The body

Workspace modes

Complete worked example

Common pitfalls

Where to next