Skip to main content
This guide walks through creating an agent from scratch. The example is a Research Assistant: a specialist that finds supporting facts, statistics, and references for the rest of the team. Substitute your own role if it fits better, but stay with one concrete example all the way through. Generic guides produce generic agents. If you have not yet completed first-run setup, do that first: First-run setup.

​
Before you start

You need:
  • Rundock open with a workspace selected.
  • A clear sense of what role you are creating. One sentence describing what the agent is for. If you cannot describe it in one sentence, the role is too vague to write good instructions for. Refine the role first.

​
1. Choose how to create it

There are two routes, and both write the same markdown file to your workspace:
  • Ask Doc. Open Doc from the team list (it sits under Rundock Agents), start a conversation, and give it the details from the steps below. Doc writes the file for you.
  • Write the file yourself. Create .claude/agents/<slug>.md in your workspace, with the details from the steps below as its frontmatter and the instructions as the body of the file.

​
2. Name and role

1

Slug

Use lowercase, hyphenated. The slug becomes the filename and the identifier other agents use to reference this one.Example: research-assistant
2

Display name

Short, memorable, character-style. This appears on the org chart card. Two to ten characters works well.Example: Ari (or Research Assistant if you prefer descriptive names).
3

Role

Two to four words. Sits beneath the display name on the org chart card.Example: Research Assistant
4

Description

One line saying what the agent does. It is required: an agent file without a description is never started.Example: Finds supporting facts, statistics, and references for the team.

​
3. Write the instructions

This is the most important part. The frontmatter is identity. The instructions body is behaviour. Good instructions focus on the role, not on technique. They tell the agent who it is, what it handles, what it does not handle, and how it should sound. They do not try to teach the agent how to do its job. The model already knows how to research, write, or analyse: it needs to know what role it is playing. Use this as the agent’s instructions, the body of the file, as a starting point and adapt it to your role:
Two notes on the example:
  • The first paragraph names the role and the most common hand-off shape (“when X needs Y, they hand it to you”). When the orchestrator decides whether to hand work here, it has the agent’s description, which Claude Code lists with each agent it can delegate to, and the role and capabilities.does line from Rundock’s team roster. Rundock shows this first paragraph to every other specialist on the team, so they can recognise when a request belongs here and hand it back.
  • The boundary at the bottom is non-optional. Every specialist should have one. Without it, the agent will try to do whatever you ask, even when the work belongs elsewhere.

​
4. Set the org chart position

Pick a position on the chart. The orchestrator is 0. Specialists are 1, 2, 3, and so on. Use a number that has not been claimed by another agent: collisions produce indeterminate sibling order. Set reportsTo to the slug of the agent this one reports to. For a flat team, this is the orchestrator. For a multi-level team, it is the lead specialist. You can also set:
  • An icon: a single unicode character used as the agent’s avatar. Avoid characters that look similar at small sizes.
  • A colour: a hex value for the org chart card and profile header. UK spelling: the field is colour, not color. Quotes are optional, because Rundock reads the line directly rather than as YAML. Keep any comment on its own line, not after the value.

​
5. Assign skills (optional)

If your agent should use existing skills, list them in the skills: array:
The inline form (skills: [web-search, weekly-report]) works too. Skills only attach to an agent that is on the team, which the order you set in step 4 makes it. If you do not have skills to assign yet, skip this. You can add them later. To create a skill from scratch, see Write a skill.

​
6. Save

Once the file is saved at .claude/agents/<slug>.md, whether Doc wrote it or you did, Rundock picks it up and the agent appears on the org chart in the position you set.
The agent file is just a markdown file. You can edit it directly in any text editor (VS Code, Obsidian, even TextEdit) or through Rundock’s interface. Both routes write to the same file.

​
7. Test the agent

Click the new agent on the org chart to open its profile, then press New conversation to start a conversation scoped to it. Send a real task appropriate to the role. For the Research Assistant example:
Read what comes back. Three signals to look for:
  1. Did the agent stay in its lane? The Research Assistant should return bullet points with sources, not a polished essay.
  2. Did the agent handle the boundary? If the request is partly outside scope (“research this and then draft a tweet”), the agent should hand the drafting back rather than try it.
  3. Did the agent ask for clarification when the request was ambiguous? An agent that guesses is harder to trust than an agent that asks.
If any of those land wrong, edit the instructions. The change takes effect at the start of the next conversation, not in the active one.

​
What good looks like

You know an agent is working when:
  • You can talk to it in natural language and it stays in role.
  • The orchestrator delegates the right kinds of work to it without prompting.
  • Other specialists hand off to it when their task needs help in this domain.
  • You stop noticing it. The agent does its job and you focus on the work that needs you.
Drafts get there in two or three iterations. Resist the urge to over-specify on the first pass. Write the role, test it on a real task, fix the one thing that went wrong, retest.

​
Where to next

Write a skill

Add a reusable workflow to one or more agents.

Set up a routine

Schedule a prompt to fire automatically on a cadence.

Agent file format

Every frontmatter field, with a complete worked example.

Set up a team workspace

Share your agents across a team using a synced folder.