Reading time: 9 min · Last updated: 2026-06-15 · By: GolemWorkers Team

TL;DR. Skills are local workflow knowledge — markdown plus optional scripts the agent loads on demand from ~/.openclaw/skills/ or ClawHub. Plugins are external connector packages with a plugin.json manifest declaring MCP servers, app integrations, hooks, and bundled sub-skills. Use a skill when you want the agent to know a workflow. Use a plugin when you want the agent to reach an external service.

The 30-second mental model: skill vs plugin in OpenClaw

OpenClaw is a managed agent platform. If you've read GolemWorkers: the AI worker platform explained, you know the runtime is an LLM with a workspace, memory, and tool calls. The question every new builder hits on day two is: how do I extend the agent?

There are two extension mechanisms. They are not interchangeable.

• A skill teaches the agent a workflow. A skill is a folder of plain markdown and optional scripts. The agent reads it like a handbook. It tells the agent how to do something — the conventions, the templates, the labels, the questions to ask first.
• A plugin connects the agent to a service. A plugin is a package with a plugin.json manifest that declares MCP servers, app integrations, lifecycle hooks, and bundled sub-skills. A plugin is infrastructure — it gives the agent new tool calls that hit external APIs.

If you remember nothing else: the skill owns the workflow, the plugin owns the connector.

What an OpenClaw skill actually is (file layout, when it loads)

A skill is a local artifact. It lives in one of two places:

• ~/.openclaw/skills/<name>/ — the per-user skills directory, picked up on agent start.
• The ClawHub registry — clawhub install <slug> drops the skill into the same directory on your behalf.

The shape is deliberately boring: a folder, a SKILL.md, and optionally some helpers. No build step, no manifest, no runtime.

# ~/.openclaw/skills/gh-issues/SKILL.md  (front matter)
          name: gh-issues
          version: 0.4.2
          description: Create, triage, and link GitHub issues with the team's conventions.
          triggers:
          - "open an issue"
          - "file a bug"
          - "triage this repo"
          allowed_tools:
          - shell
          - web_fetch
          

The body of SKILL.md is plain English the agent reads when a trigger matches. The gh-issues skill is the canonical example: it codifies the team's bug-report template, label taxonomy, and reviewer routing so the agent does not improvise them on every request.

# gh-issues skill
          ## When to load
          File, triage, comment on, or close a GitHub issue. Not for read-only "list" requests.
          ## Conventions
          - `bug` template unless the user says "feature" or "chore".
          - Title: imperative mood, ≤ 72 chars, no trailing period.
          - Body: `## Summary`, `## Repro`, `## Expected`, `## Actual`, `## Logs`. Skip empty ones.
          - Labels: `area:<module>` from touched paths; `severity:s0..s3` from framing;
          `needs-triage` if confidence < 0.7. Reviewers: `CODEOWNERS`, fall back to `@platform-oncall`.
          ## Workflow
          1. Ask for any missing repro details before opening.
          2. `gh issue create --label <labels> --title <t> --body <b>` from a worktree.
          3. Echo the URL back; offer to ping reviewers via `gh pr edit --add-reviewer`.
          

That is the whole skill. No daemon, no socket, no auth flow. The agent still talks to GitHub through whatever tools it already has — typically shell for the gh CLI and web_fetch for the API fallback. The skill is the brain; the tools are the hands.

Three properties follow:

• Skills are cheap. Adding one is mkdir and writing markdown. You can have 200 skills; the agent only reads the ones that match.
• Skills are version-controlled. Drop the folder in a git repo and your teammates get the same conventions. This is the right unit of sharing for team-internal workflows.
• Skills do not give the agent new powers. They reshape how it uses the powers it already has. If the gh CLI is not authenticated, the skill cannot conjure auth out of thin air.

The seo, tailwind, three, gsap, and healthcheck skills all follow this pattern: pure knowledge, no network endpoints of their own.

What an OpenClaw plugin actually is (plugin.json, MCP servers, apps, hooks)

A plugin is the other thing. Where a skill is a markdown handbook, a plugin is a packaged integration that adds real tool calls.

A plugin lives in ~/.openclaw/extensions/<name>/ (installed by the plugin installer) and is described by a single file: plugin.json. That manifest is the contract:

