Agent Skills: Packaging repetitive tasks into discoverable, verifiable, and governable capability packages

The benefit of Agent Skills comes from reuse: repeatedly loading the same set of specifications, executing the same safety steps, and producing the same type of artifacts. Precisely because the benefit is built on "repetition," one-off open-ended exploration is not suitable to be written as a skill first. The goals of such tasks are constantly changing, and pass criteria cannot be defined in advance. If it is solidified too early, what gets encapsulated will only be unverified wrong assumptions.

Therefore, to determine whether a task is worth encapsulating, check whether it simultaneously meets two conditions: first, it is sufficiently repetitive; second, it is verifiable. Repetitive means the same type of task will appear again, making it worthwhile to accumulate stable triggers, execution steps, and resource lists for it; verifiable means there is a stable pass criterion that can determine whether an execution was done correctly. Only tasks that meet both conditions produce skills that are truly executable, verifiable, and rollback-able, rather than a piece of text that can only be read but not used.

The process of encapsulating Agent Skills is to combine the triggers, steps, resources, and acceptance of a class of repetitive tasks into a versioned capability package. Its inputs are multiple real task trajectories, plus the stable pass criteria extracted from them; its output is a reusable artifact that is discoverable, executable, and rollback-able. The input here is not a task description imagined out of thin air, but real records of successes and failures that have been run multiple times — only the stable parts extracted from these trajectories are worth writing into the skill.

Conversely, if the goal of a task keeps changing, or if it is always impossible to define "what counts as pass," then the skill should not take on this work. Forcing encapsulation at this point will only solidify wrong assumptions and make every subsequent reuse repeat the same mistake. The correct approach is to keep the fallback path of a general-purpose Agent: let the general-purpose Agent continue looking for stable approaches through open-ended exploration, and only after a pattern has been repeatedly verified and the pass criteria can be stably defined, extract it into a skill. The boundary of a skill lies here — it is responsible for solidifying verified, verifiable repetitive work, rather than drawing conclusions prematurely for exploratory work.

Prompts, tools, skills, and workflows can all “tell an Agent how to do something,” but they answer different questions and carry different responsibilities. Mixing the four up is the most common mistake beginners make, and their differences can be seen clearly from three aspects: “what they answer, what they produce, and what typical content they contain.”

A prompt answers “how to respond in this turn.” It operates on a single interaction, and its typical content is specific instructions and examples, with the goal of guiding the expression in this turn.

A tool answers “what actions can be executed.” Its typical content is a schema and an executor, and its role is to provide callable, verifiable action capabilities.

A skill answers “how a certain type of task is completed.” Its typical content covers triggers, processes, resources, and acceptance criteria, and its role is to organize a whole class of repetitive tasks into a reusable capability package.

A workflow answers “how system state transitions in a durable manner.” Its typical content includes nodes, branches, retries, and compensations, and its role is to persistently orchestrate changes in system state.

These four can be combined, but they cannot replace each other. A skill can call tools, and it can also attach to a workflow, but the skill itself does not grant any permissions, nor can it guarantee on behalf of the executor that side effects are safe. In other words, a skill describes the method of “how it should be executed,” while permission granting happens at the tool and executor layer, and the final safety responsibility for real-world side effects falls on the executor, not on the textual description of the skill.

From the perspective of layer-based discernment, this process receives an Agent artifact and the responsibilities it should bear, and outputs a classification of whether it belongs to prompts, tools, skills, or workflows. The key to classification is not the length of the text, but the question it answers: what only affects a single turn of expression is a prompt, what provides callable actions is a tool, what organizes a whole category of tasks is a skill, and what orchestrates state transitions is a workflow. Only by understanding this layer distinction can you place each type of responsibility at the correct layer during design, and avoid having skills assume permissions and safety responsibilities that they fundamentally cannot bear.

A skill that consists only of a README is difficult to reuse reliably, because it lumps together the applicable boundaries, inputs and outputs, operating steps, reference resources, and governance rules, making it impossible to access precisely what is needed at the right time. A skill package that can be executed repeatedly and accepted should have at least six types of contracts, each answering different questions.

The first type is the description, which explains the conditions under which the skill is applicable or not applicable, as well as the user-visible capability boundaries. It answers, “When should this skill be used, and when should it not be used?”

