AI Agent Skills: Procedural Memory via Markdown
Skills add procedural knowledge to agents through skill.md files with YAML frontmatter for name/description triggers, markdown instructions, and optional scripts/assets, loaded via 3-tier progressive disclosure to avoid token limits.
Skill Structure Encodes Repeatable Workflows
AI agents excel at reasoning and facts (e.g., Kubernetes architecture or unladen swallow airspeed) but lack procedural knowledge for multi-step tasks like a 47-step compliant financial report. Skills solve this with a simple folder containing a skill.md file. Start with YAML frontmatter: mandatory name (e.g., "PDF Builder") and description as the trigger condition (e.g., "use when user asks to extract a PDF"). Optional fields include author and version. Below frontmatter, plain markdown provides step-by-step instructions, rules, input/output examples—whatever the agent needs to execute the task.
Optional subfolders enhance: scripts for executable JavaScript/Python/Bash; references for extra docs loaded on demand; assets for templates/data files. This format teaches agents precise workflows without exhaustive prompting or guesswork each time.
Progressive Disclosure Scales to Hundreds of Skills
Loading full details for hundreds of skills would exhaust LLM context windows at startup. Instead, use 3-tier progressive disclosure:
- Tier 1 (Startup): Load only name/description metadata—a few tokens per skill, like a table of contents. Handles 100+ skills without overflow.
- Tier 2 (Task Match): LLM reasoning matches user request to description trigger, then loads full
skill.mdbody for instructions. - Tier 3 (Execution Need): Pull scripts/references/assets only when required.
Result: Agents start lightweight, expand context surgically, and apply skills via their own judgment—making crisp descriptions critical for accurate triggering.
Skills Complement Tools, Facts, and Tuning for Full Knowledge
Skills target procedural memory ("how/when/in what order"), distinct from other methods:
| Method | Knowledge Type | Pros | Cons |
|---|---|---|---|
| MCP (Model Context Protocol) | Tool access (APIs/services) | Reaches external capabilities | No guidance on when/how to use |
| RAG (Retrieval-Augmented Generation) | Factual (knowledge base chunks) | Runtime lookups | No workflows/processes |
| Fine-tuning | Baked into weights | Permanent | Expensive; redo on model changes |
Skills integrate with these—MCP for invocation, skills for judgment. They're version-controlled files, portable across platforms. Mirrors human cognition: semantic (facts → RAG), episodic (experiences → conversation logs), procedural (skills → skill.md).
Open Standard Enables Portability but Demands Audits
The skill.md spec at agentskills.io is Apache 2.0-licensed, adopted by Claude Code, OpenAI Codex, and others—build once, run anywhere. Power comes from scripts accessing files/env vars/API keys, but audits reveal risks in public skills: prompt injection, tool poisoning, malware. Treat like software dependencies: review code before local execution to ensure trust.