Progressive Disclosure for AI Agents: Load the Skill, Not the Entire Playbook

How SKILL.md files help agentic applications, coding harnesses, and assistants like OpenClaw access specialized knowledge only when they need it.

Imagine onboarding an engineer by handing them every runbook, architecture document, deployment procedure, and troubleshooting guide your company has, and asking them to read everything before answering their first question.

That is the design to avoid when building an AI agent.

A better approach is to provide a small directory of available expertise, then let the agent open the relevant instructions when the task calls for them.

This is progressive disclosure: make capabilities discoverable upfront, but reveal their details on demand. Agent Skills apply this through a compact catalog, dynamically loaded instructions, and supporting resources accessed only as needed. (anthropic.com)

The guiding principle is simple:

An agent should know what expertise is available without carrying all of that expertise in its active context.

From a giant prompt to a library of skills

Consider an agent that can review code, investigate incidents, generate reports, and prepare releases.

One design would put every workflow into its initial prompt. Another would give it a catalog:

Available skills:

- code-review: Review changes for correctness and maintainability.
- incident-triage: Investigate service failures using logs and runbooks.
- report-generation: Turn structured data into a formatted report.
- release-preparation: Validate changes and draft release notes.

When the user asks for a code review, the agent loads the code-review instructions. The incident runbook and report templates remain outside its context.

This is the distinction that matters: available does not mean loaded. The Agent Skills integration model separates discovering a capability from bringing its instructions into the conversation. (agentskills.io)

What SKILL.md actually contains

A naming detail first: the conventional filename is SKILL.md, singular and uppercase, not skills.md.

A skill is a directory containing that file, optionally accompanied by scripts, references, and assets. Its entry point combines YAML metadata with Markdown instructions. The standard requires a name and description; the description explains both what the skill does and when to use it. (agentskills.io)

Here is an illustrative skill:

release-preparation/
├── SKILL.md
├── references/
│   ├── changelog-style.md
│   └── compatibility-checks.md
├── scripts/
│   └── collect_changes.py
└── assets/
    └── release-notes-template.md

Its SKILL.md might look like this:

---
name: release-preparation
description: >
  Prepare release notes and a release-readiness checklist.
  Use when the user asks to summarize changes between versions
  or prepare a software release. Not for deploying a release.
---

# Release preparation

## Workflow
1. Confirm the repository and version range.
2. Collect changes using scripts/collect_changes.py.
3. Separate user-facing changes from internal maintenance.
4. Read references/changelog-style.md before drafting notes.
5. If changes affect public APIs, read
   references/compatibility-checks.md.
6. Format the draft using assets/release-notes-template.md.

## Output
Return:
- Draft release notes
- Potential compatibility concerns
- Unresolved questions

Do not publish, tag, or deploy anything.

Notice the conditional instruction: load the compatibility guide if changes affect public APIs.

That is more useful than saying "read every file in this directory before proceeding." The entry point should direct the agent toward the next relevant piece of information, not recreate the original giant prompt.

The three layers of disclosure

The Agent Skills specification describes three levels: metadata, instructions, and resources. (agentskills.io)

Layer	What the agent receives	Purpose
Discovery	Skill name and description	Decide whether a skill is relevant
Activation	Full SKILL.md instructions	Understand the workflow
Execution support	Selected references, assets, or script results	Complete the specific task

The important boundary is what enters model context, not necessarily what the application has read from disk. A runtime can parse or cache skill files ahead of time while withholding their full contents from the model until activation. (agentskills.io)

Scripts add another useful distinction: executing code does not require inserting its source into the prompt. An agent can run a bundled utility and consume its output instead. That output still needs a sensible size limit; replacing a large document with a huge tool response defeats the purpose. (anthropic.com)

How this works in agentic applications

For an application developer, I would frame the architecture as two responsibilities:

1. The model chooses relevant expertise.
2. The runtime controls access and delivers the content.

A customer-support application, for example, might offer skills for troubleshooting, account recovery, and escalation. It should expose only the skills appropriate to the current user, tenant, and environment.

The implementation does not require a local filesystem. Skills can be provisioned through bundled assets, a registry, or an API, then exposed through a dedicated activation tool. (agentskills.io)

Microsoft Agent Framework provides a concrete example. Its documented lifecycle is:

Advertise → Load → Read resources → Run scripts

It exposes operations such as load_skill, read_skill_resource, and run_skill_script, allowing the agent to request deeper material as the task progresses. These are framework-specific interfaces, not universal tool names required by the skill format. (learn.microsoft.com)

For a custom application, an illustrative sequence might be:

User asks a question
    ↓
Agent sees the eligible skill catalog
    ↓
Agent requests load_skill("account-recovery")
    ↓
Runtime checks access and returns instructions
    ↓
Agent requests the relevant recovery reference
    ↓
Agent follows the workflow using authorized tools

Loading the skill should not itself perform the recovery action. Reading a procedure and being authorized to execute it are separate decisions. Microsoft's implementation likewise distinguishes skill loading from script execution and tool approval. (learn.microsoft.com)

How this works in coding harnesses

In a coding harness, skills can package repeatable engineering workflows: reviewing database migrations, debugging failing tests, preparing releases, or implementing a particular API pattern.

Claude Code, for example, normally exposes skill descriptions while loading full instructions when a skill is invoked. Skills can be selected automatically or invoked explicitly with a command such as /skill-name. Supporting files let the main instructions remain small. (code.claude.com)

Consider this hypothetical request:

"Add pagination to the customer endpoint."

A progressively disclosed workflow could be:

Discover api-development
    ↓
Load its SKILL.md
    ↓
Read the pagination conventions
    ↓
Inspect the endpoint and nearby tests
    ↓
Implement and validate the change

The agent does not need the release procedure or database recovery guide.

My suggested division is:

• Standing project instructions: rules that apply broadly.
• Skills: specialized procedures for particular tasks.
• References: detailed information needed within those procedures.
• Tools: the operations the agent can actually perform.

Keep universal constraints out of optional discovery paths. If a rule must apply to every code change, it should not depend on the agent remembering to activate a particular skill.

OpenClaw: the same pattern beyond coding

OpenClaw demonstrates this pattern in another agent environment.

Its system-prompt documentation describes a compact <available_skills> list containing skill names, descriptions, and file locations. The agent is instructed to use its read tool to open the relevant SKILL.md. Eligibility checks determine which skills appear in that catalog. (docs.openclaw.ai)

Conceptually, discovery looks like this:

<available_skills>
  <skill>
    <name>release-preparation</name>
    <description>
      Prepare release notes and a readiness checklist.
    </description>
    <location>
      /skills/release-preparation/SKILL.md
    </location>
  </skill>
</available_skills>

The catalog points to the procedure; it does not contain the entire procedure.

OpenClaw also documents skills from several locations, including bundled, managed, and workspace sources. That makes provenance and precedence important: developers need to know which skill is being selected, not merely that a matching name exists. (docs.openclaw.ai)

The common architecture across these environments is:

Discover → select → load → act.

The mechanisms differ. A framework may expose load_skill; a filesystem-oriented agent may simply read a file.

The description is part of the routing logic

Before activation, the agent generally sees the description, not the detailed instructions. That makes the description an operational interface, not just documentation. The specification explicitly recommends including what the skill does, when it applies, and relevant task keywords. (agentskills.io)

Compare these illustrative descriptions:

description: Helps with databases.

description: >
  Review PostgreSQL schema migrations for locking risks,
  backward compatibility, and rollback readiness.
  Use when reviewing migration files or planning schema changes.

The second gives the agent a basis for choosing.

I would test descriptions with both positive and negative examples:

• "Review this migration before deployment." → should activate.
• "Explain what a database index is." → probably should not.
• "Rename this UI component." → should not.

A skill that never loads is unavailable in practice. A skill that loads for everything is another oversized default prompt.

What progressive disclosure does, and does not, save

Here is a hypothetical calculation:

• 40 skills
• 2,000 tokens of instructions per skill
• 80 tokens per catalog entry
• Two skills needed for the task

Loading every instruction set would require 80,000 tokens.

Loading the catalog plus two skills would require:

40 × 80 + 2 × 2,000 = 7,200 tokens

That excludes the base prompt, conversation, tool definitions, supporting resources, and tool outputs. It illustrates the loading strategy, not a measured performance result.

There are also trade-offs. On-demand access introduces additional retrieval steps, and activated instructions can remain in conversation history. Claude Code explicitly documents that invoked skill content persists across later turns; lazy loading is not automatic unloading. (code.claude.com)

For production systems, I would measure:

• Whether the right skill activates.
• Whether irrelevant skills stay unloaded.
• Total context consumed over the task.
• End-to-end latency.
• Task success and unauthorized-action attempts.

Token savings alone are not enough if the agent consistently chooses the wrong procedure.

Skills are instructions, not a security boundary

A skill can contain scripts, external references, and instructions that influence tool use. Anthropic recommends using trusted sources and auditing unfamiliar skills, including bundled code and network access. OpenClaw similarly warns that third-party skills should be treated as untrusted code. (anthropic.com)

My implementation checklist would therefore include:

• Review and version skills before distribution.
• Restrict resource access to approved locations.
• Sandbox script execution.
• Keep credentials out of skill text.
• Enforce authorization in the runtime.
• Require approval for consequential side effects.
• Log which skill version was loaded and what it executed.

A Markdown instruction saying "ask before deployment" is useful guidance. It is not a substitute for a deployment tool that enforces approval.

The takeaway

Progressive disclosure is a useful way to separate what an agent can access from what it needs to read right now.

SKILL.md provides a practical packaging format, but the architectural decision matters more than the filename:

• Advertise capabilities concisely.
• Load procedures when relevant.
• Fetch supporting details selectively.
• Enforce permissions independently.

Whether you are building an agentic application, extending a coding harness, or configuring OpenClaw, start with this question:

What is the smallest amount of information the agent needs to choose its next step?

Then make the deeper information available when that step requires it.