The second type is inputs and outputs, which specifies fields, files, schema, and examples. It answers, “In what form does data enter, and in what form does it leave?”, so that callers and executors have the same understanding of the data contract.

The third type is steps, ordered by dependencies and annotated with key decisions and stop conditions. It answers, “In what order should things be done, and under what conditions should each step stop?”, preventing the executor from improvising in intermediate states.

The fourth type is resources, that is, references, templates, and assets that are read on demand. It answers, “What other materials can be accessed when needed?”, rather than being loaded unconditionally in full.

The fifth type is scripts, which handle deterministic computation, transformation, and validation. It answers, “Which computations must be done by code rather than natural language?”, and hands reproducible work to executable logic.

The sixth type is governance, which records versions, dependencies, permissions, owners, and rollback methods. It answers, “Who is responsible for this skill, what does it depend on, and how do we roll back when something goes wrong?”

The six types of contracts are not read in the same way. The entry instructions must be read in full, because the trigger conditions, data contract, and execution steps determine everything that follows; extended resources should be loaded progressively as the task progresses, avoiding permanently stuffing the entire document into the context. This ensures sufficient information during execution without overloading the context all at once.

The overall process of the skill package structure is: input applicable tasks, data contract, operating steps, reference resources, scripts, and governance information; output six types of contracts that can be independently executed and validated. Reading the entry instructions in full, loading extended materials on demand, and delegating deterministic work to scripts—these three points together ensure stable reuse. It is important to be wary that having all six types present only means responsibility can be traced; it does not mean the scripts, templates, or rules are always correct. When dependencies change, regression verification is still required; otherwise, the skill will continue to be executed with outdated assumptions.

Scattered writing prompts, calculation scripts, and brand templates are each useful, but they do not form a stable and reliable capability. Packaging them into a “generate and verify monthly PDF report” skill makes it clear how the six types of contracts map onto concrete objects in real tasks.

The trigger conditions for this skill are very clearly specified: the inputs are a verified CSV and a report date, plus brand rules. The skill is not responsible for data cleaning or fact completion—those missing or unverified contents are outside its scope and belong to upstream work.

The division of labor during execution is layered. The entry point reads the field dictionary and brand rules, and selects the corresponding template accordingly. The script is responsible for calculating aggregate numbers and outputting a machine-readable intermediate JSON; the model only interprets trends and does not perform numeric calculations. After generating the document, a rendering script is called to check page count, overflow, fonts, and tables, keeping layout issues out before delivery.

The acceptance loop is the key that distinguishes this skill from “please write a beautiful report.” Every number must be traced back item by item to the intermediate JSON, and every citation must be traced back to the input row; if any trace-back fails, it stops and does not deliver. The final output includes the PDF, a validation report, the complete versions of the skill/template/script, and any unresolved warnings.

The value of doing this is that what is added is not more text, but three things: clear input boundaries, deterministic computation, and a verifiable acceptance loop. Overall, the input of this case is a verified CSV, a report date, and brand rules; the output is a PDF, a validation report, complete version information, and unresolved warnings. It solves the problem of how scattered prompts, scripts, and brand templates can form a reliable capability. The system uses scripts to calculate numbers, the model to interpret trends, and the renderer to check layout, then traces numbers and citations back to the input, so that the word “pass” is well-founded. It must be emphasized that “pass” only means that this artifact satisfies the declared content and layout acceptance, and does not handle cleaning missing data or fabricating facts—these two responsibilities always belong to upstream and input data.

“90% selection accuracy” sounds good, but in low-base-rate scenarios it can still frequently disturb users. Skill selection is essentially a classification problem, and classification performance must be assessed with two ratios, not just one.

Suppose only 20 of 100 requests truly need skill S. The selector retrieved 18 correct requests, achieving recall of 18/20 = 90%. But at the same time it falsely triggered 16 ordinary requests. Then precision is only 18/(18+16) = 52.9%. In other words, nearly half of the triggers are wrong.

These two formulas correspond to two different questions. Precision equals true positives divided by true positives plus false positives, answering “among requests that triggered the skill, how many truly should have triggered it.” Recall equals true positives divided by true positives plus false negatives, answering “among requests that truly need the skill, how many were retrieved.” Here, TP is the number of requests that correctly triggered the skill, FP is the number of requests that did not need the skill but were falsely triggered, and FN is the number of requests that needed the skill but were not triggered.

