OpenClaw Engineering, Chapter 6: Extending Capabilities with SKILL.md

If you finished Chapter 5 with a multi-channel agent running, the next step is expanding what that agent can actually do. Multi-channel delivery gets messages to your users, but you need capabilities to match those messages. That's where skills come in. A skill is fundamentally a directory with a single file: SKILL.md. But that file contains metadata, dependencies, and procedural instructions that teach your agent how to accomplish complex tasks. This chapter covers how to author them, structure them, and think about them as a unit of organization in your system.

What are skills, really

Think of skills as the difference between having hands and knowing how to use them. Tools (the raw functions the agent can call) are the hands. Skills are the textbooks—structured, reusable instruction sets that teach the agent when to use those hands, in what order, and how to handle failures gracefully.

In OpenClaw, a skill is just a directory on disk. Inside it is SKILL.md, a Markdown file with YAML frontmatter at the top. The YAML declares metadata: the skill's name, version, dependencies (environment variables, system binaries, OS requirements). Everything after the frontmatter is plain Markdown—instructions for Claude to follow. Because skills are text files, they're human-readable, version-controllable, and can be easily audited before deployment. You can review a skill before installing it. You can track changes in Git. You can deprecate old versions without breaking existing deployments.

The power emerges from composability. When your agent runs, the OpenClaw gateway loads dozens or hundreds of available skills into context—not the full text, just metadata summaries. When Claude encounters a complex task, it understands which skills are available and chains them together. The skill for reading spreadsheets, combined with the skill for drafting emails, combined with the skill for sending emails, lets the agent handle a multi-step business process that no single skill could do alone.

The YAML frontmatter: declaring what you need

Every SKILL.md starts with YAML frontmatter enclosed in triple dashes. Here's a minimal example:

---
name: email-composer
description: Draft, review, and send professional emails
version: 1.2.3
metadata:
  openclaw:
    requires:
      env:
        - SMTP_HOST
        - SENDER_EMAIL
      bins:
        - openssl
      os:
        - linux
        - darwin
---

The name is the skill's unique identifier. The description is a one-liner for listings and help text. The version follows semantic versioning (major.minor.patch). Under requires, you declare dependencies: environment variables that must be set, system binaries that must exist in PATH, and operating systems the skill supports. If any dependency is missing at Gateway boot, the skill is silently disabled. This prevents runtime errors mid-task; instead, the agent simply knows it can't use that skill.

The requires.env block lists configuration variables. The requires.bins block lists CLI tools (like openssl, ffmpeg, git). The requires.os block restricts to specific systems—useful for platform-specific skills. There's also primaryEnv, which hints which environment variable is essential for the skill's core purpose. The gateway uses this hint when displaying skill info or constructing audit logs.

The Markdown section: writing instructions for Claude

After the closing ---, everything is Markdown. This is where you instruct Claude how to use the skill. Unlike a typical README, this isn't documentation for humans reading the code—it's instructions for Claude to follow. Be explicit, procedural, and crystal clear.

A well-structured skill follows a pattern: an overview section, a ## Steps or ## Procedure section that walks through the task sequentially, and a ## Safety Checks section that outlines guards against common mistakes. For the email example:

# Email Composer Skill
Use this skill to draft professional emails with multiple review stages.
## Steps
1. Draft the email with proper salutation and structure
2. Review for tone, accuracy, and sensitive information
3. Request user approval before sending
4. Send via SMTP or log error if delivery fails
## Safety Checks
Before sending, always check: no API keys, no passwords, no SSNs, no credit card numbers.

The key is explicitness. Don't assume Claude will infer proper error handling. State it clearly: 'If an error occurs during the query, always roll back the transaction. Never leave partial updates.' These details seem obvious to engineers but are crucial for agent reasoning.

Include exit criteria—a summary of what was accomplished. 'Email successfully sent to alice@example.com at 2026-02-28 14:35:22 UTC. Recipients: 5 total (3 To, 2 Cc). Subject: Quarterly Review.' This summary gives users confidence the task completed as expected.

Managing skill versions and deprecation

As a skill evolves, version carefully. The version number in YAML is the single source of truth. If you make breaking changes (changing input format, removing features), bump the major version. Add a 'Version History' section documenting breaking changes: 'v2.0.0 changes output format from CSV to JSON. If you depend on CSV, stay on v1.x. v1.5.5 is the last v1 release.'

When a skill becomes obsolete, mark it as deprecated. Add to the YAML: deprecated: { since_version: "3.0.0", reason: "The Acme API has shut down. Use acme-v2-connector instead.", removal_date: "2027-01-01" }. The gateway won't prevent using it (it might still work), but will warn. The removal date gives users time to migrate.

For widely-shared skills, include a 'Testing' section: 'To test this skill, ensure DATABASE_URL is set to a test database. Run the skill with input { query: "SELECT 1" }. Expected output: { result: [1], duration_ms: 50 }.' This guidance helps operators validate proper configuration before production use.

Workspace skills and overrides

OpenClaw ships with bundled skills—basic file operations, shell commands, HTTP requests. You can also create workspace skills in your local environment, typically in ~/clawd/skills/my-skill-name/. These are version-controlled, tailored to your needs, and follow the exact same SKILL.md format.

The critical design pattern is overrides. If a workspace skill has the same name as a bundled skill, the workspace skill wins. Suppose the bundled execute-sql skill works with PostgreSQL, but you use Oracle. Create a workspace skill called execute-sql that handles Oracle syntax. When the agent runs, it uses your version. You can customize foundational behaviors without forking the entire OpenClaw codebase. When bundled skills update upstream, you choose to adopt, stay customized, or migrate gradually—critical flexibility in large organizations with different tooling.

What's next

With individual skills working, the next question becomes: how do you organize, discover, and share them at scale? That's where ClawHub enters the picture. Chapter 7 covers the skill ecosystem—bundled vs workspace skills, skill discovery and context, publishing to ClawHub, and how 13,000+ community skills can work together without collision or duplication.