Subtopic 6.1 explained what a skill is — a markdown file in ~/.openclaw/skills/ that the agent loads on demand, with only the metadata in the prompt at session start. Subtopic 6.2 is the hands-on: how to write the file, how to choose between the two creation methods (conversational vs explicit), and how to make sure the metadata is doing the matching the body is doing the work.

The structural rule is the same as 6.1: a skill is a recipe, the metadata is the index entry, and the body is the recipe itself. The agent reads the metadata to decide if the skill matches the task; the agent reads the body to know what to do. The whole craft of writing a good skill is making the metadata precise enough to match reliably and the body concrete enough to execute without re-prompting.

This article walks through the file structure, the metadata design, the body design, the two creation methods, and the iteration loop that turns a first draft into a reliable recipe. The cron layer comes in 6.3; for now, the focus is the file on disk.

What you'll learn

  • The canonical skill file has YAML frontmatter (name, description, trigger keywords, tags, version) followed by a markdown body with sections for Purpose, When to Use, Steps, Output Format, and Quality Checks (obET69yycFc, transcript).
  • The description field is the most important piece of metadata — it's what the agent matches against the user's task. A vague description produces fuzzy matching; a specific description with trigger keywords produces precise matching (obET69yycFc, transcript).
  • Two creation methods: conversational ("save this as a skill") and explicit ("create a skill with these specs"). The conversational method is faster for non-technical users; the explicit method is better when you already have a clear recipe in mind.
  • The body should be specific about the output format — file path, format type, delivery channel. The host's example: "save to ~/presentations/daily/YYYY-MM-DD.pptx, post to Discord #daily-briefing" (obET69yycFc, transcript).
  • Skills can chain to other skills. The main skill lists "execute skill: tweet_digest" as one of its steps, and the agent loads the second skill on demand (obET69yycFc, transcript).
  • Skills should end with a "Common Pitfalls" or "Quality Checks" section. The agent reads the file top-to-bottom, and the last section gets the freshest attention (obET69yycFc, transcript).

The file structure, end-to-end

A skill file is a markdown file with YAML frontmatter. The minimum viable skill looks like this (obET69yycFc, transcript):

---
name: tweet_digest
description: Summarises the last 24 hours of tweets from monitored accounts
trigger: tweets, twitter, x, digest, daily
tags: [social, research, daily]
version: 1.0.0
last_updated: 2026-05-06
---

# Tweet Digest