How to Build Your First OpenClaw Skill: From SKILL.md to ClawHub (2026) | OpenClaw DC

What is an OpenClaw skill?

An OpenClaw skill is a Markdown file (SKILL.md) with YAML frontmatter that teaches your agent how to do a specific task. You can build one in 10 minutes and publish it to ClawHub for others to install. Skills are the primary extension mechanism for OpenClaw. Instead of writing code plugins or editing agent internals, you write structured natural language instructions that the agent follows. Each skill lives in its own folder, and the heart of that folder is always a file called SKILL.md.

If you are new to OpenClaw, start with our guide to what OpenClaw is and how to use it before building your first skill.

What a skill file looks like

A skill is a directory containing one required file (SKILL.md) and optional supporting files like scripts, templates, or config. Here is a complete example of a working SKILL.md:

---
name: daily-standup-summary
description: Summarizes yesterday's git commits into a daily standup update
version: 1.0.0
tags: [productivity, git, standup]
author: your-github-username
requirements:
  tools: [bash, git]
---

## Instructions

When the user asks for a standup summary or standup update, do the following:

1. Run `git log --since="yesterday" --oneline --all` in the current repository.
2. Group the commits by author.
3. For each author, write a two-sentence summary of what they worked on.
4. Format the output as a bulleted list under the heading "Standup Summary".
5. If there are no commits since yesterday, tell the user there is nothing to report.

## Rules

- Never fabricate commits. Only summarize what appears in the git log output.
- If the user specifies a date range, use that range instead of "yesterday".
- Always confirm the repository path with the user before running git commands.

## Examples

User: "Give me a standup summary"
Agent: Runs git log, groups commits, returns formatted summary.

User: "Standup for the last 3 days"
Agent: Adjusts the --since flag to "3 days ago" and follows the same steps.

The YAML frontmatter tells OpenClaw and ClawHub what the skill is called, what it does, and what tools it needs. The Markdown body contains the actual instructions the agent will follow.

Anatomy of a skill

Every SKILL.md has five key parts. Understanding each one will help you write skills that behave predictably.

Name. A unique, lowercase, hyphenated identifier. This is how users find and install your skill on ClawHub. Keep it descriptive: csv-to-json-converter is better than my-tool.

Description. A single sentence explaining what the skill does. This appears in ClawHub search results, so make it clear and specific.

Tools. The requirements.tools field lists what the agent needs access to. Common values include bash, git, python, node, and browser. If your skill requires a tool the user has not enabled, OpenClaw will warn them at install time.

Instructions. The core of the skill. Write step-by-step directions in plain language. The agent treats these as guidance and will fill gaps with its own judgment, so if a behavior matters to you, spell it out explicitly. Include what to do when things go wrong, not just the happy path.

Examples. Optional but highly recommended. Concrete input/output pairs help the agent understand your intent and reduce misinterpretation. Two or three examples usually suffice.

You can also add a Rules section for hard constraints the agent must never violate. This is where you put guardrails like “never delete files without confirmation” or “always use the staging API endpoint, never production.”

Step by step: create, test, iterate, publish

Step 1: Create the skill folder

mkdir -p ~/.openclaw/skills/my-new-skill
touch ~/.openclaw/skills/my-new-skill/SKILL.md

Open SKILL.md in your editor and add the YAML frontmatter and instructions following the structure shown above.

Step 2: Validate the format

openclaw skills test my-new-skill

This checks your SKILL.md for valid YAML frontmatter, required fields, and basic formatting issues. Fix any errors before moving forward.

Step 3: Test in conversation

Start a new OpenClaw session and trigger your skill by asking the agent to perform the task you described. Watch the output carefully. Does the agent follow your instructions in order? Does it handle edge cases the way you expect? If not, revise the instructions and test again.

Step 4: Iterate on the instructions

This is where most of the work happens. Common adjustments include adding more specific rules, expanding the examples section, and clarifying ambiguous phrasing. The agent interprets your instructions literally in some places and loosely in others, so testing is the only way to know where to tighten the language.

Step 5: Publish to ClawHub

Once you are satisfied with the skill’s behavior:

cd ~/.openclaw/skills/my-new-skill
clawhub publish .

You need a GitHub account that is at least one week old. Each publish creates a new version, and ClawHub keeps a full version history so users can audit changes before installing. After publishing, your skill is searchable and installable by anyone running openclaw skills install your-skill-name.

Common skill patterns

Four patterns cover the vast majority of custom skills. Use these as starting points.

API caller. The skill instructs the agent to make HTTP requests to a specific API, parse the response, and present the results. Include the base URL, required headers, and expected response format in your instructions. Always specify error handling for rate limits and authentication failures.

File processor. The skill reads files from a directory, transforms them, and writes the output somewhere. Common uses include CSV conversion, log parsing, and batch renaming. Specify which file types the skill should handle and what to do with files that do not match.

Web scraper. The skill uses the browser tool to navigate to a page, extract specific data, and return it in a structured format. Include the target URL pattern, the CSS selectors or content markers to look for, and how to handle pages that load dynamically.

Scheduler. The skill runs a task on a recurring basis, usually combined with cron or a system timer. The instructions should cover what triggers the task, what the task does, and where to store the output. Specify retry behavior for transient failures.

Security considerations

Skills are powerful, and that power comes with real risk. The ClawHavoc campaign in early 2026 demonstrated what happens when malicious skills go unvetted: data exfiltration, prompt injection, and credential theft across thousands of OpenClaw instances. Before you install anyone else’s skill, and before you publish your own, keep these principles in mind.

Minimize permissions. Only request the tools your skill actually needs. A text formatting skill should not require network access. A git summary skill does not need file write permissions outside the repository.

Never embed secrets. Do not put API keys, tokens, or credentials directly in SKILL.md. Reference environment variables instead, and document which variables the user needs to set.

Avoid obfuscation. If your skill includes supporting scripts, keep them readable. Obfuscated or minified code is a red flag for anyone reviewing your skill, and ClawHub’s automated scanning may flag it.

Test in a sandbox. Before publishing, run your skill with openclaw sandbox run to verify it only accesses what it should.

For a detailed breakdown of how malicious skills work and how to vet them, read our analysis of the ClawHavoc campaign.

What to build next

Start with a skill that solves a problem you personally face every day. The best skills on ClawHub grew out of someone automating their own repeated task and then sharing it. Keep the instructions focused on one job. If your skill is trying to do five different things, split it into five skills.

ClawHub crossed 13,000 published skills in early 2026, and the registry is growing fast. The sooner you publish, the sooner others benefit from your work.

Questions about building OpenClaw skills or need help with your setup? Book a Call.