Skip to content

Create a skill

DuckTapeKiller edited this page Sep 13, 2026 · 1 revision

A skill is a set of instructions the model follows for one kind of task, saved as a folder with a SKILL.md file. Writing one needs only a text editor. The same folder works in Dive, pi and Claude Code, because all three read the Agent Skills format.

This page builds a small skill step by step, then covers the rules Dive checks, bundled files, and testing.

1. Make the folder

Create a folder named after the skill inside ~/dive/skills:

mkdir -p ~/dive/skills/meeting-notes

Dive also reads ~/.agents/skills and any extra folders you add in Settings > SKILLS. Put the skill in ~/.agents/skills if you want pi to use it too; see Sharing with pi and Claude Code.

2. Write SKILL.md

Create ~/dive/skills/meeting-notes/SKILL.md:

---
name: meeting-notes
description: Turns rough meeting notes or a transcript into a short summary with decisions and action items. Use when the user pastes meeting notes or asks for minutes.
---

# Meeting notes

1. Start with a two-sentence summary of what the meeting was about.
2. List every decision under "Decisions", one per line.
3. List action items under "Actions" as "Owner: task (due date)". Write "Owner: unassigned" when nobody was named.
4. Leave out small talk. Don't invent owners, dates or decisions that aren't in the notes.

The block between the two --- lines is YAML frontmatter:

  • name uses lowercase letters, digits and single hyphens, up to 64 characters, and matches the folder name. It becomes the command /skill:meeting-notes.
  • description says what the skill does and when to use it, in under 1,024 characters. Until the model loads the skill, the description is all it sees, so name the situations that should trigger it.

Everything after the second --- is the instructions. The model receives them when the skill loads.

3. Load it and switch it on

Open Settings > SKILLS and press RELOAD SKILLS. Dive also rescans by itself, at most every two seconds. The skill appears under AGENT SKILLS with its description, its command and the folder it came from.

New skills start switched on in every mode. Use the skill's switch to turn it off in a mode.

4. Test it

There are two ways:

  • Force it. Type /skill:meeting-notes followed by your notes. Dive puts the instructions straight into your message, followed by User: and your text.
  • Let the model choose. Paste the notes and ask for a write-up. The model should call activate_skill with the skill's name before it answers, and the call appears in the Execution Trace.

If the model doesn't pick the skill on its own, make the description more specific about when it applies.

What Dive checks

Problem What happens
There's no frontmatter between --- lines at the top, or no closing --- Not loaded
The frontmatter isn't valid YAML, or isn't a set of key: value fields Not loaded
description is missing or empty Not loaded
name contains spaces, colons or control characters Not loaded
Another skill with the same name was found first Not loaded
name is missing Loads under the folder's name, with a warning
name breaks the naming rules Loads, with a warning
name doesn't match the folder Loads, with a warning
description is longer than 1,024 characters Loads, with a warning
A value contains a colon but isn't quoted Loads after Dive quotes it, with a warning

Warnings appear in the skill's entry in Settings. Skills that didn't load are listed below the others, marked "Not loaded" with the reason.

When two skills share a name, the first one found wins, in this order: ~/dive/skills, then ~/.agents/skills, then your extra folders.

Only when you ask: disable-model-invocation

Add this line to the frontmatter to keep a skill out of the list the model sees:

disable-model-invocation: true

The skill then only runs when you type its /skill: command, and Settings says so in its entry.

Bundling files

Longer material, such as a style guide or examples, can live in files next to SKILL.md, for example references/style-guide.md. Point to them from the instructions with a path relative to the skill folder.

When the model loads the skill, it receives the instructions, the skill's folder, and a list of the files in it: up to 200 files, up to four folders deep, leaving out hidden files and node_modules. To read one, it calls activate_skill again with that file's relative path. Dive only reads files inside the skill's own folder, and it hands over long text in parts of 100,000 characters.

Instructions can mention tools. If the model doesn't have a tool a skill mentions, it's told to use the fallback the instructions give, or to ask you. Dive never runs anything in a skill folder by itself.

Editing a skill

Dive reads SKILL.md again every time the skill loads, so a change to the instructions applies to the next message. A change to the name or description shows after the next rescan.

For developers

  • Everything lives in agent-skills.js. skillRoots() lists the folders, scanAgentSkills() walks them (up to five levels deep and 2,000 folders, cached for two seconds), and parseSkillFile() applies the rules above, reading the frontmatter with the yaml package.
  • buildAgentSkillsPrompt() writes the <available_skills> list into the system prompt.
  • executeActivateSkill() answers activate_skill. The instructions come back inside <skill_content name="...">, with a Skill directory: line and a <skill_resources> list. A file comes back inside <skill_file skill="..." path="...">.
  • resolveSkillCommand() and expandSkillCommandsInHistory() handle /skill:name.

Read next

Clone this wiki locally