AI agent skills turn repeatable procedures into reusable instructions, with evidence checks and explicit boundaries supporting dependable results. Photo: Jakub Żerdzicki / Unsplash
Learn how AI agent skills package instructions, references and scripts, and how to design, test and maintain a reusable workflow with clear boundaries.
Repeating the same instructions to an AI agent is a sign that part of the workflow could be made reusable. Perhaps every release summary needs the same evidence checks, or every design task should follow an established visual system. A skill packages that procedure so the agent can consult it when the relevant task arrives.
Skills are useful because good work usually involves more than asking for an output. It involves knowing which sources to inspect, what to do when information is missing and how to establish that the result is ready. Packaging those decisions can make a workflow easier to repeat and review.
This guide explains what AI agent skills contain, how they differ from prompts and tool connections, and how to design and test a narrow skill. The release-summary example is illustrative; it is not a claim that we installed or benchmarked a particular skill package.
A Skill Is a Reusable Procedure
The Agent Skills specification defines a skill as a directory containing a required SKILL.md file. The file combines metadata with instructions, and the directory can include scripts, reference documents and assets. A skill can therefore carry both a procedure and the supporting material needed to follow it.
Think of a skill as an operational document for a recognizable task. A release-summary skill might explain how to compare changes, distinguish completed work from plans and produce the organization’s preferred summary. A document-formatting skill might provide a template and a checklist for reviewing the finished file.
This does not retrain the underlying model or permanently teach it new facts. The agent receives instructions and resources during the workflow. Its performance still depends on the model, the tools available and the quality of the evidence it can access.
That distinction helps set expectations. If the agent cannot read the repository, a well-written review procedure cannot conjure the code. If it lacks the intended output tool, a template does not automatically give it a way to create the final artifact.
Prompts, Project Rules, Skills and MCP Solve Different Problems
A task prompt describes what you want now: summarize a particular change, revise a page or investigate a failure. Project rules capture standing requirements that matter across relevant work. A skill packages a procedure that should become relevant when a particular kind of task appears.
A tool connection supplies a different layer. MCP can expose ways to read live data or perform operations in another system. A skill can explain which of those tools to call, what to check between calls and what the final output should contain. Our MCP guide explains that connection layer in more detail.
OpenAI makes a similar separation in its plugin architecture: plugins can package skills, MCP servers or both. Instructions help the model follow a workflow; server-backed capabilities provide tools and access. Neither the presence of a skill nor its name establishes that an account is connected or authorized.
For a release summary, the prompt identifies the release. Project rules might establish the audience and house style. The skill specifies the comparison and verification procedure, while the tool connection lets the agent inspect the relevant records. Keeping these roles clear makes a failure easier to diagnose.
How Agents Find and Load Skills
In the official OpenAI documentation, ChatGPT and Codex initially use skill names and descriptions, then load the full instructions when selecting a skill. Users can invoke a skill explicitly, and the agent can also choose one when the task matches its description. The description is therefore part of the routing mechanism.
A vague description such as “helps with development” leaves too much room for interpretation. “Draft a release summary from a specified comparison, including verified changes and unresolved items” establishes a clearer task. Add boundaries when adjacent work should use a different procedure.
Anthropic also describes progressive disclosure: metadata helps identify relevance, the main instructions load when needed and supporting files are consulted for additional detail. The practical benefit is that every reference document does not need to occupy the initial context.
A shared file format does not establish identical behavior in every host. Discovery locations, available commands, dependencies and permissions can differ. Check the current documentation for the environment where you plan to use the skill, and verify that it appears there before diagnosing the model’s choices.
Design One Small Workflow Before Adding More
Choose a task that you already understand well enough to assess. For the worked example, imagine a team that needs a draft release summary from a specified range of code changes. The task ends with a draft and a list of unresolved questions; publishing the release is a separate action.
Write the success criteria before the procedure. The draft should include only changes supported by the supplied comparison, identify user-visible consequences and separate known limitations from completed features. It should not infer that code has been deployed merely because it was merged.
Then identify the minimum inputs. Those might include a repository, a comparison range and the intended audience. If the range is missing, the skill should ask for it rather than silently using whatever changed most recently. If a source is inaccessible, the result should state the gap.
Keep unrelated tasks out of the first version. A release-summary skill does not also need to own dependency updates, performance analysis and customer-email delivery. A narrow boundary makes both activation and output quality easier to test.
Put the Procedure and Evidence Requirements in Writing
OpenAI’s skill-building guidance recommends focused workflows with clear inputs, outputs and boundaries, while keeping detailed references beside a concise SKILL.md. Begin with instructions and existing tools; add a script when deterministic processing serves a specific need.
For the example, the procedure could tell the agent to confirm the comparison, inspect relevant changes, group them by user impact and draft the summary. It should also require source references for significant claims and a final check that planned work has not been presented as delivered.
Begin with a short metadata header, then write the procedure beneath it. This instruction-only sketch demonstrates the format and task boundary; adapt it to the host and tools before use.
---
name: release-summary
description: >
Draft release notes from a
specified code comparison.
---
Confirm the repository, comparison range and audience.
If the comparison is missing or inaccessible, ask or report the gap.
Inspect the changes using the available authorized tools.
Separate user-visible changes, limitations and unresolved questions.
Link important claims to the inspected evidence.
Do not infer deployment status or publish the draft.
Return the draft and a brief record of what was checked.
The most useful lines often describe failure behavior. Explain what to do with an ambiguous change, an unavailable source or contradictory release metadata. Without those branches, an agent may produce the requested shape while filling important gaps with assumptions.
Keep the output requirements observable. “Be thorough” is difficult to assess. “List the comparison inspected, identify unavailable checks and distinguish evidence from inference” gives both the agent and reviewer something concrete to inspect.
Use References, Templates and Scripts Deliberately
Supporting files should each have a reason to exist. A reference document might explain the team’s release categories, while an asset provides an approved output template. A script might validate that the draft includes the required sections without trying to decide whether its factual claims are true.
Tell the agent when to consult each file. Loading a long policy document for every small edit can waste attention, while never referencing it can leave the relevant rule unused. Our guide to context engineering explores this wider problem of selecting the right information at the right point in a task.
Document script inputs, outputs and dependencies. If a script fails, the skill should preserve the error and explain which check remains incomplete. A failed validation must not be translated into a successful check simply because the rest of the draft looks plausible.
Portability needs practical checks. A directory containing the right files may still depend on a package, path or tool unavailable in another environment. Test the actual target setup rather than assuming that copying the folder is the final step.
Test Activation Separately From Output Quality
A skill can fail before its procedure begins. The host may not discover it, the description may match the wrong request or the agent may choose another workflow. Start by confirming that the skill is available, then use an explicit invocation to test the procedure itself.
Next, test natural requests without naming the skill. For the release example, try a direct release-note request and an indirect request to explain what changed for customers. Also try a general code-review question that should not activate the release workflow.
Keep a few difficult cases in the test set: an unspecified comparison, an empty release, a change that is still behind a flag and a comparison containing internal maintenance only. Write down the expected behavior before running each case. These are suggested evaluation cases, not measured claims about a particular agent.
Review the evidence behind the output as well as its formatting. A perfectly organized summary can still invent deployment status or omit an important limitation. Repeat the same cases after changing the description or procedure, and check whether an improvement in one case caused a regression elsewhere.
Our guide to evaluating AI agents covers broader outcome checks. For a skill, the immediate question is whether the same recognizable task produces a more dependable and reviewable result.
Review Skills as Executable Workflow Dependencies
Anthropic’s security guidance recommends auditing the whole skill bundle, including scripts and external references. A malicious or compromised skill can try to misuse the tools the agent already has. A reassuring name and a readable front page do not establish what every supporting file will do.
Inspect a new package before using it with valuable data or production access. Check whether network calls, file access and requested dependencies fit the stated task. Keep credentials out of templates and reference files, and use the host’s permission controls to limit what the workflow can actually reach.
For the release example, begin with access sufficient to inspect changes and draft text. Adding publication later should be a deliberate change with a clear destination and authorization policy. An instruction saying “draft only” is useful guidance, but it does not replace a technical restriction on a publishing tool.
Version the skill and retain a small set of test cases. When a recurring failure appears, change the narrow instruction responsible and rerun the relevant checks. A useful skill should become easier to understand as it improves, with a clear purpose, explicit failure behavior and evidence that its procedure helps.
