Guide for creating, updating, and managing skills. Use when: you need to extend your capabilities with a new skill, or the user asks you to create one. Skills are persistent Markdown instruction modules auto-discovered at runtime.

Skill Creation

You can create new skills to extend your own capabilities. Skills are Markdown instruction modules that persist across conversations and require no restart.

When to Create a Skill

A recurring task that benefits from a structured workflow
Domain knowledge worth preserving across conversations
A multi-step process the user asks about repeatedly
Integration with a new CLI tool or API

When NOT to Create a Skill

One-off tasks that won't recur
Information that belongs in MEMORY.md (user preferences, personal facts)
Temporary instructions or experiment notes

How to Create a Skill

Choose a name: lowercase, digits, hyphens only (e.g., meeting-notes, code-review)
Create the file using write_file:

write_file("skills/<name>/SKILL.md", content)

The skill is available immediately on the next message — no restart needed
Always tell the user when you create a new skill

SKILL.md Format

Every skill needs a YAML frontmatter block followed by Markdown instructions:

---
name: <skill-name>
description: "Brief description of what this skill does and when to use it. Max 1024 chars."
---

# Skill Title

Instructions in markdown...

Frontmatter Fields

Field	Required	Description
`name`	Yes	Must match the directory name exactly
`description`	Yes	What the skill does and when to use it. Max 1024 chars
`requires_env`	No	List of environment variables needed (skill is hidden if missing)
`requires_bridge`	No	Host gateway bridge name required (skill is hidden if bridge unavailable)
`homepage`	No	External URL for reference documentation
`metadata`	No	Provider-specific metadata (e.g., OpenClaw)

Frontmatter Examples

Simple skill (no dependencies):

---
name: meeting-notes
description: "Generate structured meeting notes from conversations. Use when the user asks to summarize or document a meeting."
---

Skill requiring an API key:

---
name: notion
description: "Manage Notion workspace: create pages, query databases, add content blocks. Requires NOTION_API_KEY."
requires_env:
  - NOTION_API_KEY
---

Skill requiring a host bridge:

---
name: spotify
description: "Control Spotify playback: play, pause, skip, search tracks/albums/playlists via spogo CLI."
requires_bridge: "spotify"
---

Body Structure

Follow this structure for the Markdown body:

# Skill Title

Brief one-line summary.

## When to Use

- Trigger phrase or scenario 1
- Trigger phrase or scenario 2

## When NOT to Use

- Scenario where another approach is better

## Commands / Workflow

Step-by-step instructions, code blocks, curl examples, etc.

## Notes

- Caveats, rate limits, known issues

Guidelines for the Body

Be procedural: write steps the agent can follow, not conceptual explanations
Include concrete examples: real commands, API calls, curl snippets
Use code blocks with language hints for syntax highlighting
Document known issues and workarounds — these save the most time
Keep it concise: aim for what's needed to execute, not exhaustive documentation

Rules

Only create SKILL.md files — never create Python scripts or executable code in skill directories
The name in frontmatter MUST match the directory name
One skill per directory, one SKILL.md per skill
You can add supporting files (configs, docs) in the same directory if needed
You can update or delete your own skills when they become outdated
Always verify the skill works by reading it back after creation

Updating & Deleting Skills

Update: use edit_file or write_file to modify skills/<name>/SKILL.md
Delete: remove the skill directory (tell the user first)
Changes take effect on the next message — no restart needed

skill-creation