write-a-skilllisted

# write-a-skill A good SKILL.md does one thing well, triggers on the right moment, and stays scoped to what it actually knows. Most skill problems come from: vague trigger descriptions, scope creep, and missing the why. ## The minimum viable skill ```markdown --- name: my-skill description: "One sentence. What does this skill do and WHEN should the AI invoke it? Be specific." --- # my-skill Instructions for the AI go here. ``` That's it. Name, description, body. The description is the most important field — it's how the runtime decides whether to load this skill at all. ## Frontmatter reference ```yaml --- name: my-skill # Required. Slug-format (lowercase, hyphens). description: "..." # Required. One sentence, specific trigger condition. # Bad: "Helps with code." # Good: "Use when reviewing TypeScript PRs for type safety issues." user-invocable: true # Optional. Adds a /my-skill slash command. allowed-tools: Bash(git *) # Optional. Restricts which tools the skill can use. # Omit if the skill only generates text. --- ``` ## Writing the description field The description does two jobs: it tells the runtime **when to load the skill**, and it tells the user **what the skill does**. Bad descriptions (too vague — the runtime loads this for everything): - `"Helps with tasks."` - `"Useful for developers."` - `"Contex