Skip to content

Tools and skills

DuckTapeKiller edited this page Sep 13, 2026 · 2 revisions

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.

The difference in one table

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.

Tools

Where tools come from

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>.

How the tools reach the model

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 tools array, 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 tools field, 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.

What happens when the model calls a tool

executeToolCallWithConfirmation() in routes/chat.js handles every call, in this order:

  1. 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.
  2. 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 sets requiresConfirmation. 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.
  3. Names that start with mcp__ go to the MCP client.
  4. Everything else goes to executeSkill() in skills.js, which looks for a native tool first, then activate_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.

Skills

What a skill looks like

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.

Where Dive finds skills

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.

How a skill reaches the model

  1. Every enabled skill is listed by name and description in the system prompt, inside an <available_skills> block written by buildAgentSkillsPrompt().
  2. 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 of SKILL.md without its frontmatter.
  3. If the instructions point to a file such as references/style-guide.md, the model calls activate_skill again 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.

Telling them apart in Settings

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.

Pi 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.

Names in the code

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.

Read next

Clone this wiki locally