OpenClaw has two ways to extend what your agent can do: plugins and skills. The terms sound similar and both show up in the same conversations about customizing an instance, but they work completely differently, fail completely differently, and are the right tool for completely different jobs. Confusing the two leads to over-engineering simple problems with plugins that can crash your gateway, or under-engineering complex ones with skills that cannot actually do what you need. This article explains the real distinction so you can make the right call every time.
TL;DR
- Plugins are code. They run inside the gateway process, register new tools, and can crash OpenClaw if they break.
- Skills are instructions. They are Markdown files that tell the agent how to do something. They cannot crash anything.
- Use a skill when you want to change how the agent behaves or give it a new workflow.
- Use a plugin when you genuinely need a new tool call that cannot be replicated through existing tools and instructions.
Throughout this article you will see indented blocks like the ones below. Each one is a command you can paste directly into your OpenClaw chat. Your agent will run it and report back. You do not need to open a terminal or edit any files manually.
What a plugin actually is
A plugin is a Node.js package that runs directly inside the OpenClaw gateway process. It loads when the gateway starts, executes its own initialization code, and registers one or more new named tools that the agent can call during conversations. Because a plugin is executable code running inside the same process as the gateway itself, it has access to everything the gateway has access to: the server filesystem, the network, the model API client credentials, and internal OpenClaw systems like the memory database, the LCM compaction layer, and channel integrations.
This capability level is genuinely powerful. A plugin can do things that are completely impossible without it: make authenticated HTTP calls to external APIs with managed credentials, read and write to specialized databases, expose new tool interfaces that wrap system commands or vendor SDKs, integrate with services that OpenClaw does not support natively. The plugin registers a named tool with a defined input schema, the agent calls that tool when the task requires it, and the plugin code handles all the actual work behind the tool interface.
This power comes with a real cost. A plugin that has a bug, a missing npm dependency, or an incomplete config entry can prevent the entire gateway from starting, taking the agent offline until the issue is manually resolved. A plugin that runs malicious code has exactly the same access level as the gateway process itself. A plugin that conflicts with another plugin can corrupt shared state in ways that surface as confusing, hard-to-trace behavior. Plugins are the right tool exactly when you genuinely need their power, and the wrong tool for every other situation.
Show me all currently installed plugins. For each one: the plugin name, whether it is enabled, what tools it registers, and whether it initialized successfully at the last gateway start. I want to understand what each plugin actually does at the code level, not just what its name suggests.
What a skill actually is
A skill is a Markdown file. Specifically, it is a SKILL.md file that contains structured instructions telling the agent how to handle a particular type of task or category of request. When the agent detects that an incoming request matches a skill’s description tag, it reads the relevant SKILL.md file and follows the instructions inside it as a core part of generating its response to that request.
Skills have no initialization code. They have zero npm dependencies. They cannot crash the gateway because they are not executed by the gateway at all. They are read by the agent as plain text and followed as behavioral instructions. The “execution” of a skill is the agent reading and applying its instructions to a specific request, in exactly the same way it reads and applies the guidance in SOUL.md and AGENTS.md during every response.
This architecture makes skills extremely safe to install and experiment with. Installing a skill that turns out to be wrong or unhelpful means the agent follows suboptimal instructions for that request type. It does not mean the gateway goes down or anything else breaks. Removing a skill is as simple as deleting a single file. Skills are also free to create from scratch: no npm packages, no Node.js knowledge, no deployment pipeline beyond writing a Markdown file and placing it in the correct directory.
List all installed skills in my workspace. For each skill: its name, its location, and the first two sentences of its description (from the skill’s description tag). Tell me what tasks each skill is designed to handle based on its description.
The limitation of skills is the same as their strength: they are instructions, not code. A skill can tell the agent to use existing tools in a specific sequence, format output in a particular way, or apply specific judgment rules to a category of task. A skill cannot give the agent access to a new external service, register a new tool, or perform actions that are impossible with the existing tool set.
The decision framework: plugin or skill?
The right way to decide between a plugin and a skill is to ask one precise question: does this require a new tool that does not currently exist, or does it require better instructions for using the tools that already exist?
If the answer is new instructions, use a skill. If the answer is a new tool, ask a follow-up question before defaulting to a plugin: can the same result be achieved by having the agent use web_fetch, exec, read, write, or another existing built-in tool with the right skill instructions guiding its use? If the answer to that follow-up is yes, use a skill. Only if the answer is genuinely no should you reach for a plugin.
Examples that belong in skills:
- A workflow for how the agent should research and write articles
- A persona for responding to a specific type of customer inquiry
- A set of rules for how to format code responses
- Instructions for how to handle weather requests using the existing web_fetch tool
- A process for how to audit security configurations using the existing exec and read tools
Examples that require plugins:
- A persistent LanceDB memory system that stores and retrieves embeddings
- A real-time WebSocket integration with an external trading platform
- A custom database connector that maintains a persistent connection pool
- A tool that integrates directly with a proprietary API using a vendor SDK that is not accessible via HTTP
- An integration that requires maintaining state across multiple agent turns without writing to files
I am considering whether to use a plugin or a skill for this use case: [describe what you want the agent to do]. Help me decide. Specifically: (1) What existing tools does OpenClaw already have that could accomplish this? (2) Could this be done with instructions in a SKILL.md file using only existing tools? (3) Is there anything here that genuinely requires new code running inside the gateway? Give me a recommendation with your reasoning.
How plugins load and why that matters
Understanding exactly how plugins load helps clarify why plugin failures are so disruptive compared to skill failures. When the OpenClaw gateway starts, it reads the plugins configuration from openclaw.json, imports each enabled plugin package via require(), and runs each plugin’s exported initialization function in sequence. All of this happens synchronously before the gateway is ready to accept any connections or respond to any messages. If any single plugin’s initialization function throws an unhandled error, the gateway startup fails entirely and no connections are accepted until the problem is fixed.
This is architecturally different from how many other extensible web services handle plugins. Many systems load plugins lazily (only when first needed, not at startup), in isolation (in a separate worker process that cannot crash the main service), or with graceful degradation (failing plugins are skipped rather than causing a hard stop). OpenClaw currently loads all enabled plugins synchronously in the main gateway process at startup. One plugin with a bad initialization is one failed gateway startup.
Show me the current gateway startup sequence in the logs. Run:
journalctl -u openclaw -n 100 --no-pager | grep -E "(plugin|Plugin|PLUGIN|loaded|initialized|error|Error)". I want to see which plugins loaded successfully, which had warnings, and whether any took significantly longer to initialize than others.
Plugin initialization order also matters and is frequently overlooked. If Plugin A registers a tool that Plugin B depends on, but Plugin B initializes before Plugin A in the startup sequence, Plugin B’s initialization will fail with a tool-not-found error because the tool it needs has not been registered yet. OpenClaw initializes plugins in the exact order they appear in the plugins.entries section of openclaw.json. If you have interdependent plugins, the order of their entries in your config directly determines whether they initialize successfully.
How skills load and why that is different
Skills load on demand at the moment they are needed, not at gateway startup. When the agent receives a message, it checks the list of available skill descriptions, identifies whether any skill description matches the current request, reads the SKILL.md file for any matching skill, and uses those instructions to guide the response it generates. If a SKILL.md file has a typo, unclear instruction, or incorrect assumption in it, the agent gets imperfect guidance for that request type. If a SKILL.md file is missing entirely, the agent handles the request using its general operating instructions. Neither scenario causes a crash. Neither affects any other skill, plugin, or part of the system.
This on-demand loading also means skills are effectively instantaneously installable and removable in a running system. Place a new SKILL.md file in the correct skills directory and it is available to the agent on the very next request, with no gateway restart, no config file edit, and no risk of disrupting anything that is currently working.
Check whether a skill is being applied correctly to a request. When I send the message [example request that should trigger a skill], which skill gets selected? Read the selected skill’s SKILL.md and show me the first 20 lines. Are the instructions in the skill file what I expect? This confirms the skill is loading and matching correctly.
Security implications: why they are not equivalent risks
The security risk of a plugin is categorically different from the security risk of a skill, and operators who treat them the same are significantly underestimating plugin risk. A malicious or compromised plugin runs as code inside the gateway process itself. It can silently exfiltrate API keys and secrets from your openclaw.json config, run arbitrary shell commands if exec access is enabled, make outbound network calls to attacker-controlled infrastructure, and persist across gateway restarts because it lives in the npm package directory on disk.
A malicious skill has a much smaller blast radius. It can only cause the agent to take actions using the tools that are already available. It can instruct the agent to send messages to unintended recipients, read files and include their contents in responses, or follow workflows that produce outputs the operator did not intend. These are real risks and should be taken seriously. But the blast radius of a malicious skill is bounded by the agent’s existing tool permissions. A malicious plugin is bounded by the operating system and whatever process-level access the gateway has.
Run the security audit on all currently installed skills. For each skill in my workspace skills directory, run:
python3 skills/agents-skill-security-audit/audit.py [skill]/SKILL.md. Report what each audit found. I want to know if any skill has instructions that could cause the agent to take unintended external actions.
This asymmetry in security risk is why the three-review protocol in AGENTS.md applies to plugins with much stricter scrutiny than to skills. A new skill from ClawhHub that turns out to be problematic is a bad day. A new plugin from ClawHub that turns out to be malicious, as happened with hundreds of plugins during the March 2026 security crisis, is a potentially serious compromise of the server and everything the gateway has access to.
Creating your own: skill vs. plugin
If you want to extend your OpenClaw instance yourself rather than installing something from ClawHub, the skill path is almost always where to start. Writing a SKILL.md file is the same as writing any other structured Markdown document. You define a description (so the agent knows when to use the skill), a location, and the instructions themselves. No programming knowledge required.
I want to create a new skill for this task: [describe the task]. Help me write the SKILL.md file. The skill needs: a name, a description that accurately tells the agent when to activate it (specific enough that it does not trigger on unrelated requests), a location in the skills directory, and the step-by-step instructions for how the agent should handle this type of request. Show me a draft before writing it.
Writing a plugin requires Node.js or TypeScript knowledge, familiarity with the OpenClaw plugin API, and an understanding of the gateway startup lifecycle. If you need to write a plugin because a skill genuinely cannot accomplish the task, the OpenClaw documentation and community Discord are the right starting points. The plugin API is documented and the community is active.
I want to understand what writing a plugin would require for this use case: [describe what you need]. Walk me through: (1) what tool the plugin would need to register, (2) what that tool’s function signature would look like, (3) what external packages it would need, (4) whether this is within the range of complexity that a non-expert developer could implement, or whether it is a professional development task. Do not write any code yet, just assess the scope.
When a plugin can be replaced by a skill
As OpenClaw’s built-in tool set expands, some functionality that previously required a plugin can now be achieved with a skill. If you installed a plugin a year ago that wraps a simple HTTP API, it is worth checking whether the web_fetch tool can now achieve the same result with a skill-based workflow, eliminating the plugin and its crash risk.
Review my installed plugins. For each enabled plugin, tell me: what tool does it register, what does that tool do, and could the same functionality now be achieved using existing OpenClaw built-in tools (web_fetch, exec, read, write, message, etc.) with appropriate skill instructions? I want to identify any plugins that are now redundant and could be replaced with a simpler skill-based approach.
Replacing a plugin with a skill is always worth doing when it is genuinely possible. The skill approach is safer, simpler to maintain, trivially versioned (it is just text in git), and immediately deployable without gateway restarts. The plugin approach is only irreplaceable when the task cannot be done with existing tools.
The anatomy of a skill file
A skill file has a specific structure that OpenClaw uses to decide when to activate it and how to use it. Understanding this structure helps when evaluating skills from ClawHub or writing your own.
The key parts of a skill’s SKILL.md are the name, the description tag, the location path, and the instruction body. The description tag is what the agent reads to decide whether this skill applies to an incoming request. It must be precise enough to activate on relevant requests without triggering on unrelated ones. A description that is too broad means the skill activates when it should not. A description that is too narrow means relevant requests get handled without the skill’s guidance.
Read the SKILL.md for one of my installed skills. Show me: (1) the name, (2) the description tag content, (3) the location path, and (4) the first section of instructions. Then tell me: is the description specific enough to avoid false activations on unrelated requests? Is the location path correct relative to the workspace? Is the instruction body written in a clear imperative style that the agent can follow unambiguously?
The instruction body is where operators most commonly make mistakes. Common problems include instructions that are too vague (“respond helpfully”), instructions that conflict with SOUL.md or AGENTS.md (a skill cannot override core behavioral rules), and instructions that assume tool availability that does not exist in the current installation. A good skill instruction body reads like a precise procedural guide: numbered steps, specific tool calls named where applicable, clear success criteria for each step.
I want to evaluate whether my skills are well-written. For each skill in my workspace, read its SKILL.md and rate it on three criteria: (1) description specificity (will it activate on the right requests?), (2) instruction clarity (are the steps clear and unambiguous?), (3) tool compatibility (do the instructions require any tools that are not available in my current installation?). Flag any skill that scores poorly on any criteria.
The anatomy of a plugin config entry
Every plugin in OpenClaw has a config entry in the plugins.entries section of openclaw.json. Understanding the structure of this entry helps you diagnose plugin issues and understand what each plugin requires before it will initialize successfully.
A typical plugin config entry has four fields: a unique key (the plugin’s identifier in your config), a package field (the npm package name), an enabled field (true or false), and a config object (the plugin-specific settings required for initialization). The config object varies by plugin: some require only an API key, others require multiple connection parameters, port numbers, or path settings.
Show me the plugins.entries section of my openclaw.json. For each entry: the key name, the package name, whether it is enabled, and what config keys are set (do not show the values, just the key names). Tell me if any plugin’s config object is empty or appears to be missing required fields based on what you know about that plugin type.
The config object is the most common source of plugin initialization failures. Plugins are written by different authors with different conventions for required vs. optional config. Some plugins fail silently when required config is missing (they initialize without the expected functionality). Others fail loudly and crash the gateway. Reading a plugin’s documentation or source before installing tells you which category it falls into and what config it requires.
Version compatibility: plugins vs. skills
Plugins have version compatibility concerns. An OpenClaw plugin written for version 1.x of the plugin API may behave differently or not at all on the current version. Plugins use internal OpenClaw APIs that change between releases. When OpenClaw updates, a plugin that worked before may stop working because the internal interface it depended on changed.
Skills have no version compatibility concerns. A skill written two years ago is just as valid today as when it was written, because it contains no code and depends on no APIs. The only way a skill can become outdated is if it references a specific tool by name and that tool is removed or renamed in a new OpenClaw version. That is rare and easily fixed by updating the skill instructions.
Check whether my installed plugins are compatible with the current OpenClaw version. For each enabled plugin: when was it last updated (check the npm package metadata if available), and are there any known compatibility issues with the OpenClaw version I am running? Flag any plugins that appear to be significantly out of date relative to the current gateway version.
This version compatibility asymmetry is one more strong reason to prefer skills whenever both approaches could genuinely accomplish the task. The time invested in writing a well-structured skill file is durable across OpenClaw versions because it contains no code and depends on no internal APIs. The time invested in configuring and validating a plugin may need to be revisited after significant OpenClaw updates, whenever the internal gateway API the plugin depends on has changed between releases.
Debugging each type when something goes wrong
When a plugin breaks, the debug process is gateway-level: check the startup logs, identify the initialization error, trace it to the specific plugin, and fix the config or dependency that caused the error. The fix requires gateway restarts and may require SSH access if the gateway is not starting. The investigation is code-level.
When a skill produces wrong behavior, the debug process is instruction-level: check whether the skill is being selected, read the instructions that are being followed, identify which instruction is producing the wrong behavior, and rewrite that instruction to be clearer or more specific. No restart required. No gateway risk. The investigation is text editing.
I am seeing unexpected behavior from my agent. Help me determine whether this is a plugin issue or a skill issue. The behavior is: [describe the unexpected behavior]. Ask me the following diagnostic questions one at a time: (1) Did this behavior start after a plugin change or a skill change? (2) Does the behavior occur on every request or only on specific types of requests? (3) Is the gateway showing any errors in the logs? Based on my answers, tell me whether to investigate at the plugin level or the skill level first.
A useful mental model: if the gateway started cleanly and the agent is responding but doing the wrong thing, the issue is almost certainly in instructions (skills, SOUL.md, AGENTS.md) rather than plugins. If the gateway is having trouble starting, crashing, or specific tools are failing with errors, the issue is almost certainly at the plugin or gateway configuration level.
Using plugins and skills together effectively
The most powerful OpenClaw setups use plugins and skills in combination. The plugin provides a new tool that would otherwise be impossible. The skill provides the instructions for when and how to use that tool precisely. This separation of concerns keeps each layer doing what it is best at: plugins handle capability, skills handle judgment.
A good example is the weather skill in the standard OpenClaw skill library. The skill’s description tag matches weather-related requests. The skill’s instructions tell the agent to use web_fetch against the wttr.in API with specific URL formats for different types of weather queries. No plugin required. The web_fetch tool already exists; the skill provides the judgment about when and how to use it for weather specifically.
Contrast this with a custom market data integration. If the data comes from a vendor SDK rather than a public HTTP API, web_fetch cannot reach it. A plugin is needed to wrap the SDK and expose it as an OpenClaw tool. A companion skill then provides the instructions for when to call the market data tool, how to format the results, and what to do when the data service is unavailable. The plugin provides the capability; the skill provides the operational guidance.
For each plugin I have installed: is there a corresponding skill that provides instructions for when and how to use the tools the plugin registers? If a plugin registers a tool but there is no skill guiding its use, the agent will use that tool based on general judgment rather than specific operational instructions. Identify any plugin-tool pairs that would benefit from a companion skill, and tell me what the skill’s description and key instructions should cover.
Real-world examples: which approach was right
Abstract principles about when to use a plugin vs. a skill are useful as a starting framework, but concrete examples make the distinction practically sharper and more immediately applicable. Here are six common OpenClaw extension use cases and the correct approach for each, with the specific reasoning that determines the choice.
Use case 1: The agent should respond to weather requests.
Correct approach: skill.
Reasoning: wttr.in provides weather data via public HTTP. The existing web_fetch tool can retrieve it. A skill file that matches weather requests and instructs the agent on the URL format and response structure handles this completely. No new tool is required. The weather skill in the standard library works this way.
Use case 2: The agent should store and retrieve memories across sessions.
Correct approach: plugin.
Reasoning: Persistent vector storage with embedding retrieval requires a database (LanceDB), a vector embedding model, and state that persists across gateway restarts. None of this is achievable with existing tools and a skill file. A plugin is the only path. This is what memory-lancedb-pro does.
Use case 3: The agent should always format code responses in a specific style.
Correct approach: SOUL.md or AGENTS.md instruction, not even a skill.
Reasoning: Formatting instructions that apply to every code response are global behavioral rules, not a task-specific workflow. They belong in the agent’s core operating files. A skill activates on specific request types; a global formatting rule should always be active.
Use case 4: The agent should research and write SEO articles following a specific 12-step process.
Correct approach: skill.
Reasoning: The research and writing process uses existing tools (web_search, web_fetch, write). The 12-step workflow is procedural instruction, not a new capability. A skill file that activates on content-creation requests and walks through the specific steps is exactly what skills are designed for.
Use case 5: The agent should connect to a private internal API requiring OAuth2 token refresh.
Correct approach: plugin.
Reasoning: OAuth2 token refresh requires maintaining state (the current token, its expiry time) between calls and running token refresh logic at the right moment. The web_fetch tool can make HTTP calls, but it cannot manage token lifecycle state. A plugin that handles authentication and exposes a clean tool interface is the right architecture.
I have this use case I want to implement: [describe it]. Based on the plugin vs. skill framework, which approach is correct? Walk through: (1) What existing tools could partially address this? (2) Is the remaining gap a capability gap (needs a new tool) or an instruction gap (needs clearer workflow guidance)? (3) If a plugin, what specifically would the tool it registers do that existing tools cannot? Give me a clear recommendation.
The cost of getting the choice wrong
Choosing a plugin when a skill would have worked is a tax on your operational stability. Every plugin you add is another potential startup failure, another attack surface, another dependency to keep updated, and another thing to audit when something breaks. A set of ten plugins is meaningfully harder to maintain and diagnose than a set of two plugins and eight skills that accomplish the same total functionality.
Choosing a skill when a plugin is required is a tax on your agent’s actual capability. A skill that instructs the agent to do something the available tools genuinely cannot do will produce either errors, hallucinated results where the agent pretends to have done something it could not, or partial completions that look correct but are not. Each of these is a trust problem: the agent appears to be doing the task but the output is unreliable.
Audit my current setup for both types of mismatch. (1) Are there any plugins installed that could be replaced by a skill using existing tools? These are candidates for simplification. (2) Are there any skills that instruct the agent to do things the available tools cannot actually accomplish? These are candidates for either plugin replacement or instruction correction. Show me findings in both categories.
The right balance for most OpenClaw operators is a small number of plugins that provide genuinely irreplaceable capabilities, and a larger number of skills that provide judgment, workflow guidance, and task-specific behavior. The plugins are stable and rarely need to change once correctly configured. The skills evolve continuously as the operator refines how they want the agent to behave, what workflows to use, and what judgment to apply to different request types. This clean separation of capability from judgment makes the overall system substantially easier to maintain, extend, and diagnose when something goes wrong.
Frequently asked questions
Can a skill call a tool that a plugin registered?
Yes. Skill instructions can tell the agent to call any tool that is available in the current session, including tools registered by plugins. The skill provides the workflow instructions and the plugin provides the tool. They work together. The skill describes when and how to use the tool; the plugin makes the tool available to use.
Do skills work if the gateway is restarted?
Yes. Skills are loaded from files on the filesystem. A gateway restart does not affect them. The skill files persist in the skills directory, and the agent reads them on demand after the restart exactly as before. The only way to make a skill unavailable after a restart is to delete or move its SKILL.md file.
Can I have both a plugin and a skill for the same functionality?
You can, but it creates ambiguity. If a plugin registers a tool called weather_lookup and you also have a skill that instructs the agent to use web_fetch to look up weather, the agent may use either approach depending on which it judges more appropriate for a given request. That inconsistency in behavior is usually undesirable. Pick one approach for each capability and remove the other.
Are skills on ClawHub reviewed for safety the same way plugins are?
No, and this reflects the difference in risk. Skills on ClawHub receive lighter review scrutiny because their blast radius is bounded by the agent’s existing tool permissions. Plugins receive heavier scrutiny because a malicious plugin runs as code with gateway-level access. This does not mean skills from ClawHub are safe to install without review. It means a skill audit looks different from a plugin audit. For skills, the audit focuses on what external actions the instructions could cause the agent to take. For plugins, the audit focuses on what the code does at the system level.
My agent is not following a skill’s instructions. Is that a skill problem or a model problem?
Usually a model problem or a skill matching problem. Check two things: (1) Is the skill being selected? Add a test by asking the agent which skill it is using for the request. If the answer is none, the skill’s description tag is not specific enough to match the request. Rewrite the description to more precisely describe the situations where the skill applies. (2) If the skill is being selected but instructions are not followed, the instructions are ambiguous or conflict with SOUL.md or AGENTS.md. Simplify the instructions and resolve any conflicts with higher-priority operating files.
How do I know which plugins are safe to install from ClawHub?
You cannot know from the listing alone. The three-review protocol exists precisely because ClawHub listings are operator-controlled and can misrepresent what a plugin does. Before installing any plugin: read the source code yourself or have someone with Node.js experience read it, run the security audit scanner against the SKILL.md if there is one, check the plugin’s GitHub repository for recent activity and open issues, and verify the package name on npm to confirm the publisher is who the listing claims. The March 2026 ClawHub security crisis exposed over 800 malicious plugins that had passed the listing review process. Source code review is the only reliable check.
Can skills be shared between OpenClaw instances?
Yes, easily. A skill is just a directory with a SKILL.md file. Copy the directory to the skills folder on another instance and it works immediately, no configuration required. This is why the ClawHub skills marketplace can distribute skills as zip files or git repositories rather than npm packages. Plugins require an npm publish and a specific installation process. Skills require only a file copy.