Anatomy of a Skill
Relevant source files
The following files were used as context for generating this wiki page:
Skills are modular knowledge packages designed to transform general-purpose AI agents into specialized experts. They provide procedural knowledge, domain-specific context, and bundled resources that allow agents to execute complex, multi-step workflows with high precision. By encapsulating expertise into a standardized format, skills reduce context consumption while ensuring consistent output across different AI platforms such as GitHub Copilot CLI, Claude Code, and Codex.
Sources: bundled-skills/skill-creator-ms/SKILL.md:13-18, bundled-skills/skill-creator/SKILL.md:120-123
Structural Composition
A skill is defined by a specific directory and file hierarchy. Every skill must reside in a kebab-case directory that matches its internal name field. The core of any skill is the SKILL.md file, which contains the logic, metadata, and instructions for the agent.
The following table summarizes the mandatory and optional components of a skill's directory structure:
| Component | Requirement | Purpose |
|---|---|---|
SKILL.md | Required | Main skill definition, triggers, and instructions. |
references/ | Optional | Supporting documentation and detailed guides. |
scripts/ | Optional | Executable code and deterministic utilities. |
assets/ | Optional | Output templates, images, or boilerplate resources. |
examples/ | Optional | Code samples and usage demonstrations. |
Sources: bundled-skills/writing-skills/references/standards/README.md:9-15, bundled-skills/skill-creator-ms/SKILL.md:57-73, bundled-skills/skill-writer/references/authoring-path.md:12-16
The SKILL.md Architecture
The SKILL.md file is structured into two primary parts: the YAML frontmatter (metadata) and the Markdown body (instructions). The frontmatter is always loaded into the agent's context for discovery, whereas the body is loaded only when the skill is triggered.
The diagram shows the division between discovery metadata and implementation instructions, optimized for context efficiency.
Sources: bundled-skills/skill-creator-ms/SKILL.md:46-52, bundled-skills/writing-skills/references/standards/README.md:52-59
Metadata and Discovery
Discovery is driven by the description and triggers fields within the YAML frontmatter. To maintain efficiency, the SKILL.md should generally be kept under 500 lines, with excessive detail moved to the references/ directory.
Mandatory Metadata Fields
- name: Must be kebab-case and match the directory name exactly.
- description: Must start with "Use when..." and focus strictly on trigger conditions rather than summarizing the workflow.
- metadata.triggers: A comma-separated list of keywords, symptoms, or error messages.
Sources: bundled-skills/writing-skills/references/standards/README.md:17-23, bundled-skills/writing-skills/references/standards/README.md:41-45, bundled-skills/skill-creator-ms/SKILL.md:51-52
Skill Workflow and Execution
When an agent interacts with a skill, it follows a lifecycle from discovery to validation. The skill creation process itself is automated through specialized meta-skills that handle brainstorming, template application, and installation.
Skill Creation Lifecycle
This flowchart illustrates the stages of skill development from initial planning to deployment in the local or global skill directory.
Sources: bundled-skills/skill-creator/SKILL.md:94-118, bundled-skills/skill-creator-ms/SKILL.md:143-150
Progressive Disclosure Pattern
To manage cognitive load and context window limits, skills utilize a three-level disclosure pattern:
- Metadata (~100 words): Persistent in context for discovery.
- SKILL.md Body (<5,000 words): Loaded only upon trigger.
- References (Unlimited): Accessed via links only as needed for deep-dive tasks.
Sources: bundled-skills/skill-creator-ms/SKILL.md:46-54, bundled-skills/skill-creator/SKILL.md:278-283
Implementation Standards
Technical accuracy is enforced through mandatory requirements for writing style and documentation depth.
Documentation Requirements
Technical wiki pages and skill documentation must adhere to the following non-negotiable standards:
- Trace Actual Code Paths: Instructions must be based on implementation, not file names.
- Evidence-Based Depth: Every claim requires a citation (file path + line number).
- Mermaid Diagrams: Minimum of 2 per page to visualize architectures or flows.
- Imperative Voice: Instructions should use direct, actionable language.
Sources: bundled-skills/wiki-page-writer/SKILL.md:21-30, bundled-skills/wiki-page-writer/SKILL.md:55-58, bundled-skills/skill-writer/references/authoring-path.md:8-10
Technical Constraints Table
| Constraint | Rule | Source |
|---|---|---|
| File Name | Must be SKILL.md (all caps) | Standards:19 |
| Word Count | Ideal: 1,500-2,000; Max: 5,000 | Skill-Creator:281 |
| Writing Style | Third-person, imperative voice | Skill-Creator:285 |
| Descriptions | Under 500 characters | Standards:50 |
| Colors (Mermaid) | Must use specific dark-mode hex codes | Wiki-Page-Writer:66-70 |
Sources: bundled-skills/writing-skills/references/standards/README.md:19, 50, bundled-skills/skill-creator/SKILL.md:281-285, bundled-skills/wiki-page-writer/SKILL.md:66-70
Summary
The anatomy of a skill is a structured framework designed for modularity and efficiency. By separating metadata from instructions and utilizing a hierarchical directory structure, skills provide agents with on-demand expertise without overwhelming the context window. The combination of mandatory SKILL.md files, optional supporting references, and strict documentation standards ensures that skills remain accurate, discoverable, and highly effective for complex software engineering tasks.