How to write better agent skills

A useful skill has a clear job. It should tell the agent what done means, what evidence to collect, and where to report whether the run helped.

Good skills read like working procedure, not brand copy. Prefer concrete checks, command paths, fallback behavior, and stop rules.

• Name the exact files, routes, or APIs the agent should inspect first.
• Describe the smallest acceptable proof before the agent reports completion.
• Call out what is intentionally out of scope so the agent does not expand the task.

A skill gets better when you compare what it promised against what happened. Review negative and neutral feedback first, then edit the skill around repeated failure modes.