SKILL.md file holds the skill definition. The folder name is the skill’s slug.
This page is the reference. For the concept, see Skills. For a walkthrough of creating one, see Write a skill.
Where skill files live
Rundock scans two locations:.claude/skills/. The Playbooks path exists for older workspace layouts, and a skill there is named to its agent but cannot be opened by it, because the agent’s runtime loads skills from .claude/skills/. Saving one in Rundock does not change it either: it creates a second skill with the same slug under .claude/skills/.
Use lowercase letters, numbers, and hyphens only in the slug. No spaces, no underscores.
Field categories
Skill frontmatter is intentionally lean. Rundock’s parser reads two fields and stops. Every other YAML key in the frontmatter block is preserved on disk, but Rundock does not act on it.- Universal fields work in any tool that supports the Claude agent and skill format. Some are read by Claude Code when the skill is loaded into a subprocess.
- Rundock-only fields are listed here only because the convention exists for agents and may surface in skill files written by hand. For skills, none of them are read.
Frontmatter fields
The minimal valid skill frontmatter is just
name and description. Both can be omitted entirely: Rundock still assigns the skill by slug, and Claude Code falls back to the first non-empty line of the body for the description. Write one anyway, because it is what the model reads when deciding whether to use the skill.
The body
Everything after the closing--- of the frontmatter is the skill’s instruction set. There is no implicit context injection at skill load: Rundock does not prepend or append anything. What you write is what the agent sees.
Write the body in the second person, addressing the agent. Match the voice of the calling agent. Skills are leaf instructions, not standalone personalities, so do not introduce a new identity in the skill body.
Length discipline
Live skills cluster around 100 to 200 lines of body text. If a skill is growing past 300 lines, it is doing too much. Split it into two skills, or move bulk into reference files in a sibling folder and link to them from the body.Reference files
A skill can keep supporting documents next to it: examples, templates, sub-routines, schemas. Put them in areferences/ folder under the skill, and link from the body with relative paths. Rundock does not parse these files; they are loaded by the agent only when the body text instructs it.
Cross-skill references
Skills can mention other skills by slug to suggest follow-on work. The orchestrator does not chain skills automatically: the agent decides whether to invoke a follow-on, based on the body’s guidance.Suggested structure
A typical skill body has six sections in this order:Skill discovery and assignment
Rundock matches skills to agents in two passes. Pass 1: explicit assignment via the agent’sskills: array. Each entry is a skill slug. This pass takes precedence: an agent matched in Pass 1 is not considered again in Pass 2 for the same skill.
Pass 2: implicit assignment via body-text scan. For every agent not matched in Pass 1, Rundock reads the agent’s body and tests whether the skill’s slug appears as a distinct word-boundary token. The match uses negative lookbehind and lookahead so partial slugs do not match.
Use explicit assignment when the relationship is permanent and load-bearing. Let body-text fallback handle weaker references.
Unassigned skills are still usable. If a skill has no owner via either pass, Rundock registers it with status: 'unassigned': it shows as unassigned in the skills panel, appears under no agent’s profile, and no leading agent’s roster lists it. Rundock does nothing else with it.
Claude Code is a separate layer. By default it offers every skill in .claude/skills/ to every agent it runs in the workspace, by name and description, whether or not Rundock assigned it, so an agent can still use an unassigned skill when the description fits the request. Skills under System/Playbooks/ are Rundock’s own location, and Claude Code does not discover them.
Only agents that are on the team are considered. An agent whose status is
available or raw is skipped entirely and gets no skills however it declares them. Nothing warns, so this reads as the assignment being broken.The rundock- prefix then gates in both directions, as two separate rules:- A platform agent, currently only Doc, is assigned
rundock-skills and nothing else. - Every other agent is assigned anything except
rundock-skills.
Workspace mode
Skills inherit the workspace mode of the agent that invokes them. There is no per-skill mode override. A skill cannot relax workspace restrictions. If a skill needs to write code in a Notes workspace, the user has to switch the workspace to Code before running it. For the workspace mode reference, see the Agent file format page.Complete worked example
Here is a complete skill file. Frontmatter is the parser-recognised set, the body is structured around the six standard sections, every step is concrete enough that the agent can follow without asking clarifying questions.- The frontmatter holds only
nameanddescription. Anything else would be ignored. - The
descriptionopens with a verb in present tense and finishes with when to use it. This is the text Claude Code offers the model when it decides whether to use the skill. - The body opens with one paragraph that re-states what the skill does, then jumps straight to “Use this skill when”.
- Steps are numbered, imperative, and reference specific file paths.
- Boundaries are explicit. This is the discipline that keeps a skill leaf-shaped.
- Formatting rules at the bottom carry house style into every output the skill produces.
Common pitfalls
A handful of specific things that go wrong silently. Rundock-only fields do nothing on a skill. SettingdisplayName, icon, colour, or any other Rundock-only field on a skill file does nothing. The fields persist but no surface reads them.
Flat skill files are not discovered. A file at .claude/skills/my-skill.md is invisible. The skill must live at .claude/skills/<slug>/SKILL.md (or the Playbooks equivalent).
Frontmatter typos fail silently. A misspelled descripton or naem is silently ignored. The skill loads with empty values for those fields.
Both skills: forms parse. The flow style skills: [a, b] is tried first and the block form is the fallback. An earlier version of this page said the flow form parsed as an empty array; in 0.15.0 it does not.
Slug case sensitivity. Rundock lowercases slugs before matching, so Hook-Generator in an agent’s skills: would match a hook-generator directory. Keep all slugs lowercase end to end for readability.
A vague name or description gets a skill overlooked. Claude Code decides whether to use a skill from its name and description, not its body, so a rich body behind a description that never says when the skill applies leaves the model nothing to match a request against. Rundock’s roster cannot make up for it: it lists skills by slug only.
Where to next
Skills concept
When to make a skill versus when to put the instruction in the agent’s body.
Write a skill
A walkthrough of creating one and assigning it to an agent.
SKILLS.md in the Rundock GitHub repo. It tracks any new fields as they ship.