Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

ADR-26044: Skills as Progressive Disclosure Units

title: Skills as Progressive Disclosure Units date: 2026-03-18 tags:

ADR-26044: Skills as Progressive Disclosure Units

Date

2026-03-18

Status

proposed

Context

ADR-26038 established context engineering as the core design principle and stated, in one sentence, that “skills are injected instructions, not separate agents” following the SKILL.md pattern validated by cross-vendor convergence. That sentence is a principle, not a specification. The ecosystem needs a formal definition of the skill unit to:

  1. Enable consistent implementation — without a spec, each agent that wants to load skills would invent its own format, fragmenting the ecosystem.

  2. Budget context accurately — progressive disclosure requires frontmatter fields (token_size, tags, description) that drive selection. These fields need a schema.

  3. Define the skill/subagent boundary — ADR-26038 permits fork-and-join subagents but distinguishes them from skills. The boundary is not yet operationally defined.

  4. Clarify MCP’s role — the emerging standards stack places MCP as the runtime tool connectivity layer and SKILL.md as the capability packaging layer; their interaction needs explicit guidance.

Cross-Vendor Convergence on SKILL.md

The most significant evidence from A-26009: Compass — The Realistic State of Agentic AI 2026 is that the SKILL.md format — YAML frontmatter plus Markdown instructions in a directory with optional scripts and references — was released by Anthropic as an open standard in December 2025, and OpenAI adopted the same format for Codex CLI and ChatGPT. This is the closest the industry has come to a portable, reusable skill format.

The convergence is notable because it is independent: two competing vendors arrived at the same structure from different architectural starting points (Claude Code’s tool-use loop vs. OpenAI’s assistant API). When independent implementations converge, the shared structure is extracting something real.

Skill Marketplaces and Security Risk

Skill marketplaces are materializing at scale: SkillsMP hosts 31,000+ agent skills. But a Snyk study (February 2026, n=3,984) found that 36% of community skills have security flaws — prompt injection, data exfiltration, or unsafe tool invocations embedded in skill instructions. Community skills require an explicit vetting gate before ecosystem adoption.

The Progressive Disclosure Principle

The NVIDIA RULER benchmark found that effective context is only 50-65% of the advertised context window. Loading all available skills into the system prompt at startup is not viable — it consumes the available context before any user task begins. Skills must be loaded on demand.

“Progressive disclosure” — loading only what the current task requires — is the mechanism that makes the skill library scale beyond a handful of capabilities.

Relationship to ADR-26034

ADR-26034 (rejected) proposed the Agentic OS paradigm and introduced the SKILL.md + tools/ + tests/ folder structure. The OS framing was rejected; the folder structure was retained in ADR-26038 as a “validated pattern.” ADR-26044 formalizes exactly what was retained: the skill unit structure, selection mechanism, and boundaries.

Decision

We adopt the progressive disclosure unit as the formal definition of a skill in this ecosystem.

1. Skill Structure

A skill is a directory with a required SKILL.md and two optional subdirectories:

skill_name/
  SKILL.md          # Required: frontmatter + Markdown instructions
  tools/            # Optional: executable scripts invoked by the skill
  tests/            # Optional: golden-file fixtures for skill verification

SKILL.md has two parts:

tools/ contains executable scripts (Python, Bash) that the skill’s instructions reference. tests/ contains golden-file fixtures that verify the skill’s behavior without API calls.

2. Progressive Disclosure Mechanism

Skills are not loaded at agent startup. They are loaded on demand:

  1. The agent maintains a skill registry — a list of skill frontmatter objects (name, description, tags, token_size) loaded at startup. The registry’s total token cost must be under 5% of the working context budget.

  2. When a user task arrives, the agent matches task intent against registry metadata and selects the minimal set of skills needed.

  3. Selected skills are injected into the working context window as additional instructions.

  4. When a skill’s task is complete, its instructions are removed from the active context to reclaim budget.

The frontmatter fields description, tags, and token_size exist specifically to support this selection and budgeting loop. Without these fields, the agent must load and inspect the full skill body to decide relevance — defeating the purpose of progressive disclosure.

3. Skills Are Injected Instructions, Not Subagents

A skill executes within the main agent’s context window and LLM loop. It is not:

This is the boundary established by ADR-26038: skills are injected, subagents are forked. The decision rule is:

MCP tool servers are neither skills nor subagents — they are runtime tool endpoints that any skill or the agent itself may invoke. A skill that depends on an MCP server declares it in its frontmatter mcp_servers field; the agent runtime resolves the server connection before injecting the skill.

4. Security Gate for External Skills

Community skills from marketplaces require explicit review before ecosystem adoption. The review checks for prompt injection vectors, data exfiltration patterns, and unsafe tool invocations. Reviewed skills are committed to the repository’s skills/ directory — they are not fetched at runtime. This eliminates supply-chain risk from dynamic skill loading.

First-party skills authored within the ecosystem are exempt from the external review gate but are still subject to the standard test suite (tests/ fixtures must pass).

Consequences

Positive

Negative / Risks

Alternatives

References

Participants

  1. Vadim Rudakov

  2. Claude Sonnet 4.6 (AI Engineering Advisor)

Adr
ADR-26043: Ecosystem Package Boundary
Adr
ADR-26045: AI-Native Development — Code as Primary Documentation