SKILL.md Agent Skills Format: The Complete Guide for OpenClaw Developers

Forty-one agent platforms now load the same SKILL.md file format, eight months after Anthropic published it as an open standard in December 2025 (Agent Skills Specification). The list includes Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, JetBrains Junie, Snowflake Cortex Code, and Databricks Genie Code, among others. That adoption curve happened because every agent team hit the same problem independently: agents had access to tools but lacked procedural knowledge about when and how to use them well.

SKILL.md is a lightweight, open format for packaging domain knowledge and workflows into portable instruction sets that AI coding agents load on demand. A skill is a folder containing a SKILL.md file with YAML frontmatter (name, description) and Markdown instructions.

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

The frontmatter gives agents a quick summary of what the skill does. The Markdown body provides the detailed instructions. Optional subdirectories can hold scripts, reference docs, and templates that the agent pulls in only when needed.

What makes this more than a regular markdown file is progressive disclosure. Agents scan only names and descriptions at startup, roughly 100 tokens per skill according to the specification. Full instructions load only when a task matches a skill's description, and bundled files load only when those instructions reference them. This staged approach lets an agent carry dozens of skills without exhausting its context window.

Anthropic created the format for Claude Code and published it as an open standard in December 2025, hosted at agentskills.io. Adoption followed quickly: OpenAI added support in Codex CLI, JetBrains in Junie, and enterprise platforms like Snowflake and Databricks followed.

How do skills relate to MCP tools? MCP tools expose callable functions with typed parameters. Skills sit above tools, encoding the judgment layer: when to call which tool, in what order, and how to interpret the result. Tools are verbs; skills are playbooks.

For OpenClaw developers, skills are the primary way to extend agent behavior. OpenClaw loads skills from multiple locations, including workspace, user, managed, and bundled directories, with workspace-level overrides taking highest precedence (OpenClaw Skills Documentation). ClawHub hosts a community registry where developers share and install skills across teams.

The frontmatter block at the top of every SKILL.md file is what agents read first and what registries like ClawHub index. Two fields are required; four more are optional. Understanding what each field does and how agents interpret it will save you debugging time later.

name (required)

The skill's identity. Must be 1 to 64 characters, lowercase alphanumeric plus hyphens only. No uppercase, no underscores, no consecutive hyphens. Cannot start or end with a hyphen. The name must match the parent directory name.

Valid: pdf-processing, data-analysis, code-review

Invalid: PDF-Processing (uppercase), -pdf (leading hyphen), pdf--processing (consecutive hyphens)

description (required)

What the skill does and when to use it, up to 1,024 characters. This field serves double duty: agents read it at startup to decide whether the skill matches the current task, and humans read it when browsing registries like ClawHub. Include specific keywords that help agents identify relevant tasks.

Good: "Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions forms or document extraction."

Weak: "Helps with PDFs."

The difference matters. Agents make activation decisions based on semantic similarity between the task and the description. Vague descriptions lead to unreliable activation.

license (optional)

A short string naming the license or pointing to a bundled file. Keep it brief: Apache-2.0 or Proprietary. LICENSE.txt has complete terms.

compatibility (optional)

Environment requirements, up to 500 characters. Use this when your skill needs specific software, a particular agent product, or network access. Examples: Requires Python 3.14+ and uv or Designed for Claude Code (or similar products). Most skills don't need this field.

metadata (optional)

Arbitrary key-value pairs for properties not covered by the spec. Registry tools use these for filtering and author attribution.

metadata:
  author: example-org
  version: "1.0"

OpenClaw extends this field with a structured openclaw key for dependency gating:

metadata:
  openclaw:
    requires:
      bins: ["docker"]
      env: ["API_KEY"]
    primaryEnv: "API_KEY"

When OpenClaw encounters these requirements, it checks for the listed binaries and environment variables before making the skill available. If the requirements aren't met, the skill stays hidden from the agent entirely.

allowed-tools (optional, experimental)

A space-separated string of pre-approved tools. Support varies between agents, so don't rely on this for critical behavior.

Here is a complete frontmatter example combining required and optional fields:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
compatibility: Requires Python 3.10+ and poppler-utils
metadata:
  author: example-org
  version: "1.0"
---

