How a Skill Becomes Context
Claude-Red’s central unit is a file, but the file does more than store security advice. It must be understandable as knowledge, discoverable as a candidate for loading, distributable without unnecessary machinery, and bounded by a human decision about where and how it may be used. This section follows that path from SKILL.md to active context, so readers can see why metadata, packaging, and trust checks are part of the system rather than administrative details.
Four layers in one small package
A Claude-Red skill has a body that explains a security surface. The API-security material, for example, begins with a sequence for mapping endpoints, identifying authentication, examining object and function authorization, testing resource controls, and documenting findings. The cloud material begins by asking which identity context is already available, then connects permissions to possible paths and data. These bodies are not simply dictionaries of terms. They give a model a frame: what to inspect first, which distinctions matter, what evidence would change the next step, and where a test leaves an observable trace.
That body is only the first layer. The project’s contribution guide requires YAML frontmatter containing a stable name and a description. The description is written for trigger matching: it should say what surface the skill covers, which scenarios activate it, and which terminology a user might mention. In a human-facing document, a description might look like a summary. In a context system, it also acts like a routing key. It helps decide whether a question about authorization should receive API guidance, business-logic guidance, identity guidance, or some combination.
A third layer is the category and manifest structure. Claude-Red groups skills by domains such as web, cloud, wireless, exploit development, and AI security. Its machine-readable manifest records category membership and paths. Categories help a person choose a bounded subset; the manifest helps software understand the collection. Neither one is the technical method itself. They describe where the method belongs and how it can be found.
The fourth layer is outside the repository: the Claude Skills runtime and the surrounding user environment. The runtime is expected to load matching skills on demand, but the repository does not control how triggers are ranked, how overlapping skills are combined, or how much context is retained. The user’s tools, credentials, target environment, and rules of engagement are also external. A file can describe how a permission edge might be examined; it cannot establish that the reader owns the system being examined or that a particular action is allowed.
Keeping these layers separate prevents a common category error. A well-formed file is not automatically active context. Active context is not target evidence. Target evidence is not a finding until its cause and impact have been established. And a finding is not authorized merely because a skill can describe how to produce it.
Why one skill should cover one surface
Claude-Red’s contributor guide favors “one skill, one surface.” That rule is partly about readability, but its deeper purpose is to reduce ambiguity at the selection boundary. If one document covers every kind of internal network movement, wireless protocol, cloud identity, and web application flaw, a trigger may bring in a large amount of loosely related material. The model then has more opportunities to blend concepts that only look similar.
A focused unit gives each term a local meaning. In API security, broken object-level authorization is a question about whether one authenticated context can reach another object. In business-logic testing, the central object may be a workflow state, a side effect, a quota, or a financial entitlement. In cloud testing, the relevant relationship may be a principal’s permission to pass a role or act as a service identity. These concerns can be related in a real attack chain, but they are not interchangeable. Separate skills allow the reader to connect them deliberately instead of letting a broad prompt flatten their differences.
Focus also improves failure analysis. If a response is poorly grounded, the reader can ask whether the wrong surface was selected, whether the selected file contains an unsupported assumption, or whether the target evidence was insufficient. With a monolithic document, those causes are harder to distinguish. Modularity does not eliminate wrong answers; it makes one class of wrong answer more visible.
The rule has a cost. Real engagements cross surfaces. A cloud identity may be reached through a CI/CD pipeline, an API may expose a business-logic race, and a wireless credential may become an internal identity pivot. Claude-Red’s category design recognizes these relationships, but a reader still needs to decide when to load an additional skill. The right pattern is not to force every surface into one document. It is to keep each unit focused, then make the relationship between units explicit through scope, evidence, and the attack or defense question at hand.
Three ways to load context
The README describes several ways to consume the collection, each creating a different boundary.
A full clone places the repository in a Claude skills directory so the runtime can discover its available content. This is convenient when a practitioner moves across domains, but it exposes the largest selection surface. It makes the quality of trigger descriptions and manifests especially important because the user is relying on the runtime to identify the relevant subset.
A sparse checkout limits the local material to selected categories. This is a stronger form of context management: an application-security team can keep web and API guidance available without treating every wireless or exploit-development document as part of the same working set. Sparse selection does not prove that the remaining material is irrelevant, but it reduces accidental exposure and gives an organization a simpler review boundary.
The project also describes direct loading of one file into Claude Code and manual insertion into a Claude.ai Project. These paths are more explicit. The user chooses the document, sees what is being supplied, and can review it before use. They may be less convenient for repeated work, but explicit selection can be valuable when a skill contains sensitive or high-impact material and the organization wants a human to approve the exact context.
These routes are not equivalent versions of the same action. Full loading optimizes convenience and breadth. Sparse loading optimizes a team or domain boundary. Direct or manual loading optimizes inspection and deliberate choice. The appropriate route depends on the question, the sensitivity of the material, the number of people using it, and the controls around the target—not simply on which route is fastest.
The diagram’s important boundary is between the runtime and the target. Claude can use the supplied context to organize questions, but only an approved investigation can produce target evidence. The arrow is not a promise that the model itself will access a system, and it is not a substitute for a tool’s authentication or authorization checks.
What the installer does—and does not do
Claude-Red’s install.sh is intentionally a distribution script. It can list categories, accept a destination, select one category, show a dry run, create the destination, and copy the skill tree. It uses rsync when available and falls back to recursive copying. The script does not install the security tools mentioned in the documents, execute Markdown as code, or decide how Claude will use the resulting files.
That simplicity is an advantage when the goal is to move reviewed documents into a known location. It is also a clear security boundary. The installer does not pin a repository commit, verify a signature or hash, review the text, or ask whether the eventual target is in scope. The project’s security policy recommends checking upstream material, but the copy operation itself cannot prove that the material is trustworthy or that the user has permission to act on it.
This distinction is easy to miss because “installation” sounds like a single event. In this project it is better understood as three separate decisions:
- Provenance: Which repository state or file are you accepting?
- Context: Which skills are necessary for the question, and which should stay out of the active environment?
- Authority: What written permission, technical restriction, and deconfliction process govern any action that follows?
The installer addresses only part of the second decision, and even there it offers copying rather than semantic selection. The first and third decisions belong to a surrounding process. A mature deployment could pin a reviewed revision, retain a manifest, scan for unexpected changes, restrict destinations, and require approval for high-impact contexts. None of those controls should be inferred from the presence of a shell script.
Metadata debt is a system problem
The repository snapshot shows why the distinction between content and routing metadata matters. The contribution guide says YAML frontmatter is required for loading through the Claude Skills system. Yet a controller inventory found that 28 of the 78 skill files do not begin with that frontmatter format. Several historical files instead begin with a prose metadata section or a plain heading. The AI-security and exploit-development documents are visible examples of this older style. The machine-readable manifest also contains empty descriptions for several skills.
This inconsistency does not mean that the older documents have no value. A person can read them, and a direct manual-loading path may still make their content available. The issue is that automatic discovery depends on information that is missing or expressed in a different form. A document can therefore be technically rich yet operationally invisible, or it can be discoverable through a manifest while lacking the descriptive data that would help a user select it accurately.
The problem is similar to an interface mismatch in ordinary software. A component may implement useful behavior, but if it does not expose the contract expected by the caller, the larger system cannot rely on it consistently. Here, the “caller” is the selection mechanism. Frontmatter is not a decoration around the body; it is part of the interface between repository and runtime.
The project’s own history suggests how this debt arose. The changelog describes early content derived from an offensive-checklist collection, later reorganization into category directories, and subsequent additions and deep rewrites. Growth creates pressure to add content quickly, while the loading contract requires older material to be migrated and the manifest to stay synchronized. Without a validation step that checks every file, the library can expand faster than its selection surface becomes reliable.
A useful maintenance response follows from the architecture: validate frontmatter, generate the manifest from the files, flag empty descriptions, preserve stable names, and identify legacy documents until migration is complete. Those checks would not establish technical accuracy, but they would remove a preventable source of routing uncertainty. In a context-aware system, discoverability is part of correctness.
Keep context scoped to the decision
The practical lesson is not that users should avoid broad collections. It is that context should be treated as a deliberate input to a decision. Before loading a skill, a reader should be able to state the authorized question, the surface or relationship under examination, and the evidence that is expected to answer it. If the question is still “What can I do with this repository?”, the context boundary is too broad for a real assessment.
The same discipline applies after loading. The skill body may suggest tools, edge cases, or chains, but the reader should ask which of those conditions are actually present. If a result depends on a particular protocol, identity, version, or state transition, that condition must be verified rather than assumed. If the test could disrupt service, expose data, or create a signal that the client did not authorize, the correct next step may be to stop, narrow the test, or obtain a new approval—not to load another skill.
Claude-Red’s design makes this disciplined selection possible, but it does not perform it automatically. The repository supplies units and conventions. The runtime supplies a way to activate them. The human supplies purpose, authority, and judgment. The next question is how to move from this file-level architecture to a coverage map that can narrow a broad security problem into a testable one.