MCP Skills: How Agent Skills Extend the Model Context Protocol in OpenClaw

At least six major AI coding tools now implement the SKILL.md standard published at agentskills.io, including Claude Code, Codex CLI, Gemini CLI, GitHub Copilot, and Cursor (Agent Skills Specification). OpenClaw takes this further with a six-source skill loading hierarchy and ClawHub, a community registry of thousands of shared skills. Cross-vendor adoption moved fast because the industry hit the same problem: MCP servers expose tools, but agents don't arrive with knowledge of when to call each tool, what parameters work best for specific scenarios, or how to chain operations into workflows. MCP skills fill that gap.

Most content about MCP conflates three distinct concepts. Here is the difference:

MCP Server

A backend process that exposes tools, resources, and prompts over the Model Context Protocol. Built in Python, TypeScript, Go, or Rust. Examples: a Stripe MCP server, a GitHub MCP server, a local filesystem server.

MCP Tool

A single callable function on an MCP server, defined with typed parameters and a description. Examples: create_issue, search_files, send_message. The tool defines what an agent can do.

MCP Skill

A SKILL.md instruction file that teaches the agent how and when to use specific tools. Written in Markdown with YAML frontmatter. The skill defines what the agent knows how to do well.

An MCP server hosts tools. A tool defines a capability. A skill teaches the agent how to use that capability in context. Without skills, an agent facing a server with 20 tools has to cycle through parameters by trial and error until something works. With a well-written skill, the agent knows the workflow before writing a single tool call.

The hybrid approach is where production teams are landing. MCP gives the agent a standardized protocol to reach external systems. Skills give the agent the procedural knowledge to use those systems correctly on the first try. As one comparison put it: "MCP scales your systems. Agent Skills scale your agent's behavior." You need both halves to build an agent that performs reliably.

The Agent Skills specification defines a deliberately minimal format. A skill is a directory with a SKILL.md file at its root:

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

The SKILL.md file has two parts: YAML frontmatter and a Markdown body. Only two frontmatter fields are required.

---
name: mcp-server-setup
description: Configure and deploy MCP servers for production use. Activate when setting up server instances or troubleshooting connection issues.
---

The name field follows strict rules: lowercase letters, numbers, and hyphens only, 64 characters max, no consecutive hyphens, and it must match the parent directory name. The description field is what the agent reads to decide if this skill applies to the current task, so specificity matters. "Helps with MCP" is too vague to trigger activation. "Configure and deploy MCP servers for production use" gives the agent a clear signal.

Optional frontmatter fields refine behavior:

• license: Distribution terms or a pointer to a license file
• compatibility: Environment requirements ("Requires Python 3.14+ and uv")
• metadata: Arbitrary key-value pairs for version, author, or agent-specific configuration
• allowed-tools: Pre-approved tools the skill can invoke (experimental)

The Markdown body after the frontmatter contains the actual instructions. There are no format restrictions on the body. Step-by-step procedures, input/output examples, edge case notes: whatever helps the agent execute the task. The specification recommends keeping the body under 5,000 tokens and moving detailed reference material to separate files in references/ or assets/.

Skills use progressive disclosure to stay lightweight. At session start, only the short metadata (name and description) loads for each installed skill. When the agent decides a skill is relevant, the full instruction body loads. Supporting files in references/ or assets/ load only when the instructions reference them. This staged approach keeps context budgets tight, since most sessions only activate one or two skills out of dozens installed.

OpenClaw resolves skills from six sources, checked in a strict priority order (OpenClaw Skills Documentation). The hierarchy moves from most specific to most general: workspace-level skills take highest priority, followed by project and personal agent directories, then managed and bundled skills, and finally any extra directories you configure. When the same skill name appears in multiple locations, the highest-priority source wins. A team can override a global skill at the workspace level without touching shared configuration.

OpenClaw snapshots eligible skills when a session starts and reuses that list for the session's lifetime. Install a skill, start a new session, and it's available.

Gating and dependencies

Skills can declare environment requirements in their frontmatter: required binaries, environment variables, or configuration flags. If a dependency is missing, OpenClaw silently skips the skill rather than throwing an error. You can also gate skills by operating system or force inclusion regardless of environment. This means a macOS-only skill won't clutter up a Linux agent's context, and a skill that requires a specific API key stays hidden until that key is set.

Token overhead

Each installed skill adds only its metadata (name, description, file path) to the session context at startup. OpenClaw's documentation estimates roughly 24 tokens per skill before any instruction body loads. A workspace with 50 installed skills costs around 1,200 tokens at startup, well within budget for any modern model.

ClawHub: the public skill registry

ClawHub is OpenClaw's community marketplace for sharing skills. You can install skills from ClawHub or directly from Git repositories. ClawHub includes a verification system that validates the trust envelope before you enable a third-party skill.

Since skills are functionally untrusted code, the OpenClaw documentation recommends reviewing them before installation, especially those requesting broad tool permissions. A Skill Workshop feature lets agents draft skill proposals that you review and apply manually, rather than allowing direct writes to your skill directories.

mcporter is a CLI tool that discovers, installs, and configures MCP servers across multiple AI hosts (mcporter guide). Instead of manually editing JSON configuration files or searching GitHub for server repositories, you search and install through a single interface.

