Building Your First Agent Skill: From Messy Notes to Structured Meeting Summaries
Agent Skills are the packaging format that turns one-shot prompts into reusable, discoverable workflows. Getting the frontmatter description right determines whether an agent ever finds your skill, and structuring instructions for progressive disclosure keeps context windows lean while still carrying full documentation and templates.
Agent Skills are built around a single SKILL.md file with YAML frontmatter and executable Markdown instructions. The frontmatter's description field is the routing mechanism: it tells the agent when to trigger the skill by matching user intent, not just keywords. A well-written description states what the skill does, when to use it, and what capabilities it includes, using language real users would type.
The instruction body must be specific and ordered by priority. Critical checks go at the top, not buried at the bottom. Supporting files in references/, scripts/, and assets/ directories stay out of context until the workflow explicitly calls for them, keeping the skill lightweight despite carrying templates, style guides, or validation scripts.
Success criteria are defined before writing any code, split into quantitative metrics (trigger accuracy across 10+ requests) and qualitative checks (no fabricated information, every action item has an owner). The skill is placed in an agent-specific directory like .claude/skills/ or .codex/skills/, with ~/.agents/skills/ serving as a shared location for multi-agent setups.
Progressive disclosure means a skill with dozens of reference files can still be lightweight because only SKILL.md enters context initially; the rest is fetched on demand.
The description field functions as a routing key, not documentation. Its quality directly determines whether the skill triggers silently or requires the user to name it explicitly.
Explicit file references in instructions are a reliability mechanism: the agent has no reason to read a file unless the workflow tells it to, which prevents context pollution but demands disciplined authoring.
Success criteria written before implementation serve as a contract for testing. Without them, a skill that 'seems to work' may fail silently on edge cases or unrelated requests.