Low base rate is the root cause that makes high recall seem dangerous. When the proportion of requests that truly need the skill is very low, overlap between descriptions causes false triggers to flood in, and even if recall is high, precision will still be dragged down. This is exactly why “90% recall” still frequently disturbs users: the total number of triggers is inflated by false positives.

Therefore, the skill selection process takes a request and skill descriptions as input and outputs one of three outcomes: selecting a specific skill, requesting clarification, or no skill. Preparing contrastive negative examples for adjacent skills and allowing the “no skill” option can help the classifier avoid jumping to conclusions before it is confident. For skills with high side effects, it is better to clarify first than to sacrifice precision for high recall—an incorrect trigger may have irreversible real-world consequences. These ratios all depend on the base rate of requests, so in high-risk, low-base-rate scenarios, the primary goal is to reduce false triggers rather than maximize recall.

Putting the full text of all skills into the system prompt makes the system both slower and worse. The reason is that context is a finite, contested resource: once full texts are piled in, each skill competes for attention and position, the information that is truly needed is diluted, and processing speed is dragged down. Progressive disclosure is a staged loading approach designed precisely to solve this problem.

The whole process can be drawn as a path from discovery to acceptance: the request first matches lightweight skill descriptions; only after selection is the complete skill entry loaded; then references, scripts, and assets are read on demand; finally the artifact is executed and accepted under constrained conditions. This path separates the “cost of discovery” from the “knowledge needed for execution”—the discovery phase requires only lightweight descriptions, while the execution phase requires complete material.

From an input-output perspective, progressive disclosure receives a task and a lightweight description catalog; the output is the entry of the selected skill, along with the references, scripts, and assets loaded on demand during execution. The discovery phase only compares each skill's applicability boundaries: the skill whose description matches the current task moves to the next stage. Only after selection is the skill's entry fully read, then the resources necessary for execution are loaded, and finally acceptance is completed.

The benefit of this approach is reducing context competition, allowing each piece of material to enter context only at the moment it is truly needed. But this does not mean that unloaded materials are useless, nor does it mean they can be compressed arbitrarily. The entry carries critical constraints; if these constraints are omitted from the entry, subsequent execution will be distorted—because the executor never sees the rules it must follow. Progressive disclosure optimizes “when to load,” not “whether it can be discarded.”

After handing computation over to scripts, skills do not automatically become reliable. Scripts are indeed good at precise, repeatable operations—parsing, calculation, format conversion, and validation should all be handed to scripts first, rather than giving them to the model to compute laboriously in natural language. But for scripts to be truly usable, they must be governed like product code.

For a qualified deterministic script, the input should be data validated against a schema, and the output should be repeatable computation, transformation, or validation results, plus explicit error codes. Its role is to solve the problem that models are not good at precise repetitive operations, while using several types of constraints to keep side effects under control: input schema, error codes, idempotency, timeout, sandbox, and tests. Together these ensure that the script behaves stably under the same conditions, and that failures can be identified and handled.

In terms of side effects and permissions, scripts should be read-only by default. Any write operation must first show a diff and request approval, and the scope of paths, network, and credentials must be minimized. Scripts must not use their output to cover up problems in the source data, nor write secrets into logs—these two points may seem like engineering details, but they are actually security boundaries: covering up source data allows errors to be prettified and continue flowing, and leaking secrets in logs spreads credentials.

It is important to note the boundary of the word “determinism.” Determinism only means that behavior is stable under the same conditions; it does not mean that the code is secure, that the input is trustworthy, or that write operations have been approved. Stably repeating an erroneous calculation is still an erroneous calculation. Therefore, the problem that deterministic scripts solve is “repeatability,” while security, input trustworthiness, and write operation authorization still must be guaranteed separately by schema, sandbox, tests, and approval processes.

Changing only one reference document may also change the behavior of the entire skill, because the components of a skill are interdependent. A change in any one of the entry point, resources, templates, scripts, dependencies, or runtime environment can, through a chain reaction, alter the final execution result. Therefore, version governance must lock these objects simultaneously, rather than giving only the entry point a version number.

The skill version inventory must record: the entry point, all referenced resources, templates, scripts, dependencies, and compatible models and runtime. At release, produce an immutable version and keep migration notes so that people using the old version know what changed in the new version and how to migrate. At runtime, record the complete resolved set of versions—that is, which versions were actually used in this execution—so that afterwards you can explain "why did we get this result at that time".

