Skip to main content
A skill is a reusable workflow. A research process, a writing audit, a sales prep sequence: anything you would describe as “this is how we do X” belongs in a skill. This guide walks through creating one from scratch and assigning it to an agent. The example is a weekly report skill, but the shape applies to any procedure with steps. If you are not sure whether something should be a skill or part of an agent’s body, see Skills for the call.

​
Before you start

You need:
  • A clear procedure with discrete steps. If you cannot list the steps, the skill is not ready to write.
  • An agent (or two) that should own the skill.
  • A workspace selected in Rundock.

​
1. Create the skill folder

A skill is a folder, not a flat file. Create the folder under .claude/skills/ in your workspace. The folder name is the skill’s slug. Use lowercase letters, numbers, and hyphens only. No spaces, no underscores.
Flat skill files at .claude/skills/weekly-report.md are not discovered. Rundock only walks subdirectories looking for SKILL.md. The skill must live at .claude/skills/<slug>/SKILL.md to be picked up.

​
2. Create the SKILL.md file

Create a new file at .claude/skills/weekly-report/SKILL.md. This is where the skill definition lives.

​
3. Write the frontmatter

Skill frontmatter is lean. Two fields matter:
A few things to know about these fields:
  • name is the skill’s command name in Claude Code: it sets the / command you type to run the skill, so it needs to be a typeable name, not prose. Use the folder’s slug, lowercase and hyphenated. When name matches the slug, Rundock shows it title-cased on the agent profile and the skill list, here as Weekly Report.
  • description is one paragraph, and it is the skill’s trigger. Claude Code offers the model each skill’s name and description when it decides whether to use one, so say what the skill does and when to use it, key use case first. Rundock shows the description in its interface, but the roster Rundock gives a leading agent lists skills by slug only, so name the skill’s folder for what it is for too.
Other YAML fields you might be tempted to add (displayName, icon, colour, model, allowed-tools) are silently ignored by Rundock for skill files. The fields persist on disk but no Rundock surface reads them. Claude Code does read model and allowed-tools when it runs the skill: see the skill file format reference. Start with name and description.

​
4. Write the skill body

The body is everything after the closing --- of the frontmatter. It is the instruction set, written for the agent that will run it. There is no implicit context injection at skill load: what you write is what the agent sees. Write in the second person, addressing the agent. Match the voice of the calling agent: the skill is a leaf instruction, not a standalone personality. A typical structure:
1

When to use

A clear “Use this skill when…” opener so the agent has unambiguous entry criteria.
2

Inputs

What the skill expects to be given (a date range, a topic, a file path).
3

Steps

Numbered, imperative, concrete. Reference specific file paths and tools where relevant. The agent should not have to infer where to read or write.
4

Output format

What the skill should produce, where it should write it, and what shape the output takes.
5

Edge cases

What to do when inputs are missing, sources are unavailable, or the procedure cannot complete.
6

Boundaries

What this skill does NOT do. Critical for keeping the skill leaf-shaped.
Here is the body for the weekly report example:
A few notes on the example:
  • The “Use this skill when” opener gives the agent unambiguous entry criteria.
  • The inputs section names a default and describes accepted formats.
  • The steps reference specific file paths, tools, and folder names.
  • The output format describes shape, location, and constraints.
  • The boundaries are explicit. The skill writes the report and stops. It does not publish, modify, or schedule.
  • Length discipline: this whole skill body sits comfortably inside the 100 to 200 line range that live skills cluster around.

​
5. Assign the skill to an agent

Open the agent that should own the skill (the one whose role this skill belongs to). In the agent’s frontmatter, add or extend the skills: array:
Either form works. Rundock tries the flow style (skills: [weekly-report]) first and falls back to the block form (- lines indented under skills:), stripping quotes either way. An earlier version of this page said the flow form parsed as empty; it does not. A skill can be assigned to multiple agents. List the same slug in each agent’s frontmatter that should own it.
You can also let body-text scanning attach the skill: if the agent’s body mentions the skill’s slug as a distinct word-boundary token, Rundock auto-attaches it. Use explicit assignment when the relationship is permanent and load-bearing. Let body-text fallback handle weaker references.

​
6. Test the skill

Open a conversation with the agent that owns the skill. Trigger the skill with a request that matches its description:
The agent should pick up the skill, follow the steps, and produce output in the format you defined. If it does not, three things to check:
  1. Is the skill discovered? Restart Rundock and check the skills panel. If weekly-report does not appear, the folder structure or filename is wrong.
  2. Do the name and description say when to use it? Claude Code offers the model each skill’s name and description, and that is what it reads when deciding whether to use the skill. A vague name, or a description that never says when the skill applies, is what gets a skill overlooked.
  3. Are the steps concrete enough? The agent should not have to infer where to read or write. If it asks for clarification, the steps are too thin.
Iterate the body, not the agent. The whole point of a skill is that you can refine the procedure without touching the agent’s identity.

​
Where to next

Skill file format

Every field, with a complete worked example.

Skills concept

When to make a skill versus when to put the instruction in the agent’s body.