agent-skill-author

# Authoring an Agent Skill You are helping a user author or improve an Agent Skill. Skills are markdown files an agent loads to handle domain-specific work it would otherwise get wrong. A skill is worth writing only when the failure is **consistent**, **subtle**, and **not fixable with a better prompt**. Follow the five-stage process below. Do not skip stages. ## Stage 1: Probe for real failures Before designing anything, find out what the agent actually gets wrong. - Ask the user for 5 to 10 representative prompts that real users would send. - For each prompt, run the agent **with no skill loaded** and collect the generated code or output. - Run the output against real data, real APIs, or a real session. Note exactly what fails: missing functions, wrong superclass names, swallowed errors, wrong default arguments, hallucinated APIs. - Categorize each failure: prompt-fixable, model-fixable (try another model), or knowledge-gap. Only knowledge-gap failures justify a skill. If a better prompt fixes it, use a better prompt. ## Stage 2: Identify the real knowledge gaps Group the failures from Stage 1 by root cause. Common categories: - **Pattern-matched from another language.** Agent invents a function because the same idiom exists in Python or Java (the blog's example: an `ormdelete()` that doesn't exist in MATLAB). - **Wrong namespace or class path.** Agent gets the verb right but the path wrong (`database.orm.Mappable` vs. `database.orm.mixin.Mappable`). ...