External links cannot be treated as stable dependencies. The content that a link points to may change at any time. The correct approach is to snapshot it, verify its hash, or fail explicitly when the link is unavailable, rather than silently substituting different content and continuing execution.

Updates trigger regression. Any change in a reference should trigger a regression verification. For high-risk updates, first replay historical tasks and compare whether choices, tool trajectories, artifacts, and permissions have undergone any unintended deviations. This way, side effects caused by changes can be discovered before release.

Overall, the inputs to version governance are the entry point, resources, templates, scripts, dependencies, and runtime environment; the outputs are an immutable skill version and a replayable complete set of versions. The value of version locking lies in supporting the explanation of old results, but it cannot prevent changes in external services themselves. When a link becomes invalid, the system must fail explicitly rather than quietly substituting content. The former is controllable internal governance; the latter is an external boundary that must be faced honestly.

When end-to-end failure occurs, the most important question to answer is: did the mistake happen at the "selecting the skill" layer, or at the "executing the task" layer? A single aggregated end-to-end score cannot distinguish between false triggering and execution errors, so evaluation must be split into two layers, each with its own metrics.

The selection layer measures whether the skill was selected correctly. The test set should include positive examples, near-negative examples, and no-skill requests; the evaluation metrics are precision, recall, clarification rate, and mismatch cost. Precision and recall answer "whether it triggers accurately and whether what should be triggered is retrieved"; clarification rate answers "whether the system stops to ask in time when uncertain"; mismatch cost answers "how much cost a single false trigger incurs".

The execution layer measures whether the task itself was done correctly after the skill has been confirmed as correctly selected. Evaluation metrics include task success, step compliance, script pass/fail, artifact quality meeting standards, permission violations, token and time savings, and the number of manual corrections needed. These metrics are meaningful only when the premise of "correct selection" holds; otherwise, even excellent execution is executing the wrong skill.

The inputs to the two-layer evaluation are a request set, near-negative examples, tasks confirmed as correctly selected, and previous version baselines; the outputs are selection metrics and execution metrics. By first determining whether the skill was selected correctly, and then determining whether steps, scripts, artifacts, and permissions pass, failures can be precisely located to a specific layer.

In addition, evaluation must have a frame of reference and slices. Compare against a general-purpose Agent, a prompt-only approach, and previous skill versions to see what incremental value the new skill brings; also slice by missing input, environment changes, and anomalous data to see how the skill performs under different conditions. Pretty examples cannot replace the failure distribution—a few success cases cannot demonstrate the system's true performance on abnormal inputs. Just as an overall end-to-end score cannot distinguish false triggering from execution errors, pretty success examples cannot represent the distribution of abnormal inputs.

When two skills have overlapping functionality, letting them continue to coexist makes selection increasingly confusing and multiplies risk. If a skill catalog only grows without removal, outdated and overlapping skills will keep competing for the selector's attention, misleading classification and increasing false triggering. Therefore, skills need complete lifecycle management, not just creation and publication.

The first step in lifecycle management is regular auditing. The catalog must periodically check each skill's owner, usage, failures, dependencies, and permission status. This information determines whether each skill should be retained, merged, deprecated, immediately disabled, or rolled back.

There are several ways to handle them. Skills with overlapping functionality should be merged, consolidating the overlapping descriptions into a clearer boundary. For skills that need to be deprecated, a replacement and a clear deadline must be provided before deprecation to give those still using them time to migrate. For high-risk vulnerabilities, they should be disabled immediately and rolled back to the general process, without waiting for the normal deprecation cycle to complete.

When deleting a skill, its versions and historical execution evidence must still be retained. The sole purpose is to ensure that old artifacts can be explained. Which version of the skill generated a past artifact and what was executed at the time—these records must not disappear when the skill is deleted. But a clear distinction must be made: retaining history is only for explaining old artifacts, and in no way means the old skill can still be triggered.

Overall, the inputs to skill lifecycle management are the owner, usage, failures, dependencies, and permission status of each skill in the catalog, and the outputs are decisions to retain, merge, deprecate, immediately disable, or roll back. It solves the problem of overlapping and outdated skills continually increasing selection confusion and risk. One priority is fixed: high-risk vulnerabilities must be stopped first, followed by the normal merge and deprecation processes.

