Agent Skills Architecture: Diagramming the SKILL.md Pattern (2026)

An agent skill is a packaged, on-disk capability — instructions, reference files, and optional scripts — that an AI agent discovers and loads only when it is relevant to the task at hand. The pattern (formalized around the SKILL.md file format) solves a real scaling problem: as agents gain access to more and more capabilities, stuffing every instruction set into the system prompt burns context window and degrades performance. Skills instead sit on disk, get indexed by name and description, and load their full content into context only when the agent decides it needs them.

This is architecturally distinct from both MCP tools and subagents, and diagrams that conflate the three tend to confuse rather than clarify. This guide covers how to diagram a skills-based agent system correctly.

The SKILL.md format

A skill is a directory containing a SKILL.md file with YAML frontmatter (name, description, and metadata used for discovery) followed by markdown instructions. Skills can also bundle supporting files — reference documents, example templates, or executable scripts the agent can run as part of following the skill's instructions. In your diagram, represent a skill as a self-contained package with three layers: the frontmatter (always loaded, used for matching), the instruction body (loaded on activation), and any bundled resources (loaded lazily, only when the instructions reference them).

Progressive disclosure: the core architectural idea

Progressive disclosure is the mechanism that makes skills scale to hundreds of installed capabilities without exhausting the context window. It works in three tiers:

• Tier 1 — metadata index: At session start, only each skill's name and one-line description are loaded into context — a lightweight catalog, typically a few dozen tokens per skill even with hundreds installed.
• Tier 2 — instruction body: When the agent judges a skill relevant to the current task, it reads the full SKILL.md body into context — the detailed how-to for that specific capability.
• Tier 3 — bundled resources: If the instructions reference a template file, a reference doc, or a script, the agent reads or executes that file only at the point it's needed, not upfront.

A skills architecture diagram should show this as a funnel: a wide, cheap metadata layer at the top, narrowing to expensive, detailed content loaded only on demand. This is the single most important concept to get across in the diagram — it's the mechanism that justifies the whole pattern.

Skill discovery, installation, and registries

Skills are typically distributed through a package-manager-like workflow — a registry that hosts skill definitions, a CLI that installs a skill into a local skills directory (analogous to npm install but for agent capabilities), and a resolver that the agent runtime uses to enumerate installed skills at session start. In your diagram, show the registry as an external system, the install step as a one-time or CI-triggered action that populates a local skills directory, and the runtime's discovery step as reading that directory fresh at every session start — skills are not recompiled into the agent, they're read from disk each time.

Skills vs. MCP tools vs. subagents

These three extension mechanisms are frequently confused in architecture diagrams because they all "add a capability" to an agent — but they operate at different layers and solve different problems.

In practice, a single system uses all three together: a skill might instruct the agent on how to perform a task, that task might call an MCP tool to fetch live data, and a complex sub-task within it might be delegated to a subagent. Your diagram should keep these as three visually distinct node types — instructions loaded in-process, calls to an external server, and delegation to a separate agent instance.

Prompt templates for agent skills diagrams

Progressive disclosure loading flow

Skill registry and CI-based installation

Skills, MCP tools, and a subagent working together

What a good agent skills diagram must show

• The progressive disclosure funnel: metadata index → instruction body → bundled resources, each stage more expensive and more selectively loaded than the last.
• The discovery boundary: where skills live on disk and when the runtime re-scans them — skills are not baked into the agent, they're read fresh.
• Skill vs. tool vs. subagent as distinct node types: conflating them is the most common diagramming mistake in this space.
• Trust boundary on installation: if skills come from an external registry, show the approval or vetting step before they land in the runtime's skills directory — skills can include executable scripts, so unreviewed installation is a real supply-chain risk.

Frequently asked questions about agent skills architecture

What is a SKILL.md file?

A SKILL.md file is a markdown file with YAML frontmatter that defines a packaged capability for an AI agent: a name and description used for discovery, and instructions the agent follows once the skill is activated. It can live alongside bundled reference files or scripts that the instructions point to. It is the on-disk unit that an agent runtime indexes, loads, and executes against.

How is a skill different from a system prompt?

A system prompt is loaded in full on every session regardless of relevance, which doesn't scale past a handful of instruction sets. A skill is loaded conditionally — only its short description is always present, and the full instructions load only when the agent determines the skill is relevant to the current task. This is what lets a single agent have access to hundreds of specialized capabilities without a proportional context cost.

Do skills replace MCP servers?

No — they solve different problems and are typically used together. MCP servers give an agent the ability to call out to external systems (databases, APIs, other services) over a network protocol. Skills give an agent instructions and reference material that live in the same process and load into its own context. A skill's instructions frequently direct the agent to use a specific MCP tool as part of following the procedure.

Related guides: MCP architecture diagrams, multi-agent orchestration patterns, AI agent memory architecture, and context engineering diagrams.