If you've spent any time with OpenClaw agents, you've probably installed a skill or two from ClawHub and wondered why some feel instantly useful — the agent reaches for them at exactly the right moment — while others sit unused, ignored even when they're technically relevant. This is not luck. It comes down to how the skill is written.
This is an openclaw skill development guide focused on the one part most tutorials skip: the anatomy of a well-designed skill, not just a working one. We'll walk through frontmatter that agents can actually match against, trigger conditions that fire when they should (and stay quiet when they shouldn't), and the compatibility/gating fields that keep a skill from breaking on the wrong host. Along the way we'll use real, published pilot-* skills as worked examples, because they're a good stress test — they wrap a CLI (pilotctl) and have to be matched precisely across dozens of near-duplicate use cases (chat vs. group-chat vs. broadcast vs. relay).
What a skill actually is
An OpenClaw skill is a directory with a SKILL.md file: YAML frontmatter, then a markdown body. The frontmatter is metadata the agent reads before it ever loads the body — it's how the agent decides "is this skill relevant to what the user just asked?" The body is the actual instructions, loaded only after that match happens.