{
          "name": "composio",
          "version": "0.9.1",
          "description": "Composio adapter — 200+ third-party MCP servers behind one install.",
          "interface": {
          "icon": "🔌",
          "category": "integrations",
          "default_prompts": [
          "Open an issue on my repo",
          "List my Linear tickets",
          "Post a message to #releases in Slack"
          ]
          },
          "mcpServers": {
          "composio": {
          "command": "composio-mcp",
          "args": ["serve", "--toolkit=*"],
          "env": { "COMPOSIO_API_KEY": "${secret:composio_api_key}" }
          }
          },
          "apps": [
          { "id": "github", "auth": "oauth2", "scopes": ["repo", "read:user"], "provider": "composio-mcp" }
          ],
          "hooks": {
          "on_agent_start": "scripts/check-credentials.sh",
          "on_tool_error":  "scripts/log-failure.sh"
          },
          "skills": [
          { "slug": "composio-github", "version": "^1.0.0" }
          ]
          }
          

Four sections matter:

• mcpServers — the Model Context Protocol servers the plugin exposes. Each one is a subprocess the agent can speak MCP to. The composio plugin runs one MCP server that fronts 200+ toolkits; a smaller plugin like attio might run one for Attio and nothing else.
• apps — declarative app manifests: auth method, OAuth scopes, which provider backs it. The platform uses this to render the "connect your account" UI and to wire credentials.
• hooks — lifecycle entry points the platform calls into. on_agent_start checks that credentials are still valid; on_tool_error logs to Sentry or posts a Slack alert.
• skills — bundled sub-skills. A plugin can ship its own markdown handbooks so the agent knows how to use the connector it just got. The composio plugin ships composio-github for exactly this reason: the connector is useless without the workflow that wraps it.

The interface block is metadata only — icon, category, default prompts. It does not change what the agent can do; it changes how the plugin presents itself.

Real examples in the OpenClaw catalog today: apollo, attio, airtable, asana, atlassian-rovo, calendly, canva. Each one is a packaged MCP server (or a few) plus an app manifest. composio is the general-purpose aggregator archetype — one plugin, many toolkits, one install.

For deployment on your own infrastructure, see how to deploy an AI agent on your own server; the plugin install path is the same whether the agent runs on the managed cloud or on your box.

Same task, two approaches: GitHub integration via gh-issues skill vs composio plugin

Same task, both paths. The user prompt is identical:

"Open issue #42 on my repo with a reproduction snippet."

Path A — the gh-issues skill (workflow knowledge). The agent loads gh-issues. It already has the shell tool and an authenticated gh CLI on the box. It executes:

gh issue create \
          --repo acme/widgets \
          --label "bug,area:checkout,severity:s2,needs-triage" \
          --title "Checkout fails when cart total exceeds 999.99" \
          --body "## Summary\nCheckout throws 500 on totals > 999.99 in EUR locale.\n\n## Repro\n1. Add 3 items, total 1000.00 EUR\n2. Click \"Place order\"\n3. Observe 500\n\n## Expected\nOrder placed, charge succeeds.\n\n## Actual\n500 from /api/v2/charge, no charge recorded."
          

Path B — the composio plugin (external connector). The agent loads the composio-github sub-skill that the plugin ships. The plugin's MCP server is already running. The agent calls the GITHUB_CREATE_ISSUE tool exposed by composio, which talks to GitHub's API on the agent's behalf through composio's auth layer:

{
          "tool": "GITHUB_CREATE_ISSUE",
          "args": {
          "owner": "acme", "repo": "widgets",
          "title": "Checkout fails when cart total exceeds 999.99",
          "body": "## Summary\n...\n",
          "labels": ["bug", "area:checkout", "severity:s2", "needs-triage"]
          }
          }
          

The agent is the caller; composio is the connector; GitHub is the destination. Three processes, one logical action.

Side by side, for this single task:

Dimension	gh-issues skill	composio plugin
New install needed	No (drop the folder)	Yes (clawhub install composio)
Where the auth lives	On the agent's box, in gh	In composio's vault
Network hops per call	1 (agent → GitHub)	2 (agent → composio → GitHub)
Team-convention enforcement	Yes, baked into the skill	No, you'd add a sub-skill on top
Works offline (cached creds)	Yes	No
Cross-service in one prompt	No	Yes (one plugin family = many services)
Best fit	Internal repos, strict templates, regulated envs	Mixed SaaS stacks, many services, BYO cloud

Both solve the task. They solve it for different reasons. The skill sells you consistency; the plugin sells you reach.

Decision tree: when to reach for a skill, when for a plugin

Walk down this list, top to bottom. The first match wins.

