A Skill's Shape: Knowledge, Instructions, and Progressive Disclosure
A Claude Skill becomes useful through the way its parts divide responsibility. The focus here is not the folder as a piece of packaging, but the operating model inside it: which information decides whether the Skill is relevant, which instructions guide action, which resources appear only when needed, and where external tools remain responsible for state. Understanding that shape helps a reader build the smallest package that can support a real workflow instead of assembling a monolith that is difficult to load, test, and change.
The basic package is deliberately simple. A Skill is a folder containing a required SKILL.md with YAML frontmatter and Markdown instructions. It may also contain scripts, reference documentation, and assets. Those optional parts are not empty slots in a standard checklist. Each one exists to solve a different problem in the workflow, and the package works only when the boundaries among them are clear.
Four responsibilities inside one package
The first responsibility is discovery. YAML frontmatter tells Claude what the Skill is for and when it should be considered. It is a small routing surface, not the place to hide a full procedure. If the description is vague, the Skill may not load when it should. If it is too broad, the Skill may appear for unrelated requests. The metadata therefore owns relevance, but it does not own the work that follows.
The second responsibility is action. The body of SKILL.md contains the core instructions: the major steps, the decisions that must be made, the tools or capabilities to use, the checks to perform, and the way to handle common failures. This is the package's operational center. It should be complete enough to guide a relevant request, but focused enough that an agent can identify the next action without searching through a large reference archive.
The third responsibility is detail on demand. References can hold material that matters only in particular situations: an API pattern, a domain rule, an error-code explanation, or a style standard. Moving that material behind a link is not the same as discarding it. It is a decision about when the material should enter context. A reference becomes part of the workflow when the main instructions point to it and the current request needs it.
The fourth responsibility is deterministic or presentational support. A script can perform a check whose result should not depend on how the model interprets a sentence. An asset can supply a template or other material used in an output. These resources support the workflow, but they do not become a substitute for explaining when they should be used or what their result means.
The external system has a separate responsibility. An MCP integration or built-in tool owns access to data and actions in that system. It may fetch a project, create a record, or store a file. The Skill can specify the order, parameters, decision rules, and validation around those calls, but it does not magically own the external state. That distinction becomes important when an action fails halfway through, when permissions are missing, or when a tool's interface changes.
The diagram is a responsibility map, not a claim that every Skill has the same number of files or that every workflow needs a script. Discovery metadata, core instructions, and external tools are distinct because they answer different questions. References and optional resources appear only when the workflow needs them. A package is modular when a change in one responsibility does not force unrelated parts to be rewritten.
Why the package should be smaller than the domain
A domain can be enormous, but a Skill should serve a bounded use case. Consider a Skill for producing a consistent project status report. The domain might include project management, reporting conventions, data definitions, and organizational policy. The Skill does not need to contain every fact about all four areas. It needs enough instruction to gather the relevant status, apply the agreed reporting structure, identify missing data, and produce or route the result. A reference can explain a specialized metric when the report includes it. A script can check required fields. An asset can provide the approved template.
This separation has two benefits. First, it reduces the number of decisions Claude must make before acting. The core instructions can say what to do for the common path and when to consult detail. Second, it makes ownership clearer. A template owner can update the asset without rewriting the workflow. A domain expert can revise a reference rule without changing the trigger description. A tool owner can change an integration, while the Skill's author decides whether the workflow still matches the new interface.
The separation is not absolute. A reference that is never linked is effectively invisible to the workflow. A script that returns a failure without instructions for interpreting it is only a black box. An asset that does not match the steps in the core instructions can make the result less consistent, not more. Modularity requires interfaces: the main instructions must identify when a resource is needed, what input it receives, what result it returns, and what happens when the result is not acceptable.
This is also why a package should not be judged by how many components it contains. More files can mean better separation, or they can mean that the procedure has been scattered across places the agent cannot reliably find. The relevant measure is whether each component reduces ambiguity at a real boundary. If a detail is needed on every request, hiding it behind several links may create unnecessary retrieval work. If a detail is rare and costly to load every time, leaving it in the core file may consume attention that the common path does not need.
Progressive disclosure as a loading contract
Progressive disclosure gives this division a runtime meaning. The first level is frontmatter, which is always available so Claude can decide whether the Skill is relevant. The second level is the body of SKILL.md, which becomes available when the Skill is considered relevant. The third level consists of linked files that Claude can discover as the task requires them. The source guide presents this three-level system as a way to minimize token use while retaining specialized expertise.
The first level must be short but informative. It should communicate the outcome the Skill supports and the kinds of requests that should activate it. It should not assume that the agent has already read the full procedure. This is a routing interface between a user's language and the package's core instructions. A description such as “helps with projects” has too little information to distinguish the intended workflow from unrelated project questions. A description that names sprint planning, task creation, or status tracking gives the routing decision something concrete to match.
The second level must be the shortest path from relevance to responsible action. It should establish the role of the Skill, state the main sequence, name the critical checks, and point to deeper material at the moment it becomes relevant. This does not mean the body must be terse at any cost. A missing prerequisite or ambiguous branch can cause more context and more tool calls later. The goal is focused completeness: enough instruction to keep the common path coherent, without turning every exception into a permanent part of the main path.
The third level lets the package keep specialized detail available without making that detail part of every decision. Suppose a workflow supports several external services. The core instruction can establish the shared sequence and direct the agent to a service-specific reference when it identifies the service in use. Suppose a compliance check applies only to certain transactions. The core can state the decision point and require the relevant rule to be consulted before action. The reference then enters context because the current state requires it, not because every request happens to share the same possibility.
This loading contract has failure modes. If the frontmatter is too narrow, the Skill under-triggers and the user must manually invoke it or repeat the method. If the frontmatter is too broad, it over-triggers and introduces irrelevant instructions. If the core file assumes a reference without saying when to open it, the detailed knowledge may never reach the decision that needs it. If linked material is so extensive that the agent must load most of it anyway, the supposed disclosure boundary may not be doing useful work.
The guide does not establish a universal file-size threshold or a controlled measurement of token savings. Context behavior depends on the host surface, model, enabled Skills, task, and the amount of data returned by tools. Progressive disclosure is a design mechanism, not a guarantee. Its success should be tested through actual triggering, task completion, corrections, and context behavior.
Composability without a monolith
A Skill may work alongside other Skills, and the agent guide describes Skills as modular capabilities that can be composed in single-agent and multi-agent systems. Composability means that one capability can provide a bounded contribution without assuming that it is the only capability in the conversation. A document-analysis Skill might extract facts, while a compliance Skill applies a specialized rule set to those facts. The important question is not whether one Skill can mention another, but whether the boundary between them makes the handoff understandable.
A useful handoff names the input and the expected output. If one Skill produces a validated set of fields, the next Skill should know that it is receiving fields rather than an unstructured conversation. If a preceding step can return “incomplete” or “needs review,” the following step needs a path for those states. Otherwise, composition can create a hidden assumption that every upstream action succeeds.
The same principle applies when a Skill uses several tools. The Skill may own the workflow state needed to decide what comes next, but the external systems own their own records and permissions. The instructions should make clear what information crosses the tool boundary and what must be checked after it crosses. This is especially important for actions that change external state. Reading a project and creating a task are not equivalent: the second may need confirmation, permission checks, duplicate detection, or a rollback or escalation path.
Composability can also fail through overlapping triggers. If several Skills appear relevant to the same request, the agent may have to choose among competing methods or load too much guidance at once. Specific descriptions, clear scope, and negative triggers can reduce that ambiguity. A package that is designed to coexist must state not only what it handles, but also what it does not handle.
Where the simplified model breaks
The package model is useful because it gives each part a job, but real workflows create pressure at the boundaries. A tool may return more data than the core instructions anticipated. A long conversation may retain stale results that obscure the current decision. A reference may contain a rule that conflicts with a user's request or with the current permissions. Multiple Skills may each be individually reasonable but collectively overload the context or produce incompatible recommendations.
The agent guide describes context-window overflow, degraded reasoning, and coordination failures as practical concerns for longer workflows. It recommends modular design, context editing, external memory, pagination, filtering, range selection, truncation, and sensible caps on tool responses. These techniques extend the same principle as progressive disclosure: keep the current decision supplied with the information it needs, and do not treat every available result as equally relevant.
There is also a difference between modularity and isolation. A Skill that never sees the result of the tool it just called cannot validate the next state. A Skill that tries to own every external state becomes tightly coupled to systems it does not control. The useful middle is an explicit interface: the Skill guides the exchange, the tool reports a result, and the workflow decides whether to continue, retry, ask for help, or stop.
That is the shape worth carrying into design. A Skill is not a miniature organization chart or an inventory of every supporting file. It is a set of boundaries that allow specialized knowledge to enter an agent at the right time, guide an action, and connect to an external system without hiding who owns the state. Once those boundaries are clear, the next design problem becomes more concrete: how should the package state its use case, trigger, instructions, and safeguards so that the right capability appears for the right request?