SKILL.md is both a routing document and a work instruction. Its frontmatter helps the host decide whether the skill belongs in the current task. Its body tells the agent what to do after activation. Treating either half as generic documentation produces a skill that loads at the wrong time or gives weak results.

Start with the trigger contract

The required frontmatter is deliberately small. Use a lowercase, stable name and a description that says what the skill does, when to use it, and where its boundary ends. Front-load the important terms because hosts may shorten long descriptions when many skills are installed.

---
name: release-notes
description: Turn merged product work into customer-facing release notes. Use when a user asks for a changelog, launch notes, or a release summary from commits or pull requests.
---

# Release-notes workflow

Collect the shipped changes, group them by product area, and explain the user-visible result.

Test that description with real language. “Write the notes for today’s release from these PRs” should match. “Summarize this meeting” should not. Trigger tests reveal overlap before a large body hides the problem.

Write the body as a decision path

Begin with the outcome and the inputs. Then describe the steps that change the input into the output. State what evidence is authoritative, how to handle missing facts, which actions require approval, and what a complete result looks like. Use ordered steps when sequence matters and short principles when the agent needs judgment.

Avoid copying an entire team handbook into the body. Keep the common path readable and move long policies, schemas, examples, or edge-case tables into references/. This lets the agent load the detail only when it needs it and keeps the skill’s activation cost low.

Use scripts for deterministic work

A script earns its place when prose would repeatedly recreate the same parser, validator, conversion, or API request. Give each script a narrow interface, predictable exit code, and concise output. Never place credentials in the package. Explain what the script reads, what it writes, and how the agent should respond when it fails.

Keep portable fields separate from host extensions

name, description, license, compatibility, and metadata are broadly portable. Hosts add fields for tool grants, invocation control, dynamic context, presentation, or subagent execution. Those extensions can be valuable, but another host may ignore them. Put the cross-platform workflow in the body and isolate optional host behavior so the core skill remains understandable.

Review against five failure modes

  • Never triggers: the description uses internal jargon instead of the user’s words.
  • Triggers everywhere: the scope is broad and has no negative boundary.
  • Runs but wanders: the outcome and completion check are missing.
  • Consumes too much context: background material belongs in references.
  • Works only for the author: hidden assumptions are not stated as inputs or rules.

Verify behavior, not appearance

Run several tasks that should trigger, several that should not, and at least one incomplete-input case. Compare the result with the same agent working without the skill. Inspect whether it chose the right evidence, followed the required sequence, respected boundaries, and produced the requested artifact. A valid Markdown file is only the start; repeatable behavior is the product.