• Does the task talk to an external service that has an API? If no, it is a skill — a plugin is overkill. (Example: digesting a local CHANGELOG.md is pure-skill.)
• Does the task need the agent to remember a non-obvious workflow? If yes, it is a skill. Skills encode the workflow you would otherwise re-prompt every time — like automating Gmail with OpenClaw, where the labels, reply templates, and threading rules are the actual product.
• Does the auth live somewhere other than this box? If yes, it is a plugin.
• Do you need the same workflow to work from multiple machines? If yes, it is a plugin. The skill would have to be re-installed and re-authenticated on every host; the plugin centralizes the credential.
• Do you need to compose many third-party services in one prompt? If yes, it is a plugin — probably the composio-style aggregator. (Example: "triage the GitHub issue, file the Linear ticket, post to #releases".)
• Do you have hard requirements around offline operation, latency, or audit-trail locality? If yes, prefer a skill. The plugin's extra hop is the wrong trade.
• Are you enforcing strict team conventions on output? Pair the connector (plugin) with a workflow (skill) on top.

Translated into concrete cases:

• "Audit my site for SEO" → skill (seo).
• "Post a hero animation to my site" → skill (gsap, three, tailwind).
• "Triage my GitHub issues" → skill (gh-issues) plus the gh CLI the agent already has.
• "Manage my Trello board from OpenClaw" → plugin for the connector, skill for kanban conventions. See how to automate Trello with OpenClaw.
• "Open an issue, post to Slack, create a Linear ticket, log to HubSpot" → plugin aggregator (composio).
• "Spin up a custom in-house connector" → plugin (your own MCP server) plus a skill that documents how to use it.

Short version: skills for how, plugins for what.

The rule of thumb (and the one exception that breaks it)

The rule:

Reach for a skill by default. Add a plugin when you need a connector you cannot get from the agent's existing tools.

Most of what you want an agent to do — analyze, write, transform, plan, summarize, refactor — does not require a new tool call. It requires the agent to do the right thing with the tools it has. That is what skills are for. Skills are free, local, git-tracked, and the agent only loads the ones it needs.

Add a plugin when one of these is true: the auth must be portable, the service has no local CLI, you need to compose across many services, or you want a clean upgrade path for new endpoints without editing the agent's prompt.

The one exception:

If the workflow is purely about how to call a connector and you have no workflow to teach, the plugin alone is enough. Do not write a skill just to wrap a plugin's tool call. The apollo sales plugin ships with sensible default prompts; you do not need a separate "how to use Apollo" skill unless your team has a non-obvious enrichment pipeline.

Conversely, if you have a rich internal workflow that happens to use GitHub as a backend, write the skill first. Add the plugin only when auth or cross-host deployment forces your hand. The skill is the durable artifact; the plugin is the infrastructure you might swap.

Getting started

1. Audit your last 10 prompts. Mark which needed a new external service and which needed better workflow knowledge. That ratio tells you which extension you actually need.
2. Install one skill locally. Drop a SKILL.md in ~/.openclaw/skills/<name>/ with your conventions encoded as plain English. Restart, run the same prompt, compare.
3. Install one plugin via ClawHub. clawhub install composio (or a single-service plugin like attio) and try the same task. Notice the new tool calls.
4. Combine them. Watch how the agent uses the skill's workflow with the plugin's tools. That is the design working: skill for the how, plugin for the what.
5. Share via git. Skills go in a repo. Plugins go in ClawHub. Don't mix the two.

For the wider platform context, start with GolemWorkers: the AI worker platform explained. For deployment, see how to deploy an AI agent on your own server.

FAQ

What is the difference between a skill and a plugin in OpenClaw?

A skill is a folder of markdown and optional scripts that teaches the agent a workflow. It lives in ~/.openclaw/skills/<name>/ or in ClawHub, and the agent loads it on demand. A plugin is a packaged integration with a plugin.json manifest that exposes MCP servers, app integrations, hooks, and bundled sub-skills. Plugins give the agent new tool calls; skills reshape how it uses the tools it already has.

When should I use a skill vs a plugin?

Use a skill when the value is in the workflow — templates, conventions, decision rules, review routing. Use a plugin when the value is in the connector — talking to GitHub, Salesforce, Notion, Slack, or any other service you cannot reach from the agent's existing tools. If the task is "call this API", plugin. If the task is "do this in a specific, repeatable way", skill.

How do OpenClaw skills work?

A skill is a directory with a SKILL.md containing YAML front matter (name, version, description, triggers, allowed_tools) and a markdown body the agent reads as instructions. When the current task matches a trigger, the agent loads the file and follows the workflow. The skill does not run code of its own; it tells the agent how to use the tools it already has.

What is an MCP server in OpenClaw?

MCP stands for Model Context Protocol — a standard for exposing tools to an LLM agent over a subprocess. In OpenClaw, a plugin declares one or more mcpServers in its plugin.json; the platform spawns each one and the agent can call the tools it exposes. Composio runs a single MCP server that fronts 200+ third-party toolkits behind one install.

Can a skill and a plugin do the same thing?

