Skip to main content
ZICQ

Wiki AI Concepts

Agent Skills

AI Concepts
Aliases: SKILL.md Skills Standard ·2026-11-18

Agent Skills

Agent Skills is a modular packaging specification—originated by Anthropic and formalized as the open agentskills.io standard—for equipping AI agents with domain workflows, operational guardrails, reference docs, and helper scripts. Anchored by a SKILL.md file, the format is widely supported across coding agents such as Claude Code, Codex CLI, and Cursor.

Directory Layout and SKILL.md Anatomy

An Agent Skill is a self-contained directory centered on SKILL.md:

my-skill/
├── SKILL.md          # Required: YAML frontmatter (name, description) + Markdown instructions
├── scripts/          # Optional: deterministic Python/Bash helpers
├── references/       # Optional: domain manuals loaded only when needed
└── assets/           # Optional: templates, configs, or static fixtures

SKILL.md has two layers:

  1. YAML Frontmatter: Declares name and description metadata used to match tasks and decide when to trigger the skill.
  2. Markdown Body: Encodes step-by-step instructions, verification checklists, constraints, and usage patterns.

Progressive Disclosure in Context

Stuffing dozens of domain playbooks into a permanent system prompt wastes context window capacity and degrades recall. Agent Skills relies on three-stage progressive disclosure for disciplined context engineering:

  1. Discovery: At startup, the runtime loads only the lightweight name and description metadata of installed skills.
  2. Activation: When a prompt matches a skill description (or the user invokes /skill-name), the agent reads the full SKILL.md body into context.
  3. Execution: During execution, the agent selectively opens files in references/ or runs deterministic utilities in scripts/.

Comparing Agent Skills, MCP, and Prompts

Dimension Agent Skills (SKILL.md) MCP (Model Context Protocol) Static Prompt Templates
Core Purpose How to execute a workflow (procedures, checklists, scripts) How to connect live tools and data (standardized RPC) One-off single-turn framing
Runtime Footprint Plain filesystem directories; no background server Separate stdio or HTTP/SSE server process Raw text snippet
Context Overhead Progressive loading (metadata-only until triggered) Tool schemas loaded for active servers Pasted manually
Synergy Skills often teach an agent how to orchestrate multiple MCP tools Handles credentials, I/O, and execution boundaries Best for isolated tasks

Engineering and Security Practices

  • Write Sharp Trigger Descriptions: Clearly specify both when a skill should activate and when it does not apply so unrelated prompts do not pull unnecessary instructions into context.
  • Offload Determinism to Scripts: Place linting, build, packaging, or parsing steps inside scripts/ rather than asking the model to improvise fragile shell pipelines from scratch.
  • Audit Third-Party Skills: Because skills can bundle executable scripts and high-priority instructions, inspect SKILL.md and scripts/ before installing community packages to guard against prompt injection or unsafe commands.

Further Reading