TOOLS.md vs SKILLS.md vs MCP is a clarifier for three 📝OpenClaw and Claude Code concepts that get conflated regularly: the inventory of what an agent can reach, the catalog of installable workflows it can run, and the open protocol that lets any client connect to any external system. They overlap enough to confuse, and differ enough that mixing them up produces architectures that work poorly or duplicate effort. This memo names what each one is, what each one is not, and where new capability belongs.
TOOLS.md — The Capability Inventory
📝TOOLS.md is the OpenClaw file that lists every external capability the agent is authorized to call — APIs, command-line binaries, browsers, knowledge bases — paired with the inline procedure for using each one. Tools in this model are protocols, not modules: the agent reads "to do X, run Y with these arguments" and follows the steps. Authorization is by inclusion — if a tool is not in TOOLS.md, the agent cannot use it. The file is editable by the operator at any time without redeployment.
Use TOOLS.md when the question is "what can this agent reach?"
SKILLS.md — The Workflow Catalog
📝SKILLS.md is the registry of installable capability modules — each packaged as a directory with scripts, references, and a SKILL.md interface describing parameters and expected outputs. Where TOOLS.md lists individual levers, SKILLS.md catalogs composed workflows. A skill might wrap a Python security-scan suite, a query-knowledge script with modes and flags, or any other reusable bundle the agent can invoke without understanding internals. The agent discovers installed skills at boot via 📝BOOTSTRAP.md and routes matching requests to the correct module. The file format mirrors the broader agentskills.io open standard, so skills are portable across markdown-agent runtimes.
Use SKILLS.md when the question is "what reusable workflow does this agent know how to run?"
MCP — The Connection Protocol
📝Model Context Protocol (MCP) is the open Anthropic-led protocol — donated to the Linux Foundation in late 2025 — that standardizes how AI clients connect to external systems. An MCP server exposes tools, resources, and prompts to any MCP-compatible client (Claude Code, Claude.ai, Cursor, Windsurf, OpenClaw). It is the wire, not the inventory or the workflow.
A single MCP server can expose dozens of tools the agent then calls programmatically. Those programmatic calls are still external capabilities — they belong in TOOLS.md, described in prose, so the agent knows when and why to use them.
Use MCP when the question is "how does this agent connect to an external system at all?"
Decision Tree: Where Does New Capability Belong?
When adding a new capability to an OpenClaw agent, walk the questions in order.
- Does the capability already exist as an external system the agent needs to reach? If yes, the wire is MCP (or a direct API/CLI). Add it to TOOLS.md describing how and when to use it.
- Is the new capability a multi-step workflow the agent will reuse across many sessions? If yes, package it as a skill — directory with SKILL.md, scripts, and references — and register it in SKILLS.md.
- Is the capability a single deterministic action with no reusable composition? It belongs in TOOLS.md, not SKILLS.md. Don't promote isolated actions into skill packages.
- Are you exposing your own system to other agents? Build an MCP server. Don't fork the agent's TOOLS.md.
Common Conflations to Avoid
- "MCP server" ≠ "tool" — an MCP server is a host that exposes many tools through one connection. Each tool the agent calls via that server is still a tool entry in TOOLS.md.
- "Skill" ≠ "tool with extra docs" — if it's one call with one purpose, it's a tool. Skills earn their package overhead by composing multiple steps the agent shouldn't have to reassemble each time.
- "TOOLS.md" ≠ "function definitions" — OpenClaw tools are prose protocols, not typed function signatures. The model reads them, not a runtime registry.
- "SKILLS.md" ≠ "AGENTS.md" — skills are workflows the current agent runs. 📝AGENTS.md registers other agents the current one can delegate to.
Related
- 📝OpenClaw — the platform that defines these files
- 📝TOOLS.md — the capability inventory
- 📝SKILLS.md — the workflow catalog
- 📝Model Context Protocol (MCP) — the connection protocol
- 📝Markdown-File Agent Definition — the broader pattern these files implement
- 📝AGENTS.md — the sub-agent registry, a separate but adjacent concept
- 📝OpenClaw Glossary — vocabulary across the OpenClaw cluster