Often, yes. The difference is how. The skill uses the agent's existing tools (like the gh CLI) with extra workflow context. The plugin gives the agent a brand-new tool call (like GITHUB_CREATE_ISSUE) backed by an external service. They are complementary: the skill tells the agent what to say; the plugin tells it who to say it to.

What is a plugin.json?

plugin.json is the manifest at the root of a plugin folder. It declares the plugin's name and version, its mcpServers, its apps (auth method, OAuth scopes), its lifecycle hooks, any bundled skills, and its interface metadata (icon, category, default prompts). The platform reads it on install and wires the plugin into the agent's tool registry.

Where do OpenClaw skills live?

Skills live in ~/.openclaw/skills/<name>/ for per-user installs, or in ClawHub for shared installs (clawhub install <slug> drops the skill into the local directory). Plugins live in ~/.openclaw/extensions/<name>/. The two directories are independent — a skill folder never becomes a plugin, and a plugin folder is not a skill.

What is composio?

Composio is a third-party integration aggregator and the canonical example of the plugin-aggregator archetype. A single composio plugin exposes 200+ MCP servers (GitHub, Linear, Notion, Salesforce, Slack, HubSpot, and more) behind one install. The agent calls high-level tools like GITHUB_CREATE_ISSUE; composio handles the OAuth, the rate limits, and the API translation.

Can I write a plugin that just bundles several skills?

Yes. The skills field in plugin.json lists skill slugs the plugin ships with. The platform installs them into the agent's skill directory alongside the plugin. This is the right way to ship "connector + workflow" together — the plugin gives the tool, the bundled skill tells the agent how to use it idiomatically.

Do skills need network access?

No. Skills are local markdown and scripts. The agent's tools may need network access (the gh CLI to reach GitHub, web_fetch to read a URL), but the skill itself does not. This is why skills are the right unit for regulated environments and offline operation.

Do plugins replace skills?

No. Plugins add connectors; skills add knowledge. A typical production setup has 10–30 skills and a handful of plugins. Removing all skills in favor of plugins leaves you with a powerful connector set and no consistent workflow. Removing all plugins in favor of skills leaves you with great workflows and no way to reach external services. Keep both.

How do I install a skill vs a plugin?

For a skill: drop a folder in ~/.openclaw/skills/<name>/ with a SKILL.md inside, or run clawhub install <slug>. For a plugin: run the plugin installer (or clawhub install <plugin-slug> for catalog plugins) and complete the OAuth flow declared in the plugin's apps block. Plugins need a restart to pick up new mcpServers; skills are picked up on the next agent start.

What is the gh-issues skill?

gh-issues is a local skill in the OpenClaw examples that codifies a team's GitHub issue workflow — bug-report template, label taxonomy (area:*, severity:*, needs-triage), reviewer routing via CODEOWNERS, and a default gh issue create command shape. It is the canonical example of a skill: pure workflow knowledge, no new connector, no new auth.

What is the difference between an OpenClaw hook and a skill trigger?

A trigger is in the skill's front matter and tells the agent when to read this skill — a pattern in the user's prompt. A hook is in the plugin's plugin.json and tells the platform when to run this script — a lifecycle event like on_agent_start or on_tool_error. Triggers are model-driven; hooks are platform-driven.

Where can I find more examples of OpenClaw skills and plugins?

The ClawHub registry lists both. Search by slug; install with clawhub install <slug>. The plugin catalog includes apollo, attio, airtable, asana, atlassian-rovo, calendly, canva, and the composio aggregator. The skill catalog includes seo, gh-issues, tailwind, three, gsap, healthcheck, and the gog helper.

Common pitfalls

• Skipping the planning phase — Teams that jump straight into prompt engineering usually spend weeks rebuilding once they hit edge cases. Spend 30 minutes mapping the trigger, the action, and the fallback before writing the first instruction.
• Treating the first successful run as done — A 90% pass rate still produces 1 wrong answer in 10. Set an explicit acceptance threshold (typically 99% for production) and instrument the agent to log when it falls short.
• Skipping audit logging — If you can't replay what the agent did three weeks ago, you can't debug it, bill it, or trust it. Persist every tool call with timestamps and inputs from day one.
• Listing features without proof — ‘GolemWorkers supports X’ is a claim. ‘You can run a 6-hour background scan with golemworkers run and get a JSON receipt’ is a fact. Always pair capability with a verifiable command or screenshot.

Related articles

• Deploy an AI Agent on Your Own Server in 2026 (Self-Hoste...
• How to run autonomous coding tasks in OpenClaw with Codex...
• 8 Best AI Agent Builders in 2026 (Honest Comparison & Buy...
• How to automate Slack with OpenClaw
• OpenClaw vs Claude Code: when to use which, and how to us...