skills-best-practices

name skills-best-practices description Use when creating, extracting, reviewing, or refactoring agent skills. Covers self-contained skill packaging, SKILL.md structure, trigger descriptions, progressive disclosure, gotchas, defaults, bundled scripts, eval design, and with-skill vs baseline iteration. Use this whenever the user asks to turn docs or a workflow into a skill, improve a SKILL.md, audit skill quality, or make a skill pack more self-contained. Skills Best Practices Use this skill when authoring or upgrading agent skills. The target is not a pretty SKILL.md . The target is a skill that: captures real task knowledge instead of generic LLM prose stays self-contained and portable triggers on the right user intents gives a clear default path with explicit boundaries can be tested against realistic prompts Default workflow Capture real source material first. Define the skill boundary and adjacent skills. Package the skill so everything it needs lives inside the skill directory. Write a strong description that says both what the skill does and when to use it. Keep SKILL.md lean; move detail into references/ , scripts/ , and assets/ . Add defaults, gotchas, validation steps, and output expectations. Create a small eval set, compare with-skill vs baseline, and iterate. Non-negotiables Do not synthesize the skill from generic best-practices alone. Mine real runs, docs, fixes, traces, specs, and corrections. Keep the package self-contained. If the skill needs guidance, templates, schemas, or helper scripts, vendor or rewrite them inside this skill instead of pointing at repo-external docs. Use relative paths from the skill root for bundled files. Keep SKILL.md focused on the workflow the agent needs on nearly every invocation. Put trigger guidance in the frontmatter description , not hidden in the body. Prefer one clear default path over a menu of equal options. Add verification steps for anything easy to fake, skip, or get subtly wrong. Read only what you need references/authoring-guide.md — core drafting and refactoring guidance references/spec-quick-reference.md — format, frontmatter, layout, and path rules references/evals-and-iterations.md — output-quality eval loop, assertions, grading, and iteration references/description-optimization.md — trigger evals and description tuning references/scripts.md — bundling helper scripts and designing script interfaces references/update-upstream-docs.md — refreshing bundled upstream Agent Skills docs references/upstream/agentskills/ — vendored public Agent Skills docs; read specific files only when the distilled local references are insufficient assets/skill-template.md — starter skeleton for a new skill assets/evals-template.json — starter output-quality eval file assets/trigger-evals-template.json — starter trigger eval file Self-contained packaging rule If you are extracting a skill from repo docs, conversations, or a previous skill, copy or rewrite the necessary knowledge into this skill's own files. Do not leave the finished skill dependent on: repo-specific docs outside the skill directory absolute paths to authoring references hidden tribal knowledge that only existed in the extraction session upstream docs that are only present in the source repository but missing from the deployed skill package The finished skill may still operate on user files or project files. The rule is that the skill's instructions and bundled resources should live inside the skill. Authoring loop 1. Capture intent from real material Extract from real successful work: steps that actually worked corrections made during the run environment quirks and gotchas input/output formats validation steps reusable helper commands or scripts Prefer source material in this order: successful task transcripts project docs, runbooks, specs, schemas bug fixes, reviews, and incident notes existing skill files that already work generic guidance only as a final shaping pass 2. Define the boundary A good skill is one coherent unit of work. Ask: what job should this skill own end to end? what nearby jobs should stay out of scope? what should trigger this skill instead of a neighboring one? what sub-variants belong in references/ instead of the main body? 3. Build the package Use this layout: skills-best-practices/ ├── SKILL.md ├── references/ ├── scripts/ └── assets/ Put content where it belongs: SKILL.md — default workflow, boundaries, core gotchas, output expectations references/ — detailed docs read only when needed scripts/ — deterministic or repeated logic assets/ — templates, fixtures, examples 4. Write the description correctly The description is the trigger surface. It must say: what the skill does when to use it user-intent phrasing, not internal implementation wording near-obvious trigger cases, even if the user never names the domain directly Be slightly pushy. Under-triggering is usually worse than a carefully scoped description that is explicit. 5. Keep the body lean Use progressive disclosure. Keep SKILL.md limited to what the model needs on almost every run. Move long explanations, variants, API tables, and edge-case catalogs into referenced files. When pointing to a reference, say when to read it. Good: read references/description-optimization.md when tuning trigger coverage read references/scripts.md before bundling helper scripts Bad: see references/ for more 6. Prefer defaults over menus Choose a default tool or path. Only mention alternatives as fallbacks, and say when to switch. 7. Add gotchas and verification High-value skill content is usually: naming mismatches hidden filters surprising API semantics environment or auth quirks dangerous paths that require a validation loop For multi-step or destructive work, require: a checklist a plan-validate-execute flow or a concrete verification step before finishing Final review checklist Before calling the skill done, verify all of this: directory name matches name description says what + when, not just what SKILL.md is the shortest version that still preserves the default workflow detailed or variant-specific material moved to references/ repeated deterministic logic moved to scripts/ output templates or fixtures live in assets/ major gotchas are explicit default path and fallback branches are clear validation or verification steps exist where needed at least 2-3 realistic eval prompts exist for output quality a separate trigger eval set exists if description quality matters Exit standard A good result is a skill package another agent can pick up cold, without needing the original repo docs or the original conversation, and still do the job correctly.