Anatomy of a skill

A skill is deliberately small at the center. It starts with a directory and a required SKILL.md file. The rest is optional: scripts for repeatable execution, references for deeper documentation, assets for templates or examples, and product-specific metadata when an agent client supports it.

"YAML frontmatter followed by Markdown content." Agent Skills specification, SKILL.md format

The minimal shape

release-readiness/
├── SKILL.md
├── scripts/
│   └── verify-release.sh
├── references/
│   └── release-checklist.md
└── assets/
    └── report-template.md

Only SKILL.md is required by the open format. The directories around it exist when they remove ambiguity. If the instructions are enough, the skill can be one file. If the task includes fragile commands, reusable test data, or a long policy reference, move that material out of the main file and tell the agent exactly when to load it.

Frontmatter is the discovery surface

The name lets humans and agents refer to a skill. The description is more important than it looks because it is what the agent sees before deciding whether the skill is relevant. Good descriptions state the capability and the trigger conditions: what the skill does and when to use it.

---
name: release-readiness
description: Reviews a static website release for build health, generated artifacts, source links, deployment readiness, and final report requirements. Use when preparing or auditing a website launch.
---

# Release readiness

Follow the release checklist, run the project build, inspect generated files, deploy only after build success, and verify the live URL.

This is not generic documentation. It is operational routing. The agent has to decide among many possible skills; a vague description like "helps with websites" forces guesswork and creates false activations.

The body is the working procedure

The Markdown body should contain the information the agent would otherwise miss: project conventions, exact validation loops, hard constraints, source-of-truth files, output format, and edge cases. It should not explain what the model already knows. A skill that spends half its budget defining ordinary concepts is competing with the user's task for no reason.

A good body reads like a compact onboarding guide for one capability. It can include a checklist, but it should not become a giant manual. When the main file starts turning into a reference book, split the reference book out.

Scripts are for fragile or repeatable execution

A script is useful when the workflow has steps that should not be reinvented every run: converting files, validating a schema, querying a known endpoint, checking a release artifact, or producing structured output. The skill should document how to run the script and what success looks like. The script itself should be non-interactive, have helpful errors, and return output the agent can parse.

Scripts are not a requirement. They are a way to lower risk when text instructions would leave too much room for variation.

References are for detail on demand

References are where longer policy, API, style, or domain material belongs. The key is explicit routing. "Read references/api-errors.md if the upstream API returns a non-200 response" is useful. "See references for more" is not, because it leaves the agent to browse a pile of files without a decision rule.

Assets make the skill executable in context

Assets can be templates, sample inputs, screenshots, style guides, schemas, boilerplate files, or other reusable material. They are especially useful for document generation, brand work, design systems, and repeatable reporting. The agent can use the asset rather than approximating it from memory.

Progressive disclosure is the design pattern

Progressive disclosure is the reason skills can scale. At startup, an agent can load only the name and description for many skills. When a task matches, it can load the selected SKILL.md. If the skill points to references, scripts, or assets, the agent can open only the material needed for the current case.

That structure is what lets skills converge across agents. Different products may install, invoke, and sandbox skills differently, but a directory with a concise SKILL.md and clearly routed supporting files is easy for many agent clients to understand.