best practices

How to write a good skill

Good skills are easy to match, safe to follow, and short enough to load without drowning the conversation.

Description first

• State the outcome and the trigger phrases or task types.
• Avoid vague blurbs (“helps with coding”). Prefer “use when merging release notes from CHANGELOG files.”
• Mention negative triggers if useful (“do not use for interactive pair programming”).

Instructions

• Order steps the agent should actually take.
• Say what to read, what to run, and what to ask the user before irreversible actions.
• Put edge cases and stop conditions near the steps that need them.
• Prefer checklists over long essays.

Scope and safety

• One skill, one job. Split unrelated workflows.
• Declare secrets handling: never print keys; use the environment’s vault or prompts.
• Call out network, payment, or delete operations explicitly.
• Keep examples fictional (acme-demo.example, user@example.test).

Maintenance

• Update the description when behavior changes so matching stays accurate.
• Version or note breaking changes in the body.
• Remove dead paths and obsolete flags from helper scripts.