Name a Skill and describe when to use it

The examples and outputs below are independently authored teaching materials, not measured model results.

Use case

You are authoring a PR review Skill. Its agent host supports YAML metadata at the start of SKILL.md, and its discovery directory is configured. A vague name and description make it difficult to decide whether this instruction file fits the current request.

Check the host’s supported location, required fields and naming rules first. The directory and name below are teaching values; use the host’s actual installation requirements.

Mechanism

1. Create SKILL.md inside the Skill directory. Put YAML metadata first, between two --- lines.
2. Give name a recognizable identity. Make description identify the user’s task, activation conditions and a nearby request that should be treated differently.
3. Put the actual review procedure after the metadata. Metadata supports discovery and selection; the body explains how to work once selected.
4. Check parsing, then try a review request and an implementation request in a compatible host. If the file is not discovered, check its installation location before repeatedly changing its description.

Bad example

Both versions review the same PR diff and have valid metadata and the same body. This is the complete bad file:

---
name: helper
description: Help with code-related things.
---

Read the user's PR diff. Report correctness problems that can be located by file and line, and explain their triggering conditions. List missing information when needed; do not edit code.

“Code-related things” could mean review or feature implementation. A precise body does not make this metadata explain when to select it.

Good example

Replace the metadata in that same file and retain the body:

---
name: pr-review
description: Review locatable correctness problems when the user requests a PR, code-diff or pending-change review. Use for review requests; do not select this Skill merely because a feature implementation request involves code.
---

Read the user's PR diff. Report correctness problems that can be located by file and line, and explain their triggering conditions. List missing information when needed; do not edit code.

Replace pr-review with a name accepted by your host, and replace the task and activation conditions with your Skill’s responsibility. Keep necessary execution steps in the body rather than packing them all into the description.

The illustrative deliverable is pr-review/SKILL.md. Parsing yields name=pr-review and the stated description, with the review procedure retained as its body.

Why the change matters

The revision replaces a broad promise with a defined review task, recognizable triggers and a distinction from implementation. It gives the agent information to compare during selection while the body continues to define the work. This explains a mechanism; it does not establish a measured improvement in activation accuracy.

Observable expectation

Use a host-approved parser to check that metadata comes first, the two --- lines match, and name and description are readable. Fix missing fields or syntax errors first.

Then request “review this PR diff” and “implement an export button” separately. Inspect the host’s Skill-selection record: the former should be able to select this Skill; the latter should not select it solely because it involves code. If selection records are unavailable, record that limitation rather than treating review-like output as activation evidence.

Limits

The host must support this metadata format and discovery mechanism. Parsing is not a runtime activation test. A description cannot enforce tool permissions or authorization. Custom YAML fields have runtime meaning only when the host explicitly supports them.