Skills

Package reusable know-how as a SKILL.md, with optional scripts and references, so agents load it when a task matches.

On this page

A skill is a SKILL.md file, optionally with scripts and reference files beside it, that teaches agents how to do one kind of task: run your migrations safely, handle Stripe webhooks, follow your voice and tone. Agents load a skill when its description matches the task in front of them. You manage workspace skills in Settings → Skills & commands.

The SKILL.md format

A skill is Markdown with YAML frontmatter:

SKILL.md
---
name: postgres-migrations
description: Write and review Postgres schema migrations that are safe on hot tables. Use when a change adds or alters tables, indexes or constraints.
agents: [builder, operator]
---

# Postgres migrations

Never take an ACCESS EXCLUSIVE lock on a hot table.

## When to use

- A change adds a table, column, index or constraint.
- A plan mentions a backfill.

## Steps

1. Read `references/hot-tables.md` to see which tables are hot.
2. Create indexes with `CREATE INDEX CONCURRENTLY`, in their own migration.
3. Add columns as nullable first; backfill in batches with `scripts/backfill.sh`.
4. Run `scripts/explain.sh <query>` and paste the plan into the PR description.
5. Write a down migration, or say in the PR why one isn't possible.

## Don't

- Don't rename a column in one step. Add, dual-write, backfill, switch reads, drop.
- Don't run a backfill without a dry run that reports the row count first.

Frontmatter fields

FieldRequiredDescription
nameYesLowercase letters, digits and dashes, for example stripe-webhooks. Unique in the workspace. Agents and people refer to it as #name.
descriptionYesOne or two sentences. Agents read this to decide when to load the skill, so say what it covers and when to use it.
agentsNoAgent names that may load it. Leave it out for every agent (“None selected = every agent”).

The body is free Markdown. A structure that works well is a one-line rule at the top, then When to use, Steps and Don’t.

Folder layout

A skill can ship files alongside SKILL.md. Upload it as a .zip with this layout:

postgres-migrations/
├── SKILL.md
├── scripts/
│   ├── backfill.sh
│   └── explain.sh
└── references/
    ├── hot-tables.md
    └── lock-levels.md
  • scripts/ holds files the agent can run. They are copied into the run’s working directory when the skill loads, and every command they run still follows command rules.
  • references/ holds longer material the agent reads only when the steps tell it to. Keeping detail here keeps SKILL.md short, which saves tokens on every run that loads it.

Refer to these files from SKILL.md with relative paths, as in the example above.

Add a skill

In Settings → Skills & commands → Workspace skills you can:

  • Drop a SKILL.md here, or a .zip with scripts and references, or choose a file. An imported skill shows “Imported #name · available to all agents”.
  • Select New skill to write one in the editor. The form has Name, Description, Instructions · SKILL.md and the agents that may use it.
  • Install one from Explore with Install skill.
  • Push one from a folder with the CLI: duun skills push ./postgres-migrations. See the CLI reference.
  • Create one with the API: POST /skills. See Skills API.

Names must be unique. If #name already exists, rename the new one or edit the existing skill.

How agents decide to load a skill

When a run starts a step, the agent sees the name and description of every skill it is allowed to use, not their bodies. If a description matches the task, the agent loads the full SKILL.md. That means:

  • The description is the trigger. “Postgres” alone is weak; “Use when a change adds or alters tables, indexes or constraints” is strong.
  • Many skills cost little until they load, but overlapping descriptions make the choice harder. Keep each skill to one job.
  • You can force a skill into a step. Add it to the step’s Skills in the workflow inspector, or mention it in instructions or a prompt as #postgres-migrations.

The run transcript shows which skills loaded in each step, so you can check that the right one fired.

Agent skills

Each agent also has its own skill list, set in its Instructions step. Skills on the agent are always offered to it; workspace skills restricted with agents: are offered only to the agents listed.

Versions

Each save creates a new version of a workspace skill. Runs already in progress keep the version they loaded; new steps use the latest. Duplicate a skill from its menu to try a change without affecting running factories.

Skills installed from Explore keep a link to their source. When the publisher releases a new version, Your library shows Update to x.y. If you edited your copy, you choose Keep my changes (copy as new) or Replace. See Update or uninstall.

Share a skill

Every workspace skill is available to the agents it allows. To share it beyond the workspace, choose Publish to Explore… from its menu. See Publishing to Explore.

    Type to search the docs, help center and blog.