A Skill Is a Workflow with a Small Activation Surface
In Tech Leads Club's Agent Skills repository, the key design question is not how much information can fit inside a skill. It is which information should meet an agent first, which should guide the agent's decisions, and which should remain available until a specific task calls for it. Understanding that division lets a reader inspect a skill as a workflow contract rather than treating its description as marketing copy or its supporting files as an undifferentiated bundle.
Three layers, three jobs
A skill has at least three related but distinct surfaces. The first is metadata: a name, description, category, author or version information, and language that says when the skill applies and when it does not. The second is the main instruction file, SKILL.md, which gives the agent the operating guidance it needs once a candidate has been selected. The third is the set of bundled references, scripts, templates, and other assets that provide depth or perform a task-specific operation.
These layers are not simply different file formats for the same content. They sit at different points in the decision process. Metadata answers, “Could this be relevant?” The main instructions answer, “What should the agent do, and in what order?” Supporting files answer, “What detailed rule, example, checklist, or tool is needed for this particular step?” If those questions are collapsed, the system loses the ability to control when context enters the interaction.
The repository's registry reflects this distinction by recording the complete file set for each skill while preserving SKILL.md as the main file. That gives a runtime consumer a map of the package without requiring it to load every byte immediately. It also gives a human reader a useful inspection order: first understand the scope, then read the operating contract, then decide whether a deeper file is necessary.
The main instruction file is therefore an activation surface, not a miniature archive. It must be substantial enough to orient the agent, but bounded enough to remain usable as an initial payload. A long reference document may contain valuable nuance and examples while still being the wrong first response to a task that has not yet been classified. Conversely, a short main file that merely says “follow the files in this directory” leaves the agent without a reliable decision point. The package works when the main instructions mediate between the user's task and the package's depth.
This is a context-management decision, but it is also a reasoning decision. Loading fewer words is not automatically better. The relevant question is whether each loaded layer changes what the agent can correctly decide or do. A reference that contains the exact rule needed for a security review is worth loading when that review is requested. The same reference may be noise during an unrelated architecture discussion. The package gives the system enough structure to delay that choice until the task provides a reason.
The class relationships are useful because they show that a task does not consume every part of a skill in the same way.
The diagram's “requests when needed” edge is important. Supporting material belongs to the skill because it carries the skill's evidence or tools, but belonging to the package does not mean appearing in every response. That separation allows one capability to be both deep and economical: its complete working material can travel with it, while its first activation remains focused.
Consider a user who asks for help with a React component that has accumulated too many boolean props. The metadata should make the composition skill a plausible candidate and exclude unrelated performance work. The main instructions should explain the composition approach and identify the rule categories that matter. Only then does the agent need a particular rule file, such as the guidance on explicit variants or compound components. If the user instead asks why the page is slow, the same package may be present in the catalog but should not control the response. The package's layers make that difference visible before a long explanation has already shaped the agent's reasoning.
The same logic applies when supporting files contain executable material. A script may be part of the skill because it generates a review checklist or validates a structure, but its presence should not silently turn a discovery request into execution. The main instructions are where the condition should be made clear: what the file is for, whether it must be read or run, and what result the agent should expect. A bundled file without a clear relationship to the main contract increases ambiguity. A clearly linked file gives the agent a next step while preserving the user's opportunity to inspect or decline it.
Scope boundaries turn advice into a usable workflow
A package becomes more than a reference note when it tells the agent how to recognize a situation and how to proceed after recognition. The repository's examples show this in different forms.
The specification-driven skill describes a sequence that adapts to complexity. It distinguishes specifying a feature from designing its architecture, breaking work into tasks, and executing with verification. It also tells the agent how to resolve its own supporting files and scripts relative to the skill directory rather than assuming that the consuming project has the same layout. That is operational guidance: it covers the order of decisions, the location of supporting material, and the conditions under which a gate must pass.
The AWS advisory skill encodes another kind of workflow. It asks the agent to identify the relevant service, search documentation before answering, select the right topic for that search, and adapt recommendations to the user's stack and constraints. Its guidance about infrastructure-as-code choices is conditional rather than absolute. It does not present one tool as the universal answer; it connects a recommendation to a context such as a quick serverless prototype, an existing multi-cloud environment, or a team that values type safety. References and scripts are then available for deeper reviews instead of being forced into every response.
The React composition skill is narrower but makes the same design point. Its main guide identifies the situations in which composition patterns matter, orders rule categories by priority, and points to individual files for detailed explanations and examples. A reader dealing with boolean-prop proliferation can move from the scope description to the main principle and then to the specific rule that fits the component problem. The package does not require the agent to ingest every React rule before it can recognize the relevant pattern.
The difference between these examples is instructive. The planning skill is organized around state changes in a project: specify, design when needed, break work into tasks, execute, and verify. The AWS skill is organized around evidence gathering and conditional selection: identify the service, search the appropriate documentation, compare options, and then recommend. The React skill is organized around a decision taxonomy: recognize an architectural smell, choose the relevant pattern category, and inspect the rule. A shared package format can carry all three because the format does not prescribe one universal workflow. It gives each skill a place to state its own triggers, sequence, and stopping conditions.
In all three cases, positive scope is only half of the routing contract. “Use when...” phrases help the catalog surface a candidate, but negative scope prevents a nearby concept from becoming a false substitute. Security guidance that says it is not for general debugging, an AWS guide that excludes other cloud providers, or an architecture skill that excludes performance work is doing more than narrowing a marketing description. It is reducing the number of situations in which the agent should treat the skill as authoritative.
That matters because agents are good at finding semantic resemblance even when the user's task requires a different decision. A request to improve a React page's performance may mention components, rendering, and APIs—the same vocabulary that appears in a composition guide—without being a composition problem. A broad search for “security” may return a best-practices guide when the real need is threat modeling. Negative scope gives the agent a reason to reject a plausible but wrong route, and it gives the user a basis for correcting the selection.
A workflow skill also differs from a static note in what happens after a decision. It can require a search before an answer, specify a validation gate before a task is considered complete, ask for context before choosing a tool, or direct the agent to read a particular reference for a particular case. Those instructions create transitions: a trigger leads to an activation, an activation leads to a decision, and the decision may lead to a supporting file or a script. The skill is valuable because it makes those transitions explicit enough to repeat.
The repository does not claim that the file format enforces every transition. A host agent may ignore an instruction. An external MCP tool named by a skill may be unavailable. A reference can be outdated or too general for the situation. A script can produce a structured result without making the underlying judgment correct. The package expresses an intended workflow; the host agent supplies the execution environment and the user remains responsible for deciding whether the result fits the project.
These failure paths are useful tests of the package design. If a trigger is too broad, the skill competes with neighboring guidance. If the main file is too thin, the agent has no reliable reason to select or sequence the supporting material. If a reference is present but not linked, the deeper evidence becomes effectively invisible. If a script is linked but its expected inputs and outputs are unstated, the agent may run it without knowing how to interpret the result. The repository's structural conventions cannot solve every one of these problems, but they make the questions concrete enough for an author or maintainer to review.
That boundary is part of portability. A skill can travel because its scope, instructions, and supporting files are packaged together, but it cannot carry every assumption about the surrounding project. The specification skill can tell an agent where its own scripts live; it cannot guarantee that the consuming project has a compatible test runner. The AWS skill can require documentation search; it cannot supply credentials or regional availability. The React skill can point to a rule; it cannot infer the component's product constraints. A well-designed skill exposes enough of its method to make those dependencies visible.
That visibility helps a human decide whether to continue. A user can ask for the missing context, provide the required project information, choose a narrower skill, or stop before a script is run. In other words, portability should reduce friction without erasing the points where a person needs to exercise judgment. The package format is strongest when it tells the agent what it knows, what it needs, and what it cannot decide on the user's behalf.
The result is a small activation surface with a large but structured interior. Metadata narrows the candidate set. SKILL.md gives the agent a sequence and boundaries. Supporting files deepen one step without turning the whole catalog into context. This structure also creates a publication problem: once many such packages exist, the system needs a machine-readable contract that preserves their identity and complete file sets. The next boundary is therefore not another instruction inside a skill, but the registry that makes the package discoverable and verifiable at scale.