Install mcporter globally:

npm install -g mcporter

Or run without installation:

npx mcporter search web-search

Search and install servers:

mcporter search browser automation
mcporter install @anthropic/tavily-search --target openclaw

The --target openclaw flag writes the server configuration directly into your openclaw.json file. mcporter also supports Claude Desktop and Cursor as targets, making it useful even outside the OpenClaw ecosystem.

Manage your installed servers:

mcporter list --installed
mcporter update --all
mcporter remove playwright-mcp --target openclaw

The MCP server ecosystem has grown rapidly since Anthropic released the protocol specification in late 2024. Companies like Stripe, Notion, Linear, Figma, and Supabase all publish their own MCP servers. Individual developers and startups contribute hundreds more. mcporter aggregates across multiple registries rather than pulling from a single source, so a search covers the full range of available servers.

mcporter treats ClawHub skills and standalone MCP servers interchangeably. Since many ClawHub skills are MCP servers under the hood, mcporter manages both from the same interface. It handles version updates and dependency resolution across your entire server fleet, so you don't have to track which versions are installed where. The onboarding friction for adding a new MCP capability to your agent drops from "find the package, read its docs, edit JSON config" to a single install command.

Store and share your agent's MCP output in one workspace

Shared storage with MCP-native access at /mcp. Connect your OpenClaw agent to Fast.io in minutes. Starts with a 14-day free trial.

Start 14-Day Trial

Creating your own MCP skill takes minutes. Start by creating a directory with a SKILL.md file:

my-api-skill/
├── SKILL.md
└── references/
    └── api-patterns.md

Write the SKILL.md with clear, actionable instructions:

---
name: my-api-skill
description: Guide the agent through querying and writing to the
  Acme API via its MCP server. Activate when the user mentions
  Acme data, Acme integration, or Acme configuration.
---

### When to Activate

Use this skill when the user wants to:
- Query Acme datasets through the MCP server
- Configure authentication for Acme endpoints
- Write records back to Acme

### Setup Checklist

1. Verify the Acme MCP server is installed
2. Check that ACME_API_KEY exists in the environment
3. Test with a read operation before attempting writes

### Operation Order

Always read before writing. Always confirm destructive operations
with the user. Batch reads when querying multiple records.

Three patterns separate effective skills from ones that never activate:

Specific triggers. The description field determines whether the agent loads the skill. "Helps with APIs" matches nothing useful. "Query and write to the Acme API via MCP server" activates when someone mentions Acme, because the agent can match the description to the task.

Workflow knowledge, not tool documentation. An agent with access to 15 Acme tools still needs to know the order of operations: authenticate first, read before writing, confirm destructive actions. That procedural knowledge is what separates a skill from a tool description string. The MCP development skills published by the Model Context Protocol team demonstrate this pattern: the entry skill runs a discovery phase (asking about deployment model, auth needs, API surface size) before recommending a scaffold.

Right-sized instructions. Keep the main SKILL.md body under 5,000 tokens. Move detailed API reference material, code templates, and schema definitions to the references/ directory so the agent loads them on demand rather than carrying them in context from the start.

To install your skill in OpenClaw, place the directory in any of the six recognized locations. For personal use, ~/.openclaw/skills/my-api-skill/ works. For team projects, commit it to <workspace>/skills/. OpenClaw discovers the SKILL.md file automatically at the next session start. If you want to share your skill with the community, publish it to ClawHub.

MCP skills teach agents how to interact with external systems. The output those skills produce needs somewhere persistent and shareable.

Common storage approaches:

Local filesystem storage works for solo development but falls apart when agents run remotely or when teammates need access. S3 and similar object stores handle persistence but lack search, permissions, and handoff workflows. Google Drive and Dropbox offer sharing, but they were designed for humans clicking through a UI, not agents writing files programmatically.

Fast.io offers shared workspaces where agents and humans operate side by side. An agent running MCP skills in OpenClaw can write output to a Fast.io workspace through the Fast.io MCP server, and a human teammate can review or share that output from the same workspace without any file exchange.

In practice, the workflow looks like this: your OpenClaw agent runs an MCP skill that queries an external service, processes the results, and writes output files to a Fast.io workspace. A project manager opens the same workspace in a browser, reviews the deliverables, and shares a branded link with a client. The agent and the human never coordinate on storage paths or transfer files manually.

Fast.io exposes Streamable HTTP at /mcp and legacy SSE at /sse, so OpenClaw connects using the same protocol it uses for any other MCP server. Intelligence Mode auto-indexes uploaded files for semantic search. You can ask questions about your documents and get cited answers without setting up a separate vector database. Ownership transfer lets an agent create workspaces and branded shares, then hand ownership to a human while keeping admin access for ongoing maintenance. File locks prevent conflicts when multiple agents access the same workspace concurrently.

Plans bundle storage, monthly credits, and workspaces scaled to each tier, and every org starts with a 14-day free trial. For developers experimenting with MCP skills in OpenClaw, the trial is enough to run real workflows. The Fast.io MCP skill has setup details, and /storage-for-openclaw/ covers OpenClaw-specific configuration.