Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.rundock.ai/llms.txt

Use this file to discover all available pages before exploring further.

A skill in Rundock is a folder, not a flat file. Inside the folder, a single 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: 
<workspace>/.claude/skills/<slug>/SKILL.md
<workspace>/System/Playbooks/<slug>/PLAYBOOK.md
Both locations use a folder named after the slug, with a single definition file inside. The convention going forward is .claude/skills/. The Playbooks path exists for legacy Personal-OS-style workspaces.
Flat skill files at .claude/skills/<slug>.md are not discovered. Rundock only walks subdirectories looking for SKILL.md (or PLAYBOOK.md). The folder shape is required.
Same slug in both source locations: Rundock loads both as separate skill records, with the same id and slug but different source and filePath fields. The UI shows two skills with identical names. Pick one location and stick to it.
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

FieldTypeScopeRequiredPurpose
namestringUniversalRecommendedDisplay name for the skill, shown on the agent profile and in the skill list. If omitted or equal to the slug, Rundock title-cases the slug (with brand-word overrides like LinkedIn, Notion, MCP).
descriptionstringUniversalRecommendedOne-paragraph description of what the skill does and when to use it. The orchestrator uses this for routing decisions. A skill with no description is invisible to routing.
allowed-toolsarrayUniversal (Claude Code)NoTools Claude Code is allowed to invoke while running this skill. Rundock does not read this field; Claude Code does, when the skill is loaded into a subprocess.
modelstringUniversal (Claude Code)NoModel override for this skill. Same caveat as allowed-tools: Rundock does not read it, Claude Code may. In practice, behaviour follows the invoking agent’s model.
displayNamestringRundock-onlyNo (not parsed)Not parsed for skills. Rundock derives display name from name and the slug. Listed only to flag that the field is not honoured even though the convention exists for agents.
iconstringRundock-onlyNo (not parsed)Not parsed. Skills inherit the icon of their assigned agents in the UI.
colourstringRundock-onlyNo (not parsed)Not parsed. Skills inherit accent colours from their assigned agents.
The minimal valid skill frontmatter is just name and description. Both can be omitted entirely, but a skill without a description is invisible to the orchestrator’s routing decisions, so always write one.

​
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 a references/ 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. 
weekly-report/
  SKILL.md
  references/
    template.md
    examples/
      acme-q1-report.md

​
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: 
## Use this skill when

(clear "Use this skill when..." opener with trigger phrases)

## Inputs

(what the skill expects, with defaults and accepted formats)

## Steps

(numbered, imperative, concrete; reference specific paths and tools)

## Output format

(what the skill produces, where it writes, what shape)

## Edge cases

(what to do when inputs are missing or sources unavailable)

## Boundaries

(what this skill does NOT do)
Open the body with one paragraph that re-states what the skill does in slightly more depth than the description, then jump straight to “Use this skill when”. The agent reading this knows within ten seconds whether the request fits.

​
Skill discovery and assignment

Rundock matches skills to agents in two passes. Pass 1: explicit assignment via the agent’s skills: 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 callable. If a skill has no owner via either pass, it registers with status: 'unassigned'. The orchestrator can still route work to it if its description matches the request strongly enough. The skill simply does not appear under any agent’s profile until it is assigned.
Platform skills (slugs prefixed with rundock-) are gated to platform agents, currently only Doc. Non-platform agents do not see them. Non-platform skills are gated to non-platform agents and Doc does not see them.

​
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 Knowledge-mode workspace, the user has to switch the workspace to Code mode 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. 
---
name: Skill Discovery
description: Scan recent work surfaces for repeated manual patterns and propose new skills or playbooks to build, ranked by leverage.
---

Scan recent work surfaces for repeated manual patterns and produce a
ranked list of candidate skills or playbooks to build. The skill is
cadence-agnostic: it accepts a scan window argument and runs on demand.

## Use this skill when

Trigger on requests like "run skill discovery", "scan for skill
candidates", "what should I build next", "find repeated patterns I
could automate", or when invoked by a scheduled routine.

## Inputs

- **Scan window** (optional). Default: last 7 days. Accepts natural
  language ("last 14 days", "since 2026-04-01") or a day count.

## Steps

1. **Read the existing candidates file** at
   `02_Areas/System/Skill-Candidates.md` to avoid re-proposing items
   already on the list.
2. **Scan eight surfaces** for repeated manual patterns:
   - Daily notes
   - Granola meeting notes
   - Todoist task descriptions
   - Recent commits
   - Recent agent conversations
   - Skills already in `.claude/skills/`
   - Vault inbox
   - Backlog items tagged `manual`
3. **Apply detection rules:** flag any pattern that appears three or
   more times in the window with consistent shape.
4. **Score each candidate** on leverage (1 to 5), frequency (1 to 5),
   and effort to build (1 to 5). Multiply by 2x if the pattern blocks
   a primary goal.
5. **Write the proposal** to the candidates file, sorted by total score
   descending. Include a one-line trigger phrase, the source surface,
   and the score breakdown for each.

## Output format

Append-only entries in `02_Areas/System/Skill-Candidates.md`. One entry
per candidate. Each entry contains: name, trigger, source, score
breakdown, status (`proposed`).

## Edge cases

- **No daily notes for some days in window:** skip silently.
- **Granola folder missing or empty:** skip the Granola surfaces. Note
  in the run footer.
- **Existing candidate with similar trigger phrase:** add a cross-link
  rather than a new entry.

## Boundaries

- This skill proposes candidates only. It does NOT create skills,
  agents, playbooks, or any system file.
- It does NOT auto-promote candidates to the backlog.
- It does NOT modify candidate statuses on subsequent runs.

## Formatting rules

UK spelling. No em or en dashes. Use wikilinks `[[...]]` for vault
references.
Notes on this example:
  • The frontmatter holds only name and description. Anything else would be ignored.
  • The description opens with a verb in present tense and finishes with the trigger phrase. This is the field the orchestrator reads when deciding whether to route work.
  • 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. Frontmatter beyond name and description is ignored. Setting displayName, 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. Inline skills: arrays on the agent side do not parse. The flow-style skills: [a, b] parses as an empty array on the agent file. Always use the block form. 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. Description is the routing signal. The orchestrator reads the skill’s description field, not its body, when deciding whether to route work. A skill with no description is invisible to routing, even if the body is rich.

​
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.
The full source of truth is SKILLS.md in the Rundock GitHub repo. It tracks any new fields as they ship.