OpenClaw Skills Explained: What They Are and How to Write One

OpenClaw Skills are the mechanism by which DenchClaw's AI agent learns new capabilities. Instead of shipping features as code updates, Skills let you extend the agent with plain markdown files. Drop a SKILL.md into the right directory, and the agent immediately knows how to do something it didn't before — scrape LinkedIn, send emails, query an external API, manage your calendar.

This article explains exactly what Skills are, how they're structured, and walks through writing one from scratch.

What Is an OpenClaw Skill?#

A Skill is a SKILL.md file that lives inside the skills/ directory of your workspace. When DenchClaw's agent starts a session, it scans that directory and loads relevant skills based on what the user is asking for. The skill file gives the agent:

1. Context — what the skill does and when to use it
2. Instructions — step-by-step guidance on how to execute the task
3. Tool usage — which CLI tools, APIs, or commands to call
4. Examples — sample inputs and expected outputs

Think of a Skill as a procedure manual for a specialist. The agent is the contractor; the Skill is the spec sheet.

Skills ship with DenchClaw out of the box for common tasks: CRM management, browser automation, app building, email, calendar, GitHub, and more. You can also install additional skills from clawhub.ai, or write your own.

Skill Directory Structure#

workspace/
  skills/
    crm/
      SKILL.md
    browser/
      SKILL.md
      scripts/
        scrape-profile.js
    my-custom-skill/
      SKILL.md
      references/
        api-docs.md

Each skill lives in its own subdirectory. The only required file is SKILL.md. You can include helper scripts, reference documents, or any supporting files alongside it.

How the Agent Selects Skills#

When you send a message to DenchClaw, the orchestrator scans the available skills and matches them to your request. The selection logic follows this priority:

1. Exact match — a skill explicitly named for the task (e.g., github skill for GitHub operations)
2. Description match — the <description> in the skill's metadata matches the intent
3. No match — the agent proceeds with built-in capabilities

Once selected, the agent reads the full SKILL.md and follows its instructions. This is why Skills must be self-contained — the agent has no other context about how to use the tool.

Anatomy of a SKILL.md File#

Here's the minimal structure of a working skill:

# My Skill Name
 
## Description
What this skill does and when to use it. Keep this concise — it's used for skill selection.
 
## Prerequisites
- CLI tool installed: `brew install sometool`
- API key set: `export SOME_API_KEY=...`
 
## Usage
 
### Task: Do the Thing
 
1. Run `sometool list` to get available items
2. Parse the output
3. Return results to the user
 
### Task: Create a New Item
 
1. Run `sometool create --name "NAME" --type "TYPE"`
2. Confirm success with exit code 0
3. Report the created item ID back
 
## Examples
 
**User:** "List all my open tickets"
**Agent action:** Run `sometool list --status open` and format results as a table
 
## Notes
- Rate limit: 100 requests/minute
- Output is JSON; parse with `jq` or directly in the tool call

That's it. Plain markdown. No code compilation, no schema validation, no deployment pipeline.

Writing Your First Skill#

Let's build a real skill: one that wraps the gh CLI to check open pull requests across your repos.

Step 1: Create the skill directory#

mkdir -p ~/.openclaw-dench/workspace/skills/my-prs
touch ~/.openclaw-dench/workspace/skills/my-prs/SKILL.md

Step 2: Write the SKILL.md#

# My PRs
 
## Description
Check open pull requests across GitHub repos using the `gh` CLI. Use when the user asks about pending PRs, code reviews, or CI status.
 
## Prerequisites
- `gh` CLI installed and authenticated: `gh auth status`
 
## Usage
 
### Task: List open PRs
 
1. Run `gh pr list --author @me --state open --json title,url,repository,createdAt`
2. Format results as a list with: title, repo name, URL, and age
3. Highlight any PRs older than 7 days
 
### Task: Check CI status on a PR
 
1. Run `gh pr checks <PR_NUMBER>` in the relevant repo directory
2. Report pass/fail for each check
3. If any checks failed, include the log URL
 
### Task: Open a PR in the browser
 
1. Run `gh pr view <PR_NUMBER> --web`
 
## Notes
- If the user doesn't specify a repo, list PRs across all repos the user has access to
- Use `--limit 20` to avoid overwhelming output
- Date format: relative (e.g., "3 days ago")

Step 3: Test it#

Open DenchClaw and ask: "What PRs do I have open?"

The agent will load your new skill and execute the appropriate command. If something's off, edit the SKILL.md directly — no restart required.

Tips for Writing Good Skills#

Be explicit about when to use the skill. The description field drives skill selection. Vague descriptions cause mismatches. Instead of "Manage things", write "Create and list tasks in Things 3 on macOS when the user asks about to-dos, tasks, or reminders."

List prerequisites upfront. If your skill requires a CLI tool, API key, or specific setup, put it at the top. The agent will tell the user what's missing before trying to execute.

Write tasks as numbered steps. The agent follows instructions sequentially. Numbered steps reduce ambiguity and make the skill predictable.

Include error handling. What should the agent do if the command fails? If the API returns 429? If the user doesn't have the tool installed? Cover these cases.

Use references/ for long docs. If your skill wraps a complex API, put the API reference docs in references/api.md and tell the agent to read them. Keeps the SKILL.md clean.

Keep rate limits in mind. If you're wrapping an external API, note the rate limits. The agent will serialize requests rather than fire them in a tight loop.

Installing Skills from ClawHub#

ClawHub is the skill marketplace for OpenClaw. You can browse and install community-built skills:

# Search for skills
clawhub search apollo
 
# Install a skill
clawhub install apollo
 
# Update all installed skills
clawhub update

Installed skills land in ~/.openclaw-dench/workspace/skills/ and are immediately available to the agent.

Skills vs Traditional Plugins#

The traditional plugin model requires code: write a TypeScript module, implement an interface, compile, deploy, restart. Skills skip all of that. A non-engineer can write a working skill in 20 minutes. The tradeoff is that skills rely on the agent's reasoning to interpret instructions — they're not deterministic like code.

For tasks that need exact behavior, you can combine both: write a small helper script and have the skill invoke it. The script provides determinism; the skill provides discoverability and context.

What Skills Can Do#

Skills can instruct the agent to use any tool available in the execution environment:

• Shell commands — anything you can run in a terminal
• Web fetch / browser automation — scrape pages, fill forms, click buttons
• DuckDB queries — read and write CRM data
• HTTP APIs — call external services with curl or native fetch
• File operations — read, write, organize files
• Message sending — Telegram, Slack, Discord, email

The scope is your system. If your machine can do it, a skill can instruct the agent to do it.

FAQ#

Can skills call other skills? Yes. You can tell the agent in your SKILL.md to "load and follow the CRM skill to save results." The agent will load the referenced skill and follow its instructions.

Do I need to restart DenchClaw when I add a skill? No. The agent scans the skills directory at the start of each task. New skills are available immediately.

Can I share my skills with others? Yes. Publish them to ClawHub with clawhub publish. You can also just share the SKILL.md file — it's plain text.

How do I debug a skill that isn't working? Enable verbose mode in your DenchClaw session and watch the agent's tool calls. Usually the issue is in the skill's instructions — too vague, missing a flag, wrong command syntax.

Are skills safe? Can a bad skill cause damage? Skills run with your user permissions. A malicious skill could execute harmful commands. Only install skills from sources you trust. DenchClaw's default exec policy asks for approval on sensitive operations.

Ready to try DenchClaw? Install in one command: npx denchclaw. Full setup guide →