OpenClaw skills development: teach the agent, budget the tokens.

Quick answer: a skill is a folder with a SKILL.md.

The minimum viable skill is two frontmatter fields and a body. name identifies the skill (and names its slash command); description tells the model what the skill does and when to reach for it. The body is the actual instruction set the agent reads when the skill becomes relevant. Where the folder lives determines who gets it. OpenClaw discovers SKILL.md files under several roots and resolves name collisions by precedence: workspace skills win over project agent skills, which win over personal ~/.agents skills, then managed skills under ~/.openclaw/skills, then the bundled set that ships with the install. Drop a folder with a bundled skill's name into your workspace and yours wins, which is the sanctioned way to customize built-in behavior.

---
name: release-notes
description: Draft release notes from merged PRs. Use when the user asks
  for release notes, a changelog, or "what shipped".
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["gh"], "env": ["GITHUB_TOKEN"] },
        "emoji": "📝",
      },
  }
---

# Release notes

1. List PRs merged since the last tag: `gh pr list --state merged ...`
2. Group by area (feat/fix/chore) using the PR labels.
3. Write one line per change, user-facing wording, no ticket numbers.
4. Output a draft; do not post anywhere without confirmation.

How a skill actually reaches the model.

Understanding the injection path is what separates skills that work from skills that flail. At session start, OpenClaw snapshots the eligible skill list: gating evaluated (required binaries on PATH, env vars present, config paths truthy, OS match), agent allowlists applied, disabled entries dropped. Eligible skills are compiled into a compact XML block in the system prompt, name and description only, at a cost the docs put around two dozen tokens per skill plus fixed overhead. The body of a SKILL.md is not preloaded. The model sees the descriptions, decides a skill is relevant, and reads the full file through its tools at that moment. That two-stage design is the token economics of the whole system: descriptions are the always-paid index, bodies are pay-on-use. A skills watcher refreshes the snapshot when a SKILL.md changes mid-session, so editing a skill does not require restarting anything. Two frontmatter switches modulate the flow: user-invocable exposes the skill as a slash command, and disable-model-invocation keeps a skill out of the prompt entirely so it only fires when a human calls it, useful for expensive or destructive workflows.

Authoring rules that survive contact with the model.

Distribution has first-class tooling: openclaw skills install pulls from ClawHub (the public registry), from git, or from a local path, and openclaw skills verify checks a published skill's trust envelope. Treat third-party skills as untrusted code, because that is what they are: they run with your agent's tools on your machine. The Skill Workshop closes the loop from the other side, when the agent notices a reusable workflow, it drafts a skill proposal for your review instead of silently editing its own instructions.

• Write the description for routing, not marketing: it is the only thing the model sees before choosing. State what the skill does and the trigger phrases, "use when the user asks for X", in one or two sentences.
• Write the body as a procedure: numbered steps, exact commands, expected outputs, and explicit stop conditions. Prose essays make the model improvise; checklists make it execute.
• State boundaries in the body: what the skill must not do (post publicly, delete, spend) and when to hand back to the user. The model honors written constraints far better than implied ones.
• Gate honestly: declare required binaries and env vars in metadata so the skill vanishes on hosts that cannot run it, instead of failing mid-turn.
• Keep one skill per job: a folder that tries to be five workflows produces a description too vague to route and a body too long to follow.
• Version through git: skills are plain files, so the workspace skills directory belongs in a repo, and skill edits get reviewed like code.

Pay-as-you-go · transparent per-model pricing

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Which model tier should run a skill loop.

A skill invocation is not one model call. The agent reads the SKILL.md, executes its steps through tool calls, and re-enters the model between steps, so a five-step skill is routinely six or more requests, each carrying the session's full context. The model serving that loop is therefore a per-skill economic decision, and the skill taxonomy maps cleanly onto model tiers. Procedural skills, fixed steps, deterministic commands, formulaic output (log summaries, backup checks, feed digests), run correctly on budget models: deepseek-v4-flash or claude-haiku-4-5-20251001 grade. The skill body is doing the thinking; the model is following it. Judgment skills, drafting, triage, anything where step three is "decide", earn a mid tier like claude-sonnet-4-6 or glm-5.2. The body constrains the work, but quality of judgment is the output. Human-facing writing skills inherit the bar of the audience: if the skill drafts text a customer will read, run it on the tier you would let answer that customer directly. OpenClaw gives you the routing levers: per-session /model switching for testing, and per-agent model defaults so a dedicated cron or utility agent runs its procedural skills on a budget id while your main agent keeps a stronger default. Through one gateway key the whole matrix is config, and per-model usage in the console shows what each skill's loop actually costs.

Token budgeting: where skill installs get expensive.

The audit is straightforward: read one session transcript (they are JSONL on disk) after a skill-heavy turn and look at what the context actually contained. Ten minutes with a transcript teaches more about your real token flow than any estimate, and the per-request usage log on the gateway side prices what you saw.

• The description tax is per turn, not per use: every eligible skill's description rides on every run of that agent. Forty always-eligible skills add roughly a thousand tokens to each turn before anyone types anything.
• Allowlists are the budget tool: agents.defaults.skills, and per-agent skills lists, scope which skills inject where. A locked-down utility agent with three skills pays for three descriptions.
• Long bodies bill on use: a 2,000-token SKILL.md enters context whenever the skill fires, and stays in the turn's context through every subsequent loop iteration. Tight bodies are quality and cost improvements at once.
• Chatty steps compound: a skill step that cats a whole file into context taxes every remaining iteration of that turn. Prefer steps that extract, grep and head, over steps that dump.
• disable-model-invocation is a cost switch too: expensive workflows behind a slash command cost nothing until a human explicitly invokes them.

A development workflow that scales past the first skill.

Develop in the workspace: workspace skills have top precedence, so your draft shadows any managed or bundled skill with the same name while you iterate, and the watcher picks up edits live. Test the routing before the procedure, ask the agent things that should and should not trigger the skill, and tune the description until both behave. Then test the procedure on the model tier you intend to run it on, not just your default: a skill that works on Sonnet and fails on Flash needs either a tighter body or a better tier assignment, and you want to know which before it runs at 3 a.m. from cron. Then instrument. Give the agent that runs your skills its own gateway key, and the console's per-key view becomes a per-agent cost report; spikes trace back through the session transcript to the exact skill and step. Skills that prove out graduate from the workspace into a git-tracked shared directory, or onto ClawHub if they are worth publishing, with the trust caveats above applying in reverse to your users.

FAQ