# Write a small SKILL.md with a clear task boundary

Start a skill with one task and a clear expected result. Define when it should apply, which inputs it needs, and what it must not assume. Add scripts or supporting files only when they solve a real part of the workflow.

## An illustrative starter
```text
---
name: draft-review
description: Review a supplied draft for unsupported claims and unclear requests.
---

Ask for the audience, purpose, draft, and confirmed facts.
Identify factual claims and the reader's requested action.
Flag unsupported claims; do not invent evidence.
Suggest edits that preserve meaning and uncertainty.
Return a revised draft plus a list of material changes.
If an important fact is missing, ask a focused question.
```

This is a starting example, not a claim that every host accepts it unchanged. Follow the Agent Skills specification and the host’s current requirements. The directory name and metadata must meet the format constraints.

## Add a useful example
Supply a draft with a known unsupported claim and show the intended handling. For example, “The checklist doubled retention” should be flagged if the only fact supplied is that the checklist was used for twelve accounts. The example teaches the boundary more clearly than another paragraph saying “be accurate.”

## Name the output precisely
A review could return a claim table, a revision, and unresolved questions. If the output is just “a better draft,” the model has too much room to decide what better means. Keep the format small enough that the user can inspect it.

| Output | Purpose |
| --- | --- |
| Claim table | Shows evidence and gaps |
| Revised draft | Gives usable wording |
| Change note | Makes material edits visible |

## Validate and evaluate separately
Check the file format and referenced paths first. Then test behavior with complete, missing, and conflicting inputs in the intended host. A valid YAML header does not establish that the model follows the workflow.

Keep private examples outside the reusable package unless they are redacted and you have permission to share them. Add a license that reflects your actual rights. When updating the skill, describe the behavior change so a user can decide whether to repeat their tests.

---
SkillStall · 2026-10-02
Agent Skills format specification: https://agentskills.io/specification