Repository navigation
Tools and skills
Dive gives the model two kinds of help: tools and skills. The names sound alike, and before version 5.0.8 Dive called both of them skills, so this page sets out what each one is, where it comes from and how it reaches the model. The rest of the wiki uses the two words in exactly this sense.
| Tool | Skill | |
|---|---|---|
| What it is | An action the model can take | Written instructions the model can follow |
| What it is made of | A name, a description, a JSON Schema for its inputs, and code | A folder with a SKILL.md file, and optional files beside it |
| What runs | Dive runs the code and hands the result back to the model | Nothing runs. The model reads the text |
| Where you manage it | Settings > TOOLS | Settings > SKILLS |
| How you force it | A slash command such as /wiki, when the tool has one |
/skill:name followed by your text |
| Shared with other apps | No, apart from MCP servers, which many apps can connect to | Yes. pi and Claude Code read the same format |
| What it can do to your computer | Whatever its code does. Risky tools ask you first | Nothing by itself. It can ask the model to use tools |
Two examples. wikipedia is a tool: the model calls it with {"query": "Nijinsky"}, Dive fetches the article, and the model reads what came back. A proofreading skill is a skill: the model loads its instructions and follows them while it corrects your text, without running anything.
| Source | What it is | Where it lives | In Settings |
|---|---|---|---|
| Native tools | The 29 tools that ship with Dive |
skills.js (ALL_SKILLS) and the skills/ folder |
TOOLS > NATIVE TOOLS |
| External tools | Plugins you install: Node.js modules that add tools and, if they want, slash commands |
~/dive/plugins, loaded by plugins.js
|
TOOLS > EXTERNAL TOOLS |
| Custom tools | A shell command or a piece of JavaScript you type into Settings | ~/dive/custom_skills-<mode>.json |
TOOLS > MANAGE CUSTOM TOOLS |
| MCP tools | Tools offered by a Model Context Protocol server that Dive starts for you | The server list is kept per mode in the window's local storage and sent to mcp.js
|
TOOLS > MCP SERVERS |
External tools and the native tools listed in Settings each have an on/off switch per mode, saved in ~/dive/skills_config-<mode>.json. In 5.0.8 the list leaves out the two browser tools, which keep their defaults: browse_read on, browse_act off. Custom tools belong to the mode you create them in. MCP servers are also set up per mode, and their tools reach the model under names of the form mcp__<server>__<tool>.
Each request works from a snapshot of what the current mode has switched on. createSkillContext() in routes/chat.js builds it once per request: the switches, the custom tools, the enabled external tools and their slash commands, the enabled skills, and a lease on the mode's MCP session. A tool can't appear or vanish halfway through a reply.
How the list is sent depends on the mode:
-
llama.cpp and LM Studio. With NATIVE TOOL CALLING switched on, Dive sends the tools in the request's
toolsarray, in the OpenAI function format (getLocalNativeTools()). If the server refuses them, Dive retries the request with the text prompt described below. -
Ollama. With NATIVE TOOL CALLING on, the tools go in Ollama's
toolsfield, and the text prompt stays in the conversation for models that ignore it. With the setting off, only MCP tools are sent that way and the rest use the text prompt. -
Cloud. The tools are described in the system prompt (
getCloudSkillsPolicyPrompt()), merged into the first system message.
The text prompt lists each tool with an example call. The model calls a tool by writing a block like this:
<call:tool_name>{"arg": "value"}</call>
Dive picks the block out of the reply, runs the tool, and removes the markup before you see the text.
executeToolCallWithConfirmation() in routes/chat.js handles every call, in this order:
- If the call names a native tool that is switched off for the mode, the model gets an error listing the tools it can use instead.
- Some tools ask for your permission first:
shell_command,run_code,run_python,macos_control,browse_act, every custom shell tool, and every external tool that setsrequiresConfirmation. Dive shows a dialog and records the request and your answer in~/dive/security-events.jsonl. If you say no, the tool doesn't run and the model is told why. If nobody answers, the timeout settings on Pi mode's MAIN tab decide; by default the request is denied after 45 seconds. - Names that start with
mcp__go to the MCP client. - Everything else goes to
executeSkill()inskills.js, which looks for a native tool first, thenactivate_skill, then an external tool, then a custom tool.
While a tool runs, the stream carries a tool_start event and then a tool_end event, and the interface shows the tool at work. The result goes back to the model, which carries on with its answer.
proofreader/
├── SKILL.md
└── references/
└── style-guide.md
SKILL.md starts with YAML frontmatter:
---
name: proofreader
description: Corrects spelling and grammar in British English. Use when the user asks for proofreading.
---
# Proofreader
Instructions for the model go here.Until the model loads a skill, the name and description are all it sees, so the description has to say when the skill applies. Create a skill walks through writing one.
| Folder | Notes |
|---|---|
~/dive/skills |
Dive's own folder |
~/.agents/skills |
A folder that pi and other agents read too |
| Extra folders | Up to 20, added in Settings > SKILLS and saved in ~/dive/skill-paths.json
|
Dive looks up to five folders deep and rescans at most every two seconds. When two skills have the same name, the one found first wins, in the order of the table above. The scanner is agent-skills.js.
- Every enabled skill is listed by name and description in the system prompt, inside an
<available_skills>block written bybuildAgentSkillsPrompt(). - The model also gets one tool,
activate_skill. When a request matches a skill, the model calls it with the skill's name and receives the instructions: the body ofSKILL.mdwithout its frontmatter. - If the instructions point to a file such as
references/style-guide.md, the model callsactivate_skillagain with that path. Dive only reads files inside the skill's own folder, and hands over long files in parts of 100,000 characters.
You can skip the matching step: type /skill:proofreader followed by your text, and Dive puts the instructions straight into your message.
A skill with disable-model-invocation: true in its frontmatter is left out of the list in step 1, so it only runs when you type its command.
Each skill has a switch per mode. It is saved as a skill:<name> key in the same skills_config-<mode>.json file as the tool switches, and new skills start switched on.
| Settings section | What it holds | Tool or skill? |
|---|---|---|
| TOOLS > NATIVE TOOLS | The tools that come with Dive | Tools |
| TOOLS > EXTERNAL TOOLS | Plugins you install | Tools |
| TOOLS > MANAGE CUSTOM TOOLS | Shell commands and JavaScript you define | Tools |
| TOOLS > BOOK SEARCH PROVIDERS | Keys and addresses for the book_search tool |
Settings for a tool |
| TOOLS > MCP SERVERS | Programs that offer tools over MCP | Tools |
| SKILLS > AGENT SKILLS |
SKILL.md folders |
Skills |
| PROMPTS > LESSONS | Standing instructions added to this mode's system prompt | Neither |
The MCP SERVERS section isn't shown in Cloud mode.
None of this applies in Pi mode, and the TOOLS and SKILLS tabs are hidden there. Dive runs pi as pi --mode rpc, and pi uses its own tools, its own skills (including the ones in ~/.agents/skills) and its own extensions. See Pi mode.
The code is older than the split between tools and skills, so many names still say "skill" where they mean a tool. If you work on the code, keep these names: settings files and existing plugins depend on them.
| Name | What it really is |
|---|---|
skills.js, ALL_SKILLS, executeSkill()
|
Native tools and the tool dispatcher |
skills/ |
The native tool implementations |
The skills key in a plugin's exports |
The plugin's list of external tools |
/api/ollama/skills/settings |
The per-mode switches, for every mode, not only Ollama |
/api/custom-skills, custom_skills-<mode>.json
|
Custom tools |
builtinSkillsGroup, customSkillsGroup
|
The NATIVE TOOLS and MANAGE CUSTOM TOOLS sections |
Agent Skills use agent-skills.js, /api/agent-skills and the skill:<name> keys.
- How the model uses tools
- Create a skill
- Create a tool
- In the repository:
docs/tools.mdanddocs/skills.md
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