Claude Code Skills Deep Dive (2): From Description to Full Instructions

TL;DR: A Skill does not save context simply because its files live on disk. It does so through three separate loading decisions: metadata makes every available Skill discoverable; selection loads the full SKILL.md; and the actual task determines whether to read references or run scripts. Each layer must tell the agent when to move to the next. Otherwise, content loads too early—or a useful capability is never invoked.

In Part 1: From a Markdown File to a Portable Folder, we separated a Skill into its entry point, references, scripts, and assets. Splitting the files, however, does not automatically save a single token.

The real question is: Which content enters Claude's view, and when?

What if every Skill were read at startup?

Imagine a team with 40 installed Skills: release checks, API design rules, incident investigations, database migrations, frontend accessibility reviews, PDF and spreadsheet processing, and procedures for various internal systems.

If Claude read all 40 SKILL.md files and every reference at the beginning of each session, even a small button change would carry release procedures, a database manual, and an incident runbook.

That creates two problems:

1. Context cost: Material unrelated to the current task occupies the context window in advance.
2. Attention cost: With many procedures present at once, it becomes harder to identify the one that applies now.

The opposite extreme would be to tell Claude nothing about installed Skills until the user types the exact /skill-name. That saves context, but Claude cannot proactively choose a capability it does not know exists.

Agent Skills takes the middle route: provide a compact catalog first, then expand relevant entries in stages.

Three layers, three decisions—not three directories

The Agent Skills overview describes progressive disclosure in three stages:

Level 1 · Metadata
  name + description
  discovery information for available Skills
          ↓ Does this Skill match the task?

Level 2 · Instructions
  full SKILL.md body
  operating guidance loaded after activation
          ↓ Does the current step need more material?

Level 3 · Resources and code
  references / scripts / assets
  read, run, or use as needed

These are not three mandatory directory names. They are three choices at different levels of detail:

1. Select a relevant Skill from the available capabilities.
2. Load its core method of working.
3. Select the materials needed for this particular branch of the work.

Each move downward provides more information and usually costs more context. The layer above must therefore offer enough clues to justify the next move.

Layer 1: description is a router, not a blurb

Descriptions are often written like product marketing:

description: Helps you ship better releases

A teammate might infer what that means from the Skill's name and the team's history. Claude, choosing among dozens of capabilities, needs stronger matching signals. “Better” says nothing about the work, and “releases” does not say which requests should trigger the Skill.

An effective description answers at least two questions: What does this Skill do, and when should it be used? The Agent Skills specification explicitly calls for both. For example:

description: Checks whether a code version is ready to release. Use when the user is preparing a release, requests a pre-release check, or asks about release risk.

This does not cram the workflow into metadata. It does provide a task and a triggering context. When the user asks, “Can we ship this version?”, that description gives Claude a reason to route the request to release-check and load the full instructions.

The goal is therefore not to summarize the entire file. It is to route the right request to the right capability.

Two failure modes for descriptions

Too narrow:

description: Use when the user types “run release-check”

Only near-exact wording will match, so automatic discovery adds little value.

Too broad:

description: Use for anything related to code quality

Almost any coding task could activate it. An occasional capability becomes constant noise.

A good description is not a pile of keywords. It draws a boundary between recall and precision: catch relevant requests without absorbing adjacent, different tasks.

Metadata is cheap, not free

Progressive disclosure is sometimes reduced to “no invocation, no cost.” A more accurate statement is:

An unused Skill incurs its discovery cost, not the cost of its full instructions and supporting resources.

Claude needs the names and descriptions of candidate Skills to select one proactively. As the number of Skills and the length of their descriptions grow, the catalog itself grows.

That changes how metadata should be written:

• Put the most important use case first.
• Do not explain the Skill's history in its description.
• Do not copy the full procedure into metadata.
• Avoid several Skills with nearly identical, vague descriptions.
• Use stable task language rather than slogans only the author understands.

Metadata is a persistent indexing tax. It is small per Skill, but at scale it becomes an architectural concern.

Layer 2: SKILL.md is the activated control plane

Once the user or Claude selects a Skill, its full SKILL.md body enters the work. It no longer needs to attract invocation; it needs to guide execution.

The core instructions should cover:

1. The Skill's objective and completion criteria.
2. Non-negotiable constraints.
3. The main workflow and decision points.
4. When to read each reference.
5. When to run each script.
6. The expected output and how to verify it.

For example:

## Workflow

1. Check the workspace for unexpected changes.
2. Run the tests and build required by the project.
3. Read the version file and changelog.
4. If the version format is ambiguous, consult `references/version-policy.md`.
5. Summarize blockers and non-blocking risks.
6. Wait for user confirmation; do not publish directly.

The aim is not maximum detail. It is a stable decision framework. Expanding every edge case in the main body makes every invocation pay for rare branches; stating only a vague objective leaves Claude to improvise the process.

