Building Your First OpenClaw Skill

We will build a skill called `release-notes` that generates user-facing release notes from recent commits. It is the canonical first-skill exercise: small enough to ship in a sitting, large enough to exercise every part of the workflow. By the end you will have a manifest, a procedure, an example output, and a test harness that proves the skill triggers and runs locally.

The file layout

.openclaw/skills/release-notes/
├── SKILL.md              # manifest + procedure (the whole skill, mostly)
├── examples/
│   └── sample-output.md  # what good output looks like
├── helpers/
│   └── group_commits.sh  # optional helper script the procedure can call
└── README.md             # human-facing notes (not loaded by the soul)

Anatomy of SKILL.md

---
name: release-notes
description: Generate user-facing release notes from recent commits. Triggers when the user asks for release notes, changelog entries, or what changed since version X.
tools: [bash, edit]
permissions:
  bash:
    - git log
    - git diff
  edit: true
---

# Release Notes

When invoked:

1. Run `git log --oneline <last-tag>..HEAD` to gather commits.
2. Group commits by type using `helpers/group_commits.sh` if available, otherwise by parsing `feat:`, `fix:`, `perf:`, `docs:` prefixes inline.
3. Translate each commit subject into user-facing language. "feat: add export endpoint" becomes "You can now export reports as CSV."
4. Output as Markdown with a single H1 (the new version) and per-type H2 sections.
5. Suggest a one-line summary at the very top.

See `examples/sample-output.md` for the expected shape.

If there are no commits since the last tag, return "No user-visible changes" and stop.

Progressive disclosure inside the SKILL.md itself

A SKILL.md that runs past a few hundred lines will swamp the soul's context budget the moment it loads. The pattern that scales is to keep the procedure tight and push reference material into companion files the procedure can read on demand — examples, lookup tables, edge-case playbooks. Load lean by default, fetch detail when needed.

The tool-call interface

Skills declare which tools they intend to use in frontmatter. OpenClaw enforces this — a skill that lists `tools: [bash, edit]` cannot suddenly call the network tool mid-procedure. Be specific in the permissions block: list exact bash commands or path patterns rather than blanket access. The narrower the tool surface, the safer the skill is to install.

• Tools list — declare every tool the procedure may call
• Permissions block — narrow each tool to specific commands, paths, or hosts
• Confirmation flags — mark destructive tools as confirm-required so the soul pauses before firing
• Implicit deny — anything not declared is blocked at runtime

Test it locally

1. 1Spawn a soul in a workspace that has the skill folder under `.openclaw/skills/`
2. 2Type a request the description should match — try at least three phrasings
3. 3Confirm the soul announces it is loading `release-notes`; if it doesn't, the description is wrong, not the procedure
4. 4Watch the trace — does it call the tools you expected, in the order you expected?
5. 5Check the output against `examples/sample-output.md`. If it drifts, sharpen the procedure

Apply: ship one tonight

1. 1Pick a workflow you do at least weekly (changelog, code review, deploy notes)
2. 2Create a `.openclaw/skills/<name>/` folder with a SKILL.md
3. 3Write the manifest first — five plausible user phrasings should all match the description
4. 4Write the procedure as a numbered list of steps the soul should follow
5. 5Test with three different request phrasings; iterate until all three trigger and produce useful output
6. 6Commit the folder to your repo so the rest of your team gets the skill for free

The big idea: a working skill is a manifest you tested against real phrasings, a procedure under 300 lines, a narrow tool surface, and an examples folder. Build that and ship — refinement comes from use, not from perfecting in isolation.