The body content after the frontmatter has no structural requirements from the specification. Write whatever helps agents perform the task. The specification recommends including step-by-step instructions, input/output examples, and common edge cases. Standard Markdown formatting works as expected: headers, lists, code blocks, and links to bundled files.

Progressive disclosure is the design principle that makes skills scalable. Without it, every skill would consume context at startup, and agents would hit token limits before doing any useful work.

The three stages work like a well-organized manual: table of contents first, then the relevant chapter, then the appendix only if needed.

Stage 1: Discovery

At startup, agents load only the name and description of each available skill. This costs roughly 100 tokens per skill (specification). An agent with 50 skills installed spends about 5,000 tokens on discovery, a fraction of most models' context windows. OpenClaw's overhead is even more predictable: roughly 24 tokens per skill for the base metadata plus field lengths.

Stage 2: Activation

When the agent identifies a task that matches a skill's description, it reads the full SKILL.md body into context. The specification recommends keeping this under 5,000 tokens and fewer than 500 lines. This is where step-by-step instructions, examples, and edge case handling belong.

Stage 3: Resource Loading

If the activated skill references scripts, templates, or documentation in subdirectories, the agent loads those files only when the instructions call for them. A skill that bundles a scripts/extract.py file costs zero tokens until the agent actually needs to run the extraction.

This staging shapes how you structure skills. Put the critical information, the steps the agent always needs, in the SKILL.md body. Move reference tables, API schemas, and detailed examples into references/ or assets/ directories.

Consider a deployment automation skill. The SKILL.md body contains core deploy steps and common configuration patterns. A references/cloud-providers.md file lists provider-specific settings for AWS, GCP, and Azure. A scripts/health-check.sh runs post-deploy validation. During a typical deploy task, the agent loads the core instructions immediately but only reads the provider reference when the user specifies a particular cloud provider. The health check script loads only during the verification step.

Another way to think about this is in terms of token budgets. If you're building a skill library for a team, you can estimate the total discovery cost: 50 skills at roughly 100 tokens each equals about 5,000 tokens, around 1.5% of a 128K context window. Even 200 skills would use only 6% at the discovery stage. The real context investment happens only when skills activate, and typically only one or two skills activate per task.

A skill that teaches an agent to use the Fast.io MCP server could keep its main instructions under 200 lines and reference the full MCP tool documentation as a separate file. The agent reads the overview at activation and loads the detailed parameter reference only when it encounters an unfamiliar tool call.

One common mistake is cramming everything into the SKILL.md body. If your instructions exceed 500 lines, split them. The agent will still find and load the referenced files when needed, and your skill will activate faster because less context loads upfront.

Give Your Agent Skills a Persistent Workspace

A shared workspace with a Streamable HTTP endpoint at /mcp for agents to read, write, and share files across sessions. Starts with a 14-day free trial.

Start 14-Day Trial

Start with evaluation. Before writing a skill, run your agent on representative tasks and observe where it struggles or asks for help repeatedly. Skills work best when they address specific, repeated capability gaps rather than broad domains.

Here is a minimal skill that teaches an agent to format commit messages:

commit-format/
├── SKILL.md
└── references/
    └── examples.md

The SKILL.md file:

---
name: commit-format
description: Format git commit messages using conventional commits with scope. Use when committing code or writing commit messages.
---

Format all commit messages as:

<type>(<scope>): <subject>

Types: feat, fix, docs, style, refactor, test, chore
Scope: the module or component affected
Subject: imperative mood, lowercase, no period

See [examples](references/examples.md) for real-world samples.

The references/examples.md file contains concrete examples the agent reads only when it needs clarification on the format.

Here is a more complete example, a skill for managing database migrations:

---
name: db-migrate
description: Run and manage database migrations with alembic. Use when the user mentions migrations, schema changes, or database updates.
compatibility: Requires Python 3.10+ and alembic
---

### Creating a Migration 1.

Check current state with `alembic current`
2. Generate a migration: `alembic revision --autogenerate -m "<description>"`
3. Review the generated file in `alembic/versions/`
4. Verify both upgrade() and downgrade() functions

### Running Migrations

- Upgrade to latest: `alembic upgrade head`
- Upgrade one step: `alembic upgrade +1`
- Downgrade one step: `alembic downgrade -1`

### Edge Cases

- If autogenerate misses a change, write the migration manually
- For data migrations, create a separate file and mark it - Never modify a migration that has been applied to production

