What Are Skills?

+15 Mana ✨
OpenClaw Skills Reference(DOCUMENTATION)OpenClaw SKILL.md Format(DOCUMENTATION)

Introduction

Skills are modular capabilities you can add to your OpenClaw agent. Each skill is defined by a SKILL.md file containing YAML frontmatter and Markdown instructions. Skills extend what your agent can do without modifying its core configuration, letting you add specialized behaviors like git commit helpers, code review workflows, or deployment automation as self-contained packages.

Key Concepts

  • SKILL.md: The file that defines a skill, containing YAML frontmatter for metadata and Markdown body for instructions
  • YAML Frontmatter: Structured metadata at the top of SKILL.md including name, description, and behavioral flags
  • Skill Directory: A folder containing SKILL.md and any supporting files the skill needs
  • User-Invocable Skills: Skills the user can trigger by name (e.g., /commit), controlled by the user-invocable frontmatter field
  • Model-Invocable Skills: Skills the agent can decide to use on its own, unless disabled by disable-model-invocation

Real World Context

A team wants their agent to follow a specific git commit workflow: stage changes, generate a conventional commit message, run pre-commit hooks, and create the commit. Instead of writing these instructions into AGENTS.md (which would clutter it with one specific workflow), they create a git-commit skill. Team members invoke it with /commit and the agent follows the skill's instructions precisely, every time.

Deep Dive

A skill lives in a directory with at minimum a SKILL.md file. Here is the structure:

skills/
  git-commit/
    SKILL.md
  code-review/
    SKILL.md
    templates/
      review-checklist.md

The SKILL.md file has two parts: YAML frontmatter and a Markdown body.

Here is a complete SKILL.md example:

yaml
---
name: git-commit
description: Generates conventional commit messages and creates commits
user-invocable: true
disable-model-invocation: false
---

# Git Commit Skill

When invoked, follow these steps:

1. Run `git status` to see staged and unstaged changes
2. If no changes are staged, ask the user what to stage
3. Analyze the staged changes to determine the commit type
4. Generate a conventional commit message (feat, fix, chore, etc.)
5. Show the proposed message to the user for approval
6. Run `git commit -m "<message>"` on approval
7. Report the commit hash and summary

The YAML frontmatter between the --- delimiters defines the skill's metadata. The name field is the skill's identifier. The description tells the agent and users what the skill does. The user-invocable: true flag means users can trigger it with /git-commit. The disable-model-invocation: false flag means the agent can also decide to use this skill on its own when it determines the situation is appropriate.

The Markdown body below the frontmatter contains the actual instructions the agent follows when the skill is activated. These instructions are injected into the agent's context only when the skill is invoked, not all the time. This is a key difference from AGENTS.md, which is always present.

The available frontmatter fields include:

yaml
---
name: string           # Required. Skill identifier
description: string    # Required. What the skill does
user-invocable: bool   # Can users trigger it? Default: false
disable-model-invocation: bool  # Prevent agent auto-use? Default: false
requires:
  bins: ["git"]        # Required binaries on PATH
  env: ["GITHUB_TOKEN"] # Required environment variables
os: ["macos", "linux"] # OS restrictions
install: "npm i -g pkg" # Install command for dependencies
---

These fields give you fine-grained control over when and how the skill is available.

Common Pitfalls

  • Making every skill user-invocable: Not all skills should be triggered by users. Some are better as automatic behaviors the agent uses when appropriate.
  • Writing overly long skill instructions: Skills should be focused on one capability. If your SKILL.md exceeds 500 lines, consider splitting it into multiple skills.
  • Forgetting the description field: Without a description, the agent cannot determine when to use the skill automatically, and users cannot discover what it does.

Best Practices

  • One skill per capability: Each skill should do one thing well. A "git-commit" skill should not also handle branch management.
  • Write clear step-by-step instructions: The Markdown body should read like a recipe, with numbered steps the agent can follow deterministically.
  • Use the requires field: Specify binary and environment variable dependencies so the agent knows upfront if the skill can run in the current environment.

Summary

  • Skills are modular capabilities defined by SKILL.md files with YAML frontmatter and Markdown instructions
  • Frontmatter fields control metadata (name, description), invocation (user-invocable, disable-model-invocation), and requirements (bins, env, os)
  • Skill instructions are injected into the agent's context only when the skill is invoked, not permanently
  • Skills keep AGENTS.md clean by extracting specific workflows into self-contained packages
  • Each skill should focus on a single capability with clear, step-by-step instructions
✓ Completed