Agent Skills Are Just Folders with a Manifest — Here's the Full Spec and How to Write One
Skills are the packaging format that turns a general-purpose coding agent into a domain specialist without fine-tuning. Knowing the spec means teams can version, share, and compose expert behaviors the same way they manage code — and the growing open-source skill registries lower the cost of adopting battle-tested agent workflows.
A Skill boils down to a folder with a required SKILL.md file that carries metadata — name, description, version — and a Markdown body that injects role definitions, step-by-step instructions, output formats, examples, and error handling into the agent. Optional subdirectories hold executable scripts, reference documents, and template assets. The format is governed by the agentskills.io specification and Anthropic's official guide, with a growing ecosystem of community repositories aggregating thousands of pre-built skills.
Skills install either globally into an agent's own SKILLS directory or scoped to a single project under a `.opencode/skills` (or equivalent) folder. A skill-creator meta-skill from Anthropic can generate new skills from a natural-language prompt, collapsing the authoring loop into a single command.
The design philosophy is progressive disclosure: the metadata layer acts as a lightweight trigger scanned across all skills, the instruction layer swaps in a domain-specific SOP once matched, and the resource layer provides deterministic scripts and reference material for execution. This mirrors how a human expert recalls a mental checklist only when a relevant problem arises, rather than keeping every procedure active at all times.
The skill format is deliberately file-system-native — no registry, no API, no packaging tool required — which makes it trivially versionable in Git and composable across different agent runtimes.
Progressive disclosure is a cost-management strategy disguised as a design pattern: keeping only metadata in context until a skill is triggered avoids blowing out the prompt window with unused expertise.
The instruction layer effectively performs a runtime fine-tune via prompt engineering, swapping the agent's default reasoning chain for a domain-specific SOP without touching model weights.
Community skill registries are growing fast (6,000+ entries on agent-skills.md alone), suggesting that reusable agent behaviors are being commoditized the way npm packages were a decade ago.