How to write SKILL.md: structure, triggers, and examples

Start with the smallest valid SKILL.md

A standard `SKILL.md` begins with YAML frontmatter and continues with Markdown instructions. The required `name` must match its parent directory, use lowercase letters, numbers, and hyphens, and stay within the specification's length constraints. The required `description` explains the capability and the situations that should activate it. Optional fields can record licensing, compatibility requirements, metadata, or supported tools. Start with those two required fields and a short workflow. Add structure only when a real execution need appears; an elaborate template can hide whether the skill has a clear job at all.

• Directory: `release-readiness/`.
• Frontmatter name: `release-readiness`.
• Description: state the release checks performed and the requests that should trigger them.

Treat the description as a search query matcher

Agents commonly choose skills from the metadata available before activation, so the description has outsized impact. Write it for the phrases a user will actually say. Combine verbs, objects, and trigger situations: 'Audits a web release for broken routes, responsive regressions, metadata, and deployment evidence. Use when asked to QA a release, check ship readiness, or verify a deployed website.' Avoid claims such as 'best-in-class' and vague labels such as 'website helper.' You are defining a routing boundary, not selling the skill. A narrow accurate trigger is more valuable than broad accidental activation.

Make the body an executable operating contract

The Markdown body should answer what the agent must inspect, what it may change, which decisions alter the workflow, and what evidence closes the task. Use imperative steps and stable concepts rather than internal monologue. State which source wins when documentation conflicts with runtime behavior. Define approval boundaries before deploys, deletion, external contact, spending, or production data changes. Include stop conditions for missing credentials or unreadable inputs. End with a reporting contract so the agent tells the user what changed, what was verified, and what remains uncertain instead of producing a ceremonial checklist with no product outcome.

Use progressive disclosure deliberately

The Agent Skills format is designed so metadata is always cheap, full instructions load only after activation, and supporting resources load only when needed. Keep the main file focused on routing and workflow. Put a long API schema in `references/api.md`, working code in `scripts/`, and document or UI templates in `assets/`. Tell the agent exactly when each resource matters. Avoid chains where one reference points to another five levels deep; the specification recommends shallow relative links. The test is simple: can the agent complete a common case by reading `SKILL.md` once without importing an entire handbook?

Separate judgment from deterministic work

Use prose for context-sensitive decisions and code for operations that must be exact. A research skill may let the agent choose which claims deserve investigation, while a script normalizes URLs and validates the final JSON. A document skill may let the agent adapt narrative emphasis, while an asset provides the approved company template. Scripts should document dependencies, accept explicit inputs, avoid hidden global state, and return actionable errors. This division improves reliability and makes failures diagnosable: you can tell whether routing, judgment, tooling, or data caused the problem instead of blaming one enormous prompt.

Include examples that teach boundaries

Examples should show both what to do and what not to do. Give one normal request, one ambiguous request with the expected clarification or inference, and one nearby request that should stay outside the skill. Show the shape of a good output without hard-coding volatile dates, branch names, or customer facts. If a safety rule matters, demonstrate the safe branch: prepare a deployment and ask for authorization rather than silently deploying. Examples are especially useful for tone, evidence quality, and structured outputs, but they should reinforce the operating contract rather than create a second conflicting contract.

• Positive: 'Run release QA on the staging URL and fix critical bugs.'
• Paraphrase: 'Is this preview ready to ship?'
• Negative: 'Write three headline options,' which does not require the release workflow.

Test SKILL.md like routing code

Validate the format, then evaluate behavior. Run a small prompt suite and record whether the skill activates, what files it reads, what actions it attempts, and whether its conclusion is supported. Add a regression prompt whenever the skill triggers incorrectly or misses a common paraphrase. Test compatibility claims in each supported client because optional fields and tool syntax may vary. Review context use as well as correctness: if every request loads five reference files before inspecting the task, the skill defeats progressive disclosure. Better tests measure the user-visible result and the path taken to get there.

Use this SKILL.md quality checklist

A strong skill has one recognizable purpose, a discoverable description, bounded authority, a short main workflow, and a proportionate verification step. It explains dependencies without embedding credentials. It links only to files that exist, uses scripts for exact work, and states what happens when inputs are missing. It does not claim success from logs when the user receives a visual or deployed artifact. Before release, ask another person to invoke the skill from natural language and watch where the agent hesitates. Rewrite the ambiguous instruction instead of teaching the user a workaround.

• Purpose and triggers are obvious from metadata alone.
• Instructions distinguish inspect, decide, act, verify, and report.
• Risky or external actions have explicit authorization boundaries.
• The common path is concise and optional depth is loaded on demand.