Repository navigation
Create a skill
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.
Create a folder named after the skill inside ~/dive/skills:
mkdir -p ~/dive/skills/meeting-notesDive 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.
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:
-
nameuses lowercase letters, digits and single hyphens, up to 64 characters, and matches the folder name. It becomes the command/skill:meeting-notes. -
descriptionsays 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.
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.
There are two ways:
-
Force it. Type
/skill:meeting-notesfollowed by your notes. Dive puts the instructions straight into your message, followed byUser:and your text. -
Let the model choose. Paste the notes and ask for a write-up. The model should call
activate_skillwith 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.
| 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.
Add this line to the frontmatter to keep a skill out of the list the model sees:
disable-model-invocation: trueThe skill then only runs when you type its /skill: command, and Settings says so in its entry.
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.
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.
- 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), andparseSkillFile()applies the rules above, reading the frontmatter with theyamlpackage. -
buildAgentSkillsPrompt()writes the<available_skills>list into the system prompt. -
executeActivateSkill()answersactivate_skill. The instructions come back inside<skill_content name="...">, with aSkill directory:line and a<skill_resources>list. A file comes back inside<skill_file skill="..." path="...">. -
resolveSkillCommand()andexpandSkillCommandsInHistory()handle/skill:name.
These pages describe Dive 5.0.8. Source code: DuckTapeKiller/dive. Spotted a mistake? Open an issue.
Get started
Tools and skills
Build your own
Share and stay safe
How Dive works
Help