Think of SKILL.md as a control plane: objective, main path, decision points, resource navigation, and verification. It need not be an exhaustive manual.

Activation costs can outlast the current step

An ordinary prompt often serves a single user message. Once a Skill's instructions are loaded, they may continue to influence later turns in the same task.

So each paragraph of the body should be evaluated as more than a one-time reading cost. If the Skill remains in the current conversation, lengthy background, repeated examples, and unrelated explanations continue to occupy context.

The body and the description have opposite optimization goals:

If the same paragraph appears in all three layers, their boundaries probably need another pass.

Layer 3: supporting resources need a second router

After activating a release-check Skill, Claude knows the task. It still might not need the entire version policy:

• The version clearly matches the existing format → no need to read it.
• A prerelease marker or unusual branch appears → read it.
• Only a report is needed → use a template.
• Mechanical validation is needed → run a script.

This is a second routing decision inside the Skill:

SKILL.md decision point
  ├─ Ambiguous format → references/version-policy.md
  ├─ Mechanical validation → scripts/validate-version.sh
  └─ Delivery report → assets/release-report.md

References are not valuable because they can hold unlimited text. They are valuable because they defer large bodies of information until the correct branch. If the entry point merely says “see references for more,” Claude still cannot tell which file applies now.

Good resource navigation answers:

• What does this file contain?
• Under what condition should it be read?
• How should its contents be applied?
• Is a targeted search enough, rather than reading the whole file?

Moving material out of the main body does not make it load on demand by itself. On-demand loading comes from clear decision boundaries, not directory names.

Scripts reduce instructional ambiguity, but output still has a cost

A script lets Claude perform a stable operation without reading its implementation or reconstructing the algorithm in natural language. That is often more reliable.

But execution produces output. If a validation script prints 100,000 lines of logs, the source code may stay out of context while the result still overwhelms the task.

Scripts should therefore follow progressive disclosure too:

• Print a summary by default; write details to a file.
• On failure, provide enough location information without dumping every intermediate state.
• Allow the scope to be narrowed by target, file, or phase.
• Let Claude decide from the summary whether it needs more detail.

Progressive disclosure governs not only which files are read, but also how much information an execution returns.

Directory size is not context size

A Skill folder can be large without immediately consuming much context:

20 MB of references on disk
  ≠
20 MB in the current request's context

If the entry point navigates accurately, unread materials stay on disk. Conversely, a 30 KB SKILL.md loaded in full every time may cost more in practice than a large package whose references are fetched only when needed.

An audit should therefore look beyond folder size:

This is a layered cost ledger, not one “how many kilobytes is the folder?” number.

Compare the loading time with CLAUDE.md

Both CLAUDE.md and Skills can hold instructions. Their first difference is not the kind of Markdown they use, but their default loading time:

If a section of CLAUDE.md keeps expanding into a multi-step procedure, it may not need to be present for every task; consider moving it into a Skill. If a Skill inevitably activates on every task, some of its constraints may belong in the project's standing rules instead.

Choose the carrier by scope and loading time, not Markdown syntax.

Four anti-patterns

Putting the entire workflow in description

The capability becomes visible, but every session pays for execution details. A description routes; it does not execute.

Putting every edge case in the main body

Every activation pays for rare branches. Keep the decision point in the body; move detailed handling to references.

Moving material out without saying when to read it

The folder looks tidy, but Claude cannot make the second routing decision. Splitting files is not the same as progressive disclosure.

Having scripts dump everything by default

The code stays out of context; its output does not. Separate a compact summary from detailed artifacts.

Evolution signals: which layer needs work?

• Relevant tasks never trigger the Skill → its description does not make the what and when clear enough.
• Unrelated tasks trigger it often → the description is too broad or overlaps another Skill.
• Context swells immediately upon activation → SKILL.md is carrying too much reference material.
• Claude often cannot find the right file → supporting resources lack conditional navigation.
• The same reference is read every time → its essential contents may belong in the main body.
• A large reference is rarely used → that is not necessarily a problem if its navigation is accurate.
• Several Skills prescribe conflicting processes at once → redraw the capability boundaries or activation conditions.

The takeaway

Progressive disclosure is not “split a long document into several files.” Each layer must answer one selection question:

description
  Which capability should I choose?

SKILL.md
  How should I advance the task?

supporting resources
  Which materials and operations does this branch require?

Only with clear entry conditions between the three can a Skill be discoverable, actionable, and cheap to keep available.

Up next

Progressive disclosure assumes Claude already has a catalog of candidate capabilities. But personal, project, parent-directory, nested, additional-directory, and Plugin Skills do not all come from one location. Part 3 examines which Skills appear in a session and how name collisions and path relevance define their scope.

References

• Agent Skills overview: How do Agent Skills work?
• Agent Skills specification: Progressive disclosure
• Claude Code documentation: Extend Claude with skills
• Previous article: From a Markdown File to a Portable Folder
• Related future reading: the Claude Code Context Management series, Part 0, on the context-window budget.