skip to content

In OpenClaw, what is the difference between a skill and a plugin, and when is a skill enough?

level: juniorimportance: must knowfreq 14%

answer

  1. instructions versus code
  2. SKILL.md goes into the prompt
  3. plugins load inside the Gateway process
  4. new channel or provider needs code
  5. a skill cannot block a tool call

basics

~20 s

An OpenClaw skill is SKILL.md instructions for tools the agent already has; a plugin is code the Gateway loads in-process to add tools, channels, providers or hooks. A skill is enough when existing tools can do the work.

solid answer

~50 s

A skill is a folder with a `SKILL.md` file: YAML frontmatter plus Markdown instructions that OpenClaw lists in the agent's prompt when the skill is eligible. It adds no code and no new tools; it tells the model how and when to use `exec`, `web_fetch`, `browser` or a CLI that is already installed. A plugin is a code package (a native one ships `openclaw.plugin.json` plus a runtime module) that the Gateway imports into its own process, where it can register agent tools, a messaging channel, a model provider, typed hooks and services, and ship skills of its own. So a skill is enough when the capability exists and the agent needs a workflow or rubric. You need a plugin for a new chat platform, a new provider, a typed tool with a schema, or a hook that must block or rewrite something, because instructions only shape what the model tends to do.

go deeper

for a junior

Recall the one-line split: a skill is SKILL.md instructions for tools the agent already has, a plugin is code that adds tools, channels, providers or hooks.

for a middle

Explain where each one lands: eligible skills are listed in the agent's prompt, plugins are imported into the Gateway through a manifest and runtime module, and a plugin can ship its own skills.

for a senior

Draw the guidance-versus-enforcement line: enforcing layers such as tool policy, approvals, the sandbox or a plugin hook stop an action, and both extension types are trusted code to review.

for a principal

Frame the choice as cost and blast radius: a skill when tools exist, an external tool server when the integration already is one, and a reviewed plugin only when the Gateway itself must change.

## Two extension points that do different jobs OpenClaw's own overview splits its capabilities three ways: **tools** are callable actions (`exec`, `browser`, `web_search`, `message`), **skills** teach the agent how to work, and **plugins** add runtime capabilities such as tools, providers, channels, hooks and packaged skills. The question "skill or plugin?" is really "does the agent lack *knowledge* or lack a *capability*?" ## What a skill is A **skill** is a directory containing a `SKILL.md` file: YAML frontmatter (at minimum a `name` and a `description`) and a Markdown body of instructions. OpenClaw discovers skills from several roots, filters them at load time (for example, a skill can require a binary or an environment variable), and injects a compact list of eligible skills into the system prompt so the model can read the full instructions when a task matches. - A skill contains **no runtime code that OpenClaw loads**. It cannot register a tool, open a socket or listen to a chat platform. - It works through tools the agent already has: it might say "run `gh pr list` with `exec`, then summarise" or "fetch the status page with `web_fetch`". - Writing one is cheap: edit Markdown, and the skills watcher picks up `SKILL.md` changes on a later turn. ## What a plugin is A **plugin** is a code package the Gateway loads. A native OpenClaw plugin ships an `openclaw.plugin.json` manifest plus a TypeScript or JavaScript runtime module; OpenClaw also recognises compatible bundle layouts (Agent Plugins, Codex, Claude and Cursor) and maps their skills, commands and hook packs into its plugin inventory. A native plugin can: - register agent tools with `api.registerTool(...)`, with a typed parameter schema; - add a **messaging channel** or a **model provider** (many of OpenClaw's own channels and providers are themselves plugins); - register typed lifecycle hooks with `api.on(...)`, for example `before_tool_call`; - run services, Gateway methods and CLI commands, and list `skills` directories that load while the plugin is enabled. Native plugins run **in-process with the Gateway** and are not sandboxed, so a loaded plugin has the same trust boundary as core code. ## Choosing between them | Need | Skill enough? | Why | | --- | --- | --- | | A repeatable workflow with tools the agent has | Yes | Instructions are the missing piece | | A review rubric or house style for a task | Yes | Pure guidance | | A chat platform OpenClaw does not ship | No | Needs a channel adapter in code | | A new model or speech provider | No | Needs provider code and auth setup | | A typed tool with validated parameters | No | Tools are registered by code | | Stopping a risky call before it runs | No | Needs an enforcing layer | OpenClaw's own guidance matches this: use a skill "when the agent already has the tools it needs", and a plugin when the capability has code, credentials, lifecycle hooks, manifest metadata or installable packaging. A third option sits beside both: an external MCP server, connected under `mcp.servers`, contributes tools from a separate process and is covered with the MCP connection material. ## Guidance versus enforcement The most common confusion is treating a skill as a control. A line in `SKILL.md` such as "never delete files" shapes what the model tends to do; it does not stop anything. What can actually stop a call is code or configuration the Gateway enforces: 1. tool policy (`tools.allow` / `tools.deny`) decides which tools the model sees; 2. exec approvals and the sandbox decide whether and where a command runs; 3. a plugin's `before_tool_call` hook can return `block: true` or request approval. ## Neither one is harmless It is tempting to call skills "safe because they are only Markdown". OpenClaw's security guidance says the opposite: treat skill folders as trusted code and restrict who can modify them, because a skill's instructions can steer the agent to run commands or send data with the tools it holds. Plugins are a step further: installing one runs executable code inside the Gateway, so a malicious plugin is equivalent to arbitrary code execution in the OpenClaw process. Pick the smallest mechanism that does the job, and review either one before you trust it.

  • Can an OpenClaw plugin and a skill be combined?
    Yes. A native plugin can list skill directories in the `skills` field of `openclaw.plugin.json`, and those skills load while the plugin is enabled, so a plugin can register a tool and ship the instructions for using it. Plugin skills sit at the lowest load precedence, so a same-named workspace, managed or bundled skill overrides them.
  • Is a skill safe to install unread because it is only Markdown?
    No. A skill's instructions can steer the agent to run commands with `exec` or send data with tools it already holds, and OpenClaw's security guidance says to treat skill folders as trusted code. What limits the damage is tool policy, exec approvals and the sandbox, not the file format.

A skill is a recipe card handed to a cook who already has the kitchen's appliances; a plugin is a new appliance wired into the kitchen itself. A recipe changes how the cook works, but it cannot add an oven or lock the knife drawer.

  • A skill can add a new tool or chat channel to OpenClaw.
  • Skills are plain Markdown, so installing one unread is harmless.
  • A rule written in a SKILL.md blocks the agent from calling a tool.
  • OpenClaw plugins run sandboxed, apart from the Gateway process.
  • Supporting a new model provider only needs a skill describing its API.