Write and review agent skill files with quality guidance

Defines what an Agent Skill is - a folder containing a SKILL.md file (YAML frontmatter plus markdown instructions) with optional scripts/, references/, and assets/ subfolders loaded on demand - and explains the open standard behind it (agentskills.io, created by Anthropic and adopted by OpenAI Codex, Cursor, Gemini CLI, Microsoft Agent Framework, Google ADK, and 40+ other agent products, so a skill written once works across all compatible agents). It covers why the abstraction exists: prior alternatives each fail differently (stuffing instructions into the system prompt bloats context at scale, re-pasting per session loses version control and consistency, fine-tuning is slow/expensive/opaque, and MCP servers alone give tools without workflows for using them), whereas skills solve context efficiency, repeatability, composability, and portability at once. The architectural core is progressive disclosure across three loading levels: Discovery (~100 tokens per skill, only name and description always in context, so dozens of skills can be installed with negligible overhead), Activation (under 5,000 tokens, the full SKILL.md body loaded only when a request matches), and Execution (unbounded, referenced files or scripts read only as needed, so bundled content has no practical size limit).

Use it when creating, editing, reviewing, or debugging an agent SKILL.md file, or when you need quality guidance on triggers, examples, limitations, and safety notes. It distinguishes two valid design patterns: capability primitives (a thin wrapper over a deterministic CLI or script, typically 30-80 lines of mostly command examples, used when "the agent can't do X") and process primitives (pure prompt engineering encoding a methodology like TDD or a review loop, no scripts needed, used when "the agent's output quality or process is bad") - a mature setup uses both. It also names explicit anti-patterns: don't re-teach what the model already knows, don't bundle human-facing docs (README, CHANGELOG, INSTALLATION_GUIDE) inside a skill folder, don't write vague descriptions, don't paste library source instead of installing a dependency, don't build monolithic mega-skills that combine design, planning, implementation, testing, and deployment, don't assume the agent will infer an unstated step, don't write style-only variants (those belong in user preferences), don't ship happy-path-only skills that ignore failure modes, don't include time-sensitive information that rots, and don't use absolute paths.

A skill's SKILL.md follows a set anatomy:

---
name: skill-name
description: What this skill does AND when to use it. Include trigger phrases the user will say.
---

### Skill Name

### Quick start
[Minimal working example]

### Workflow
[Step-by-step procedure with checklists]

### Output format
[What the user/agent should expect back]

### Advanced
[Link to references/ for rarely-needed detail]

Frontmatter name must be lowercase, hyphens only, 1-64 characters, and exactly match the parent folder name; avoid < and > (they can inject into the system prompt); invalid YAML silently prevents loading. An optional disable-model-invocation: true field stops auto-loading so the skill fires only manually - now a standard Agent Skills spec field that works across spec-compliant clients, though some clients still inject the description into context even with it set. Before publishing, the ship checklist expects: frontmatter name matching the folder, a description with what+when+differentiator and likely trigger phrases, no human-facing docs or time-sensitive information inside the folder, relative paths only, a documented validation loop and output format, testing against both weak and strong models for correct triggering and execution, and version control. That testing step has its own concrete form: a small eval suite of representative prompts that should and shouldn't trigger the skill, each paired with its expected output, rather than a one-off manual check.

The description is the routing contract - the only thing the agent sees before deciding to load a skill - so it should state what the skill does, when to use it, and a differentiator versus related skills, using the pattern "X via Y. Use for [situations]. [Differentiator: no Z required / faster than W / handles edge case V]."; never summarize the workflow itself in the description, since the agent tends to follow that summary instead of loading the body. Match instruction rigidity to task fragility - loose natural-language heuristics when many approaches are valid, pseudocode or templates when a preferred pattern exists but variation is acceptable, and exact scripts with strict step lists for fragile or consistency-critical workflows like migrations. Build an explicit verify-fix-re-verify validation loop into every skill (visual QA for document skills, tests-pass-and-zero-type-errors for code skills, schema validation for data skills), keep referenced files one level deep rather than chaining SKILL.md through multiple nested files, and use persistent artifacts (CONTEXT.md, ADRs, decision logs) that future sessions can read to fight the "agents have no memory" problem. When debugging, a routing failure is a description problem and an execution failure is a body problem; skills snapshot at session start, so edits require a restart to take effect. Skills compose at runtime - design for one skill per concern, document the interface when one skill's output feeds another, and use a shared repo-level config substrate (AGENTS.md, CONTEXT.md, settings.json) to coordinate multiple skills without explicit handoffs. Before installing any third-party skill, read every file in the folder, audit scripts/ for outbound network calls or out-of-scope file access, check references for prompt injection, verify the name isn't typosquatting a popular skill, run it sandboxed first, and pin to a specific version rather than latest.

Someone about to write a new skill from a real, observed gap in an agent's behavior, or auditing an existing one that either never fires when it should or produces the wrong output when it does - the two failure modes this reference maps directly back to a description problem versus a body problem, respectively, rather than leaving the diagnosis to guesswork.