From User Intent to Safe Action: Designing the Skill Contract
A Skill becomes actionable only when its design connects a user's goal to a bounded sequence of decisions. This chapter focuses on that contract: how to choose a concrete use case, describe when the Skill should load, write instructions that lead to verifiable actions, and place validation or human review where the workflow can no longer safely guess. The result should be a testable operating hypothesis, not a broad promise that the Skill can handle an entire domain.
The previous chapter separated discovery metadata, core instructions, optional resources, and external tools. The design problem now is to make those parts agree. A good description should attract the right request. The core instructions should tell the agent what to do after activation. References or scripts should appear when their detail is needed. Checks should prevent an incomplete or unauthorized action from being presented as success.
Start with an outcome that can be observed
The source guide recommends identifying two or three concrete use cases before writing code or detailed instructions. Each use case should state what the user wants, what might trigger it, which steps are required, which tools are involved, and what result would count as completion. This is more demanding than naming a domain. “Project management” is a domain. “Plan this sprint from the current project status and create prioritized tasks” is a workflow that can be examined.
The distinction matters because an outcome controls scope. A Skill for sprint planning may need current project status, team capacity, prioritization rules, and task creation. It does not automatically need every project-management feature. If the use case is instead “summarize a project's status,” task creation may be outside its boundary. Adding both workflows without deciding whether they share a trigger, a sequence, and a validation rule can make the Skill harder to route and harder to test.
A concrete use case also makes success visible. The guide suggests looking at signals such as whether the Skill triggers at the right times, whether the workflow completes without user correction, whether tool calls fail, and whether results remain consistent across sessions. These are not universal pass marks. They are dimensions a team can observe. A planning Skill might be judged partly by whether it creates the intended tasks with the right properties and partly by whether it asks for missing capacity information instead of inventing it.
This is why success should be stated in terms of an external result rather than the presence of internal artifacts. A correctly named file does not prove that the workflow was useful. A response that sounds confident does not prove that the data was current or that an action succeeded. The Skill's design should identify the state or artifact that can be checked, the information required to reach it, and the conditions under which the workflow must stop.
The guide's examples of quantitative criteria—trigger rates, tool calls, API failures, or token use—are aspirational benchmarks. They help a team decide what to measure, but they do not establish a threshold that applies to every Skill. A document-creation workflow may prioritize formatting and revision quality. A workflow that changes an external record may place more weight on permissions, duplicate prevention, and human approval. The use case determines which evidence matters.
The description is a routing contract
Once the outcome is clear, the Skill's YAML frontmatter must tell Claude what the package does and when it should be used. The name identifies the Skill in a constrained format. The description is more important for behavior: it should use concrete tasks or phrases a user might actually say, not only an abstract category.
A description such as “helps with projects” leaves several questions unanswered. Does the Skill plan a sprint, create a project workspace, report status, or write project documentation? A more specific description can identify sprint planning, task creation, and status tracking as the supported work. The point is not to stuff every possible synonym into the field. It is to give the relevance decision a clear relationship between a user's request and the Skill's intended boundary.
The description must also communicate exclusion. The guide recommends more specificity and negative triggers when a Skill loads for unrelated requests. If a Skill handles statistical modeling for CSV data, it may need to distinguish that work from simple data exploration handled elsewhere. An exclusion is not a defensive slogan; it is a statement about ownership. When two Skills could plausibly respond, their descriptions should give the system a reason to prefer one or neither.
Frontmatter is a security-sensitive surface as well as a routing surface. The guide forbids XML angle brackets and reserved naming patterns, and it requires valid YAML. These rules are not cosmetic when metadata appears in the system prompt and influences whether instructions enter the model's context. A malformed or overly broad description can affect both discoverability and the material Claude is asked to follow.
The description cannot guarantee correct triggering. The guide does not provide a formal probability model or a universal trigger threshold. Representative tests are needed: obvious requests that should activate the Skill, paraphrases that express the same intent, and unrelated requests that should not. A design that cannot be expressed in a few concrete trigger situations may be too broad to implement as one Skill or may need separate use cases.
Turn the body into an executable method
The body of SKILL.md should tell the agent what happens after relevance has been established. “Validate the data before proceeding” is weaker than naming the validation and the consequence. The source's examples favor explicit actions, conditions, and common failure handling. The reader does not need a long inventory of every instruction pattern; they need to see why an action is actionable.
Consider the sprint-planning example. A usable workflow might say that the agent should fetch the current project status through the connected service, examine velocity and capacity, suggest prioritization, and create tasks with appropriate labels and estimates. The sequence reveals dependencies. Current status is needed before prioritization. Capacity affects what can be proposed. Task creation should happen only after the plan is coherent and the necessary information is present. If the service cannot be reached, the workflow needs a different path from the one used when the data is available but incomplete.
Actionable instructions also identify ownership. The Skill can decide that current status is required, but the project system owns the stored status. The Skill can prepare task properties, but the external service determines whether the user has permission to create them. The user or an assigned reviewer may own approval of a consequential change. When the instruction body leaves these boundaries implicit, a model may treat a suggested action as an already completed action.
Detailed knowledge should move into a linked reference when it is conditional or expensive to keep in the core path. A reference may explain service-specific rate limits, error codes, or a domain rule that applies only to a subset of requests. The core instruction should say when to consult it and how its answer affects the next step. A reference is not useful merely because it exists in the package; it must be reachable from the decision that needs it.
A deterministic script can be appropriate for a check whose result should not depend on interpretation. For example, a validator may verify required fields or a date format. But the instruction body still needs to explain when to run the validator, how to interpret a failure, and whether the workflow should ask for correction, retry, or stop. A script can make a check repeatable; it cannot by itself define the workflow's responsibility.
Troubleshooting belongs near the points where the workflow can fail. A connection refusal, an invalid permission, a missing field, and an inconsistent output are different conditions. They may require reconnecting, requesting access, gathering more information, or revising the Skill. Treating all of them as “try again” hides the actual boundary and can create repeated or unsafe actions.
The sequence is intentionally conditional. A tool call does not mean the action succeeded, and a loaded Skill does not mean the requested work is complete. The workflow must inspect the returned state or error, apply its checks, and distinguish completion from review, missing information, or failure. The user should receive a bounded outcome that says what happened, not a confident substitute for an unverified external state.
Put control points where uncertainty becomes consequential
Validation is most useful at a transition. Before reading external data, the workflow may need to confirm the correct project, account, or document. Before changing state, it may need permission, required fields, or an explicit confirmation. After an action, it may need to check that the external system reflects the intended result. These checks are not all interchangeable, because they protect different boundaries.
A precondition protects the action from starting with bad or missing input. A permission check protects the external system from an unauthorized change. A postcondition checks whether the requested state was actually reached. A human-review point handles cases where the Skill can assemble relevant information but should not make the final judgment. A rollback or escalation path limits damage when a later step fails after an earlier step has changed state.
The guide's pattern examples put compliance checks before processing, record the decision, and create a review case when the check fails. The same logic can apply outside regulated work. If a workflow cannot establish that its input is complete, it should request the missing information. If it cannot establish that a user is authorized, it should not silently proceed. If a multi-step operation has partially completed, it should report the partial state and use the defined recovery path rather than repeating a potentially duplicating action.
These measures do not make a Skill inherently safe. The source presents them as design obligations and examples, not as a complete threat model or certification. Data handling, permissions, external-system behavior, and human oversight remain part of the deployment. A Skill should make its control points visible enough that a team can test and monitor them.
Scope is also a failure-control mechanism
Negative triggers and troubleshooting guidance protect against a Skill being useful in the wrong situation. Over-triggering is not merely annoying. An irrelevant Skill can add instructions that compete with the user's real need, consume context, or encourage a tool call that should not occur. Under-triggering is also a functional failure when the user has to remember an invocation phrase or reconstruct the workflow manually.
The best response to a scope problem is not always a longer description. The Skill may be trying to own two different outcomes, or two Skills may need a clearer division of responsibility. Splitting the use cases can make the triggers more precise. Narrowing the instruction body can reduce accidental application. Adding a negative condition can clarify that a nearby task belongs elsewhere. These choices should be guided by test results rather than by a preference for either one large package or many small ones.
The contract is complete when a reader can answer five questions without guessing: What outcome does this Skill support? What kinds of requests activate it? What sequence follows activation? Which checks can stop or redirect the sequence? What does the Skill do when the external tool, input, permission, or review authority is unavailable? Those answers create a design that can be tested instead of a description that can only be admired.
A carefully written contract is still a hypothesis. It identifies the intended boundary and the expected path, but it has not yet shown that Claude will trigger at the right time, follow the steps, or improve the result. The next judgment is therefore integrated rather than cosmetic: do the outcome, boundary, activation, actions, context strategy, and safety controls form a coherent system that is ready to be evaluated?