When a single request hits multiple skills at the same time—for example, "turning Excel data into a PDF report" matches both a spreadsheet skill and a document skill—you cannot resolve it by arbitrarily choosing one; you must explicitly disambiguate or compose.

The selector first filters by hard conditions: skills whose input type, output artifact, or permissions do not match are directly excluded; then it ranks by description relevance. If two skills remain after filtering, further determine their relationship: is it a competitive relationship with overlapping goals, or a complementary relationship across sequential stages?

For skills with overlapping goals, choose the one that is more specific and has a supported version, and use nearest-neighbor counterexamples to verify that the choice does not lean to the wrong side. For skills that are complementary across sequential stages, the manager can compose them according to their declared inputs and outputs, chaining them together rather than arbitrarily choosing one. The key to composition is to have a single owner and an intermediate artifact schema that defines the data contract handed off between the two skills—otherwise the two skills may each interpret the intermediate product according to their own understanding.

The most dangerous situation is when two skills write to the same resource at the same time. At that point, you must either prohibit concurrency or designate a single owner, and use diff and locks to ensure that two skills do not end up editing the same file at the same time.

To enable these judgments, skills need to clearly state conflicts_with, requires, and composable interfaces in their declarations, explicitly exposing conflict relationships and composition constraints. When encountering a high-risk conflict, or when the confidence gap between two candidates is very small, you should clarify with the user; do not give an implicit priority to a skill just because it was loaded first or happens to appear earlier in the context—loading order should not become the basis for deciding permissions.

Overall, the inputs to conflict resolution are the inputs/outputs, permissions, dependencies, and conflict declarations of multiple candidate skills; the output is one of four: a single choice, composition according to schema, clarification, or fallback to no skill. First filter by hard conditions, then determine whether they overlap or complement each other, and designate a single owner for shared resources. Successful composition only means that the interfaces can connect; it absolutely does not mean that two skills are allowed to write to the same resource concurrently, nor that loading order can decide permissions.

Viewing the whole causal chain together, agent skills are a process that starts from a specific problem, gradually converges to verifiable practice, and each step builds on the previous one.

The starting point is to identify tasks that are repetitive and verifiable. Only such tasks are worth encapsulating, because all the benefits of a skill come from reuse, while tasks that cannot be verified only solidify incorrect assumptions. This step determines whether all subsequent work is meaningful.

After the task is identified, extract stable steps from multiple real trajectories of successes and failures. Stable steps are not designed out of thin air; they are distilled from the history of what has actually been run, and only validated practices are worth writing into a skill.

With stable steps in place, the next is to clearly write out the applicable and non-applicable conditions, as well as the input and output contracts. This step fixes the boundaries of the skill, so that the caller and the executor share the same understanding of "when to use it, how data goes in and out."

Then put the deterministic work into restricted scripts. Leave repeatable operations such as parsing, computation, format conversion, and validation to code, and constrain their side effects with schemas, sandboxes, timeouts, idempotency, and tests.

Organize references and assets on demand, rather than cramming them into the context all at once. Read the entry point in full, and load extended resources progressively during execution, so as to minimize context contention.

After the skill takes shape, evaluation must be conducted at two levels: first see whether the skill was selected correctly, and then see whether the skill did the task correctly. The selection layer looks at precision, recall, clarification rate, and mismatch cost; the execution layer looks at task success, step compliance, script pass rate, artifact quality, and permission violations.

Before release, lock the complete dependencies and perform a canary release. Put the entry point, resources, templates, scripts, dependencies, and runtime environment all under version lock; for high-risk updates, first replay historical trajectories, and gradually increase traffic instead of switching over entirely at once.

After going live, continuously monitor, upgrade, merge, or decommission. Audit the catalog regularly, merge those with overlapping functionality, deprecate outdated ones and provide replacements and timelines, immediately disable and roll back high-risk vulnerabilities, and when deleting, still retain historical versions and runtime evidence to explain old artifacts.

This chain starts from the judgment of "whether it is worth encapsulating", goes through extraction, contract formalization, scripting, on-demand loading, layered evaluation, version locking, and canary release, and finally enters continuous governance. Every link answers the same question: how to turn a class of repetitive tasks into a capability package that is discoverable, executable, verifiable, and rollback-capable.