OpenClaw skill.md Format: The File Structure Builders Must Know

I've reviewed hundreds of community skills on ClaWHub. The difference between a skill that works reliably and one that behaves unpredictably almost always comes down to the manifest. Vague tool descriptions, missing parameter schemas, incorrectly formatted hook entries — these don't throw errors. They just make the skill unreliable. Here's the format, field by field, with examples that actually work.

File Structure Overview

SKILL.md combines two formats in one file: YAML frontmatter between --- delimiters, followed by a Markdown body. The frontmatter is parsed by the OpenClaw runtime. The Markdown body is for human readers — it doesn't affect behavior, but ClaWHub displays it as the skill's documentation page.

---
name: my-skill
version: 1.0.0
description: "What this skill does in one sentence"
author: "Your Name"
tools:
  - name: do_something
    description: "When to call this tool and what it returns"
    handler: ./handler.sh
    parameters:
      query:
        type: string
        description: "The input to process"
        required: true
---

# My Skill

This is the human-readable documentation for my skill.

Frontmatter Fields

Required Fields

• name — the skill's identifier. Lowercase, hyphens only. Must be unique in your skills directory. This is what you use in openclaw skills remove [name].
• version — semantic version string (e.g. 1.0.0). Used for update detection when the skill is in ClaWHub.

Optional Fields

• description — one sentence. Shown in openclaw skills list and in ClaWHub search results.
• author — your name or organization. Required for ClaWHub publishing.
• requires_provider_features — list of provider capabilities this skill needs (e.g. [tool_calling, vision]). OpenClaw warns at load time if the current provider doesn't support listed features.
• min_openclaw_version — minimum OpenClaw version required. If the user's version is older, the skill fails gracefully with a clear message instead of a cryptic error.
• env_required — list of environment variables the skill needs. OpenClaw checks these exist before loading and warns if they're missing.

Defining Tools

Each entry in the tools array becomes a callable function the model can invoke. This is the most important part of your manifest — get this right and the skill works reliably.

tools:
  - name: search_web
    description: >
      Search the web for current information. Use when the user asks
      about recent events, current prices, or anything that requires
      live data not in training. Returns top 5 results with titles and URLs.
    handler: ./search.sh
    parameters:
      query:
        type: string
        description: "The search query to send"
        required: true
      num_results:
        type: integer
        description: "Number of results to return (1-10)"
        required: false
        default: 5
    timeout: 30

The handler field points to the executable that runs when the tool is called. It can be a shell script, Python file, compiled binary, or any executable on your system. OpenClaw calls it with tool parameters as JSON on stdin.

Prompt Injection

The prompt_injection block lets your skill add text to the agent's system prompt every time it loads. Use this to give the agent context about your skill's tools, set behavioral expectations, or establish persona elements.

prompt_injection:
  position: prepend  # prepend | append | replace
  text: |
    You have access to real-time web search. When a user asks about
    current events, prices, or recent news, use the search_web tool
    to get accurate information before answering. Never make up
    current information.

Hooks

Hooks let a skill execute code at lifecycle events without the user saying anything. This is how monitoring and automation skills work.

hooks:
  on_session_start:
    handler: ./on-start.sh
    description: "Check for unread alerts when session begins"

  on_cron:
    schedule: "*/15 * * * *"   # every 15 minutes
    handler: ./check-inbox.sh
    description: "Poll for new emails every 15 minutes"

Available hooks as of early 2025: on_session_start, on_message_received, on_tool_result, on_session_end, and on_cron. The on_cron hook requires a valid cron expression in the schedule field.

Complete Working Example

---
name: weather-check
version: 1.2.0
description: "Get current weather and forecasts for any location"
author: "S. Rivera"
min_openclaw_version: "1.4.0"
env_required:
  - OPENWEATHER_API_KEY
requires_provider_features:
  - tool_calling

tools:
  - name: get_weather
    description: >
      Get current weather conditions for a city or coordinates.
      Use when the user asks about weather, temperature, rain, or
      forecast. Returns temperature, conditions, and 3-day outlook.
    handler: ./weather.sh
    parameters:
      location:
        type: string
        description: "City name or lat,lon coordinates"
        required: true
      units:
        type: string
        description: "Temperature units: celsius or fahrenheit"
        required: false
        default: celsius
    timeout: 15

prompt_injection:
  position: append
  text: |
    You can check real-time weather with the get_weather tool.
    Always use it when location-specific weather is asked about.
---

# Weather Check Skill

Provides real-time weather data via the OpenWeather API.

Common Mistakes

1. YAML syntax errors — use a YAML linter before running. Indentation mistakes silently invalidate the whole manifest.
2. Handler path not executable — chmod +x handler.sh. OpenClaw can't execute a file that's not marked executable.
3. Tool name with spaces or capitals — tool names must be lowercase with underscores. search_web is valid; Search Web is not.
4. Missing required parameter in call — if you mark a parameter required: true, the model will try to always provide it. If the user's question doesn't supply the info, the model will ask. This is expected behavior, not a bug.

Frequently Asked Questions

What is SKILL.md in OpenClaw?

SKILL.md is the manifest file that every OpenClaw skill must contain. It defines the skill's metadata, tools, system prompt injections, hooks, and dependencies in a structured YAML frontmatter + Markdown body format.

Is SKILL.md format the same as CLAUDE.md?

They share a similar philosophy but serve different purposes. CLAUDE.md provides project-level instructions to the agent. SKILL.md defines a reusable, installable skill module with formal tool schemas that the runtime can load dynamically.

What fields are required in SKILL.md?

Only name and version are strictly required. All other fields are optional, though a skill without at least one tool, command, or prompt injection has no effect on the agent.

How do I define a tool parameter in SKILL.md?

Under each tool entry, add a parameters block with JSON Schema-compatible definitions. Each parameter needs a type and description. Mark required parameters in a required array. OpenClaw validates all calls against this schema before executing the tool.

Can I inject text into the system prompt from a skill?

Yes. Add a prompt_injection block to your SKILL.md with a text field. This text is prepended to the system prompt every time an agent loads the skill, letting you shape the agent's behavior and persona.

What are skill hooks?

Hooks let a skill run code at specific lifecycle events: on_session_start, on_message_received, on_tool_result, and on_cron. They're how skills like BlogWatcher and Gmail monitoring work without user prompting.

How do I validate my SKILL.md before publishing?

Run openclaw skills validate /path/to/skill-dir to lint the manifest against the current schema. It reports missing required fields, type mismatches, and tool schema errors before you publish to ClaWHub.