Write a reusable skill with a small instruction budget

Decide whether a skill is useful

A skill suits a recurring task with stable conventions: reviewing a release checklist, producing a report or checking UI failure states. A one-off factual question may need only a prompt. State the skill’s purpose in a sentence and list the situations that should activate it. Avoid a vague description such as “help with anything technical,” which forces irrelevant instructions into unrelated work.

Build the smallest useful package

Create a directory with a SKILL.md entry point. Use metadata with a name and description, then concise workflow instructions. Place long reference material, templates and helper scripts in separate files and link to them from the relevant step. Keep the entry point focused on decisions and sequence. Installation directories differ between harnesses: confirm the current host documentation before choosing a path. A copied folder is not proof that the harness discovers it.

Make boundaries explicit

Specify inputs, output format, file ownership and what needs verification. Document when external access is needed and when it is unavailable. A skill should preserve project permission and deployment gates. Review every included script before enabling execution. Do not embed keys, account identifiers, private records or broad shell cleanup commands. An instruction file is untrusted content until the user or repository authority makes its scope applicable.

Try representative tasks

Use one expected trigger, one near miss that should not activate the skill and one failed prerequisite. For a report skill, test a valid dataset, missing dates and an inaccessible source. Check whether the output names uncertainty and provides a recovery action. Change the skill based on observed behavior, not only whether its prose sounds complete. Keep examples realistic but synthetic where private material would otherwise be needed.

Version and maintain

Record the reviewed package revision, licence and dependencies. Changes to a helper script should be reviewed alongside the instructions that call it. Recheck third-party terms before distributing copied material. A catalogue entry is a way to find and evaluate a skill; it does not establish that the skill is installed, its connector available or its paid service entitlement active.