See [schema conventions](references/conventions.md) for naming rules.

This skill demonstrates several good patterns: clear step-by-step procedures, explicit tool commands, edge case handling, and a reference file link for details that aren't needed on every activation.

Where OpenClaw Loads Skills

OpenClaw discovers skills from six locations, checked in this order:

1. Workspace skills at <workspace>/skills
2. Project agent skills at <workspace>/.agents/skills
3. Personal agent skills at ~/.agents/skills
4. Managed skills at ~/.openclaw/skills
5. Bundled skills shipped with OpenClaw
6. Extra directories configured via skills.load.extraDirs

When the same skill name appears in multiple locations, the highest source wins. A workspace-level skill overrides a bundled skill with the same name. This lets you customize default behavior for specific projects without changing your global configuration.

For development, put your skill in <workspace>/skills/ for the fast feedback loop. Edit the SKILL.md, start a new agent session, and test.

Writing Effective Instructions

The Markdown body is where most developers underinvest. Vague instructions like "help the user with Git" produce inconsistent results. Good instructions include:

• Step-by-step procedures for the primary workflow
• Input/output examples so the agent knows what success looks like
• Edge cases and error handling for common failure modes
• Clear boundaries stating what the skill does NOT cover

Structure instructions as conditional rules where possible: "If the user asks for X, do Y. If the file contains Z, handle it by doing W." This gives agents clear decision points rather than open-ended guidance.

Configuration and Gating

Individual skills can be enabled or disabled through OpenClaw's configuration at ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "my-skill": {
        "enabled": true
      }
    }
  }
}

Agent allowlists further control skill visibility. The agents.defaults.skills configuration sets baseline access, while per-agent skills arrays can override the defaults entirely.

Validating Before Publishing

The agentskills.io project provides a reference validation tool:

skills-ref validate ./my-skill

This catches naming violations, missing required fields, and frontmatter formatting issues before you share your skill with anyone else.

ClawHub is the primary registry for sharing OpenClaw skills. The community has published thousands of skills spanning development workflows, browser automation, data analysis, and CI/CD pipelines. A curated catalog of over 5,400 skills is maintained at the awesome-openclaw-skills repository, filtered and categorized from the broader registry.

Publishing Your Skill

After local testing and validation, publish to ClawHub through the CLI:

clawhub sync --all

This pushes your skill directory to the registry, where other developers can install it:

openclaw skills install @your-username/skill-name

Add --global to install for all agent sessions rather than just the current workspace.

Security Scanning

ClawHub learned hard lessons about supply-chain security. In February 2026, security researchers discovered hundreds of malicious skills using typosquatted names to distribute malware across the registry. OpenClaw responded by partnering with VirusTotal to scan every published skill, removing confirmed threats and introducing daily re-scanning.

Before installing community skills, verify them:

openclaw skills verify @owner/skill-name

For any skill that runs shell commands or accesses the network, read the SKILL.md and bundled scripts before installing. Skills run with the same permissions as your agent. A compromised skill can read environment variables, execute arbitrary commands, and access files.

Skill Workshop

OpenClaw's Skill Workshop feature lets agents propose new skills during a session. When an agent spots a repeated workflow pattern, it can draft a skill proposal for human review:

openclaw skills workshop list

This keeps skill creation under human oversight while letting the agent surface automation candidates it notices during regular work.

Cross-Platform Portability

The same SKILL.md file works across all platforms that support the format, but behavior varies in two areas. The allowed-tools field is experimental, and different agents interpret it differently or ignore it. How agents resolve file references in scripts/ and references/ also depends on the agent's file access model: some agents execute Python scripts directly, while others can only read them and suggest shell commands.

Test your skill on at least two platforms before publishing. The core behavior (loading frontmatter, activating on matching tasks, following Markdown instructions) is consistent across agents. The edges around tool permissions and script execution vary enough to warrant verification.

Connecting Skills to Persistent Storage

Skills that produce files need somewhere to put the output. Local storage works during development, but production agent workflows often need persistent, shareable storage across sessions. Fast.io workspaces fill that role: agents write files through the MCP server, and team members access the same workspace through the web UI. Intelligence Mode auto-indexes uploaded files for search and RAG without extra configuration. Every org starts with a 14-day free trial, and paid plans scale storage and monthly credits to each tier.