Building Your First OpenClaw Skill

Walk through the file layout, the SKILL.md progressive-disclosure pattern, the tool-call interface, and how to test a skill locally before sharing it. The other refrain echoed by both OpenClaw maintainers and Claude Code skill authors: write the test (the example output you want) before the procedure.

11 min · Reviewed 2026

What you are building

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)A typical skill folder. SKILL.md is the only required file. Everything else is referenced from inside it.

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.The whole skill, in one file. Frontmatter for the soul, prose for the procedure, references for the assets.

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

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

Apply: ship one tonight

Pick a workflow you do at least weekly (changelog, code review, deploy notes)
Create a `.openclaw/skills/<name>/` folder with a SKILL.md
Write the manifest first — five plausible user phrasings should all match the description
Write the procedure as a numbered list of steps the soul should follow
Test with three different request phrasings; iterate until all three trigger and produce useful output
Commit 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.

End-of-lesson check

15 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-openclaw-skills-build-first-creators

What is the core idea behind "Building Your First OpenClaw Skill"?
1. Walk through the file layout, the SKILL.md progressive-disclosure pattern, the tool-call interface, and how to test a skill locally before sharing it. The other refrain echoed by both OpenClaw maintainers and Claude Code skill authors: write the test (the example output you want) before the procedure.
2. Inspect the permissions block — would you be comfortable if every line ran right…
3. wrap
4. Set a maximum step count or token budget; abort cleanly when exceeded
Which term best describes a foundational idea in "Building Your First OpenClaw Skill"?
1. frontmatter
2. SKILL.md
3. tool surface
4. implicit trigger
A learner studying Building Your First OpenClaw Skill would need to understand which concept?
1. SKILL.md
2. tool surface
3. frontmatter
4. implicit trigger
Which of these is directly relevant to Building Your First OpenClaw Skill?
1. SKILL.md
2. frontmatter
3. implicit trigger
4. tool surface
Which of the following is a key point about Building Your First OpenClaw Skill?
1. Tools list — declare every tool the procedure may call
2. Permissions block — narrow each tool to specific commands, paths, or hosts
3. Confirmation flags — mark destructive tools as confirm-required so the soul pauses before firing
4. Implicit deny — anything not declared is blocked at runtime
Which of these does NOT belong in a discussion of Building Your First OpenClaw Skill?
1. Permissions block — narrow each tool to specific commands, paths, or hosts
2. Tools list — declare every tool the procedure may call
3. wrap
4. Confirmation flags — mark destructive tools as confirm-required so the soul pauses before firing
Which statement is accurate regarding Building Your First OpenClaw Skill?
1. Type a request the description should match — try at least three phrasings
2. Confirm the soul announces it is loading `release-notes`; if it doesn't, the description is wrong, n…
3. Spawn a soul in a workspace that has the skill folder under `.openclaw/skills/`
4. Watch the trace — does it call the tools you expected, in the order you expected?
Which of these does NOT belong in a discussion of Building Your First OpenClaw Skill?
1. Inspect the permissions block — would you be comfortable if every line ran right…
2. Spawn a soul in a workspace that has the skill folder under `.openclaw/skills/`
3. Confirm the soul announces it is loading `release-notes`; if it doesn't, the description is wrong, n…
4. Type a request the description should match — try at least three phrasings
What is the key insight about "One folder, one skill" in the context of Building Your First OpenClaw Skill?
1. Resist the urge to bundle multiple skills into one folder. The soul matches at the folder level — two skills sharing a f…
2. Inspect the permissions block — would you be comfortable if every line ran right…
3. wrap
4. Set a maximum step count or token budget; abort cleanly when exceeded
What is the key insight about "Aim for SKILL.md under 300 lines" in the context of Building Your First OpenClaw Skill?
1. Inspect the permissions block — would you be comfortable if every line ran right…
2. Anything longer is a code smell. If your procedure needs more, split into sub-files (`examples/`, `cases/`, `templates/`…
3. wrap
4. Set a maximum step count or token budget; abort cleanly when exceeded
What is the key insight about "Failure to trigger is the most common bug" in the context of Building Your First OpenClaw Skill?
1. Inspect the permissions block — would you be comfortable if every line ran right…
2. wrap
3. Most first skills 'work' the moment you invoke them by name and 'fail' when fired implicitly — because the description d…
4. Set a maximum step count or token budget; abort cleanly when exceeded
Which statement accurately describes an aspect of Building Your First OpenClaw Skill?
1. Inspect the permissions block — would you be comfortable if every line ran right…
2. wrap
3. Set a maximum step count or token budget; abort cleanly when exceeded
4. We will build a skill called `release-notes` that generates user-facing release notes from recent commits.
What does working with Building Your First OpenClaw Skill typically involve?
1. A SKILL.md that runs past a few hundred lines will swamp the soul's context budget the moment it loads.
2. Inspect the permissions block — would you be comfortable if every line ran right…
3. wrap
4. Set a maximum step count or token budget; abort cleanly when exceeded
Which of the following is true about Building Your First OpenClaw Skill?
1. Inspect the permissions block — would you be comfortable if every line ran right…
2. Skills declare which tools they intend to use in frontmatter. OpenClaw enforces this — a skill that lists `tools: [bash, edit]` cannot sudde…
3. wrap
4. Set a maximum step count or token budget; abort cleanly when exceeded
Which best describes the scope of "Building Your First OpenClaw Skill"?
1. It is unrelated to tools workflows
2. It applies only to the opposite beginner tier
3. It focuses on Walk through the file layout, the SKILL.md progressive-disclosure pattern, the tool-call interface,
4. It was deprecated in 2024 and no longer relevant

← Back to interactive lesson

Tendril · Creators · Tools Literacy

Building Your First OpenClaw Skill

11 min · Reviewed 2026

What you are building

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)A typical skill folder. SKILL.md is the only required file. Everything else is referenced from inside it.

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.The whole skill, in one file. Frontmatter for the soul, prose for the procedure, references for the assets.

Progressive disclosure inside the SKILL.md itself

The tool-call interface

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

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

Apply: ship one tonight

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

End-of-lesson check

15 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-openclaw-skills-build-first-creators

What is the core idea behind "Building Your First OpenClaw Skill"?
1. Walk through the file layout, the SKILL.md progressive-disclosure pattern, the tool-call interface, and how to test a skill locally before sharing it. The other refrain echoed by both OpenClaw maintainers and Claude Code skill authors: write the test (the example output you want) before the procedure.
2. Inspect the permissions block — would you be comfortable if every line ran right…
3. wrap
4. Set a maximum step count or token budget; abort cleanly when exceeded
Which term best describes a foundational idea in "Building Your First OpenClaw Skill"?
1. frontmatter
2. SKILL.md
3. tool surface
4. implicit trigger
A learner studying Building Your First OpenClaw Skill would need to understand which concept?
1. SKILL.md
2. tool surface
3. frontmatter
4. implicit trigger
Which of these is directly relevant to Building Your First OpenClaw Skill?
1. SKILL.md
2. frontmatter
3. implicit trigger
4. tool surface
Which of the following is a key point about Building Your First OpenClaw Skill?
1. Tools list — declare every tool the procedure may call
2. Permissions block — narrow each tool to specific commands, paths, or hosts
3. Confirmation flags — mark destructive tools as confirm-required so the soul pauses before firing
4. Implicit deny — anything not declared is blocked at runtime
Which of these does NOT belong in a discussion of Building Your First OpenClaw Skill?
1. Permissions block — narrow each tool to specific commands, paths, or hosts
2. Tools list — declare every tool the procedure may call
3. wrap
4. Confirmation flags — mark destructive tools as confirm-required so the soul pauses before firing
Which statement is accurate regarding Building Your First OpenClaw Skill?
1. Type a request the description should match — try at least three phrasings
2. Confirm the soul announces it is loading `release-notes`; if it doesn't, the description is wrong, n…
3. Spawn a soul in a workspace that has the skill folder under `.openclaw/skills/`
4. Watch the trace — does it call the tools you expected, in the order you expected?
Which of these does NOT belong in a discussion of Building Your First OpenClaw Skill?
1. Inspect the permissions block — would you be comfortable if every line ran right…
2. Spawn a soul in a workspace that has the skill folder under `.openclaw/skills/`
3. Confirm the soul announces it is loading `release-notes`; if it doesn't, the description is wrong, n…
4. Type a request the description should match — try at least three phrasings
What is the key insight about "One folder, one skill" in the context of Building Your First OpenClaw Skill?
1. Resist the urge to bundle multiple skills into one folder. The soul matches at the folder level — two skills sharing a f…
2. Inspect the permissions block — would you be comfortable if every line ran right…
3. wrap
4. Set a maximum step count or token budget; abort cleanly when exceeded
What is the key insight about "Aim for SKILL.md under 300 lines" in the context of Building Your First OpenClaw Skill?
1. Inspect the permissions block — would you be comfortable if every line ran right…
2. Anything longer is a code smell. If your procedure needs more, split into sub-files (`examples/`, `cases/`, `templates/`…
3. wrap
4. Set a maximum step count or token budget; abort cleanly when exceeded
What is the key insight about "Failure to trigger is the most common bug" in the context of Building Your First OpenClaw Skill?
1. Inspect the permissions block — would you be comfortable if every line ran right…
2. wrap
3. Most first skills 'work' the moment you invoke them by name and 'fail' when fired implicitly — because the description d…
4. Set a maximum step count or token budget; abort cleanly when exceeded
Which statement accurately describes an aspect of Building Your First OpenClaw Skill?
1. Inspect the permissions block — would you be comfortable if every line ran right…
2. wrap
3. Set a maximum step count or token budget; abort cleanly when exceeded
4. We will build a skill called `release-notes` that generates user-facing release notes from recent commits.
What does working with Building Your First OpenClaw Skill typically involve?
1. A SKILL.md that runs past a few hundred lines will swamp the soul's context budget the moment it loads.
2. Inspect the permissions block — would you be comfortable if every line ran right…
3. wrap
4. Set a maximum step count or token budget; abort cleanly when exceeded
Which of the following is true about Building Your First OpenClaw Skill?
1. Inspect the permissions block — would you be comfortable if every line ran right…
2. Skills declare which tools they intend to use in frontmatter. OpenClaw enforces this — a skill that lists `tools: [bash, edit]` cannot sudde…
3. wrap
4. Set a maximum step count or token budget; abort cleanly when exceeded
Which best describes the scope of "Building Your First OpenClaw Skill"?
1. It is unrelated to tools workflows
2. It applies only to the opposite beginner tier
3. It focuses on Walk through the file layout, the SKILL.md progressive-disclosure pattern, the tool-call interface,
4. It was deprecated in 2024 and no longer relevant

← Back to interactive lesson