How Agent Skill Works

An agent skill works by packaging task-specific instructions in a discoverable folder, then loading those instructions only when the user's task matches the skill. The short version: the agent first sees lightweight metadata, decides whether the skill applies, reads SKILL.md, opens any needed supporting files, optionally runs bundled scripts or external tools, and returns evidence that the workflow actually completed.

That mechanism is simple on purpose. OpenAI describes a Codex skill as a directory with a required SKILL.md file plus optional scripts/, references/, and assets/. Anthropic's Agent Skills documentation uses the same basic model: a skill packages instructions, metadata, and optional resources that load when relevant. The open Agent Skills specification gives the shared shape: metadata first, full instructions second, bundled resources only when needed.

That makes skills different from a long prompt pasted into every session. A prompt is immediate context. A skill is stored capability that waits until a matching task pulls it into the run.

A skill usually moves through seven runtime stages:

Stage	What the agent sees or does	Failure mode
Discovery	Reads the skill name, description, and path	Description is too broad, too clever, or missing trigger words
Activation	Decides the user task matches the description	Skill fires for adjacent work or fails to fire for the real use case
Instruction loading	Reads the full SKILL.md body	Instructions are vague, contradictory, or too buried
Resource loading	Opens selected files from references/, assets/, or examples	Large files crowd out the task, or useful examples are hard to find
Execution	Follows the workflow and calls tools when required	The skill describes judgment but not concrete steps
Helper execution	Runs scripts, templates, or deterministic checks where useful	Code is unsafe, unavailable, undocumented, or unnecessary
Verification	Reports proof: files, commands, sources, diffs, screenshots, eval results, or blockers	The final answer sounds confident but cannot be inspected

For the broader category, see what an agent skill is. The mechanical question is narrower: how does the agent get from "a skill exists" to "this run used the skill correctly"?

The center of the package is SKILL.md. It has two jobs.

First, it exposes metadata. At minimum, a skill needs a name and description. Those fields are not decorative. In Codex, the initial skills list is constrained so it does not consume too much context, and implicit activation depends heavily on the description field. OpenAI's docs advise front-loading the key use case and trigger words because long descriptions may be shortened in large skill sets.

Second, SKILL.md contains the instructions the agent follows after activation. The body should tell the agent what to inspect, what order to work in, what tradeoffs matter, what tools are allowed or required, and what evidence belongs in the final response. A good file reads less like brand copy and more like a field manual.

Weak metadata:

Useful metadata:

The second version gives the agent matching handles: primary-source docs, changelogs, community reports, cited briefing, confirmed facts, implementation risks. It also narrows the boundary. A request for a slogan or a sales email should not trigger it.

The body has a different job. It should be explicit enough to change behavior:

## Workflow

1. Start with official documentation and changelogs.
2. Use community reports only to identify practical failure modes.
3. Separate confirmed behavior from inference.
4. Link every version-sensitive claim near the sentence it supports.
5. End with a "verified / uncertain / blocked" summary.

That is the difference between a skill that labels the work and a skill that drives the work. A description gets the skill selected. The body changes how the agent reasons through the task.

Progressive disclosure is the loading pattern that makes skills scale. The agent does not read every installed skill in full before every answer. It starts with small metadata. If a task matches, it loads the chosen skill's instructions. If the instructions point to supporting material, it opens only the files needed for that run.

OpenAI's Codex skills documentation describes this directly: Codex starts with each skill's name, description, and file path, then reads the full SKILL.md only when it decides to use that skill. The Agent Skills specification describes the same three layers: metadata, instructions, and resources. Anthropic's engineering post on equipping agents with skills frames progressive disclosure as the reason a skill can carry procedural knowledge without forcing all of it into every request.

That matters because context is an operating budget. If every brand guide, test harness note, data dictionary, and release checklist lived in the always-on prompt, the agent would spend attention on irrelevant material. With a skill, a salesforce-migration-review task can load migration checklists and schema examples, while a pdf-redaction task can load document-processing instructions and ignore the Salesforce material entirely.

Progressive disclosure also changes how a skill should be written. Put the highest-value rules in SKILL.md. Move long, situational detail into references/. Keep examples easy to find, but not so large that every run pays for them.

A skill is a folder, not just a Markdown file. The exact conventions vary by host application, but the common layout is:

my-skill/
  SKILL.md
  references/
    rubric.md
    api-notes.md
  scripts/
    validate-output.js
  assets/
    report-template.md
  examples/
    good-brief.md
    bad-brief.md

references/ is for material the agent may read: rubrics, schemas, policy excerpts, migration notes, brand rules, examples, or domain background. The Agent Skills spec recommends focused reference files and relative links from SKILL.md, because agents load these files on demand.

assets/ is for reusable static material: templates, starter files, lookup tables, diagrams, configuration fragments, or report shells. If every incident report needs "Impact", "Timeline", "Detection", "Resolution", and "Preventive Action", put that template in assets/incident-report.md and tell the skill when to use it.

scripts/ is for executable helpers. That can be a validator, parser, converter, renderer, data cleaner, or repeatable setup step. Scripts are valuable when correctness depends on deterministic work. A legal-review skill might keep instructions in SKILL.md, a jurisdiction matrix in references/, and a script that checks whether required clauses are present. A design-token skill might use instructions to decide what to inspect, then run a script to compare CSS variables against a canonical token file.

Examples deserve special treatment. The Anthropic public skills repository describes skills as folders of instructions, scripts, and resources, and its published examples show how concrete artifacts make behavior easier to understand. A single good example can anchor tone, depth, and output shape better than another paragraph of instruction.

The most common design mistake is treating a skill as either all prose or all automation. It should usually be both, but each part has a different responsibility.

Instructions are for judgment. They tell the agent how to choose sources, sequence work, handle ambiguity, respect constraints, and decide what "done" means. They can express tradeoffs: prefer primary docs over blog summaries; ask before destructive writes; do not change unrelated files; keep a human in the loop for payments; report unknowns instead of inventing a value.

Scripts are for repeatability. They do not judge whether a migration plan is good. They can parse the repository, count missing frontmatter fields, validate JSON, render a screenshot, extract headings, run a linter, or compare two exports.

The boundary is practical:

Need	Better as instructions	Better as script
Decide whether a source is primary	Yes	No
Parse 200 Markdown files for missing canonical paths	No	Yes
Weigh whether an MCP write action needs approval	Yes	Maybe as a policy check
Convert a CSV into normalized JSON	No	Yes
Explain tradeoffs in a customer-facing migration note	Yes	No
Verify that all generated files match a schema	No	Yes

For a skill author, the question is not "Can the model do this?" It is "Should this be left to model judgment every time?" If the answer is no, put the mechanical part in a helper.

A skill is not a tool. A tool is an action the agent can call. A skill is procedural knowledge about how to do a job. The distinction matters because teams often compare agent skills versus tools as if they compete. They usually stack.

The Model Context Protocol tools specification defines tools as model-invoked capabilities exposed by a server, with names, metadata, schemas, and results. MCP gives the agent a standardized way to interact with external systems such as databases, APIs, file stores, issue trackers, or internal services. A skill can tell the agent which MCP tool to use, when to call it, what input shape to pass, and what output should be considered sufficient evidence.

Example:

Layer	Concrete case
User request	"Review this GitHub PR for documentation drift."
Skill	A documentation-review workflow that says to inspect changed public APIs, route names, README claims, and release notes
MCP tool	GitHub file and PR-comment tools exposed through an MCP server
Script	A local heading extractor that compares docs headings against changed route files
Output	Findings with file paths, line references, missing docs, and verification commands

Without the tool, the agent may not have access to the PR. Without the skill, the agent may read the PR and still miss the workflow-specific judgment. For deeper protocol boundaries, compare agent skills and MCP: MCP standardizes access; skills standardize repeatable work.

This layering is also where security belongs. The MCP spec calls out clear tool exposure and human confirmation for risky operations. A skill should turn that into rules: read-only tools during diagnosis, explicit approval before billing, production-data, authentication, or customer-record writes, and final evidence after any approved write.

Consider a skill named api-migration-review. The package contains:

api-migration-review/
  SKILL.md
  references/
    migration-rubric.md
    deprecation-policy.md
  scripts/
    scan-breaking-changes.ts
  examples/
    accepted-review.md

The user asks: "Review this branch before we migrate customers from v1 webhooks to v2 webhooks." At discovery time, the agent sees the skill name and description. If the description mentions API migrations, webhook deprecations, compatibility checks, and release-readiness reviews, the match is likely. If it says "helps with backend work", the match is weak.

At activation time, the agent loads SKILL.md. The file tells it to inspect the migration diff, identify changed event names, check retry behavior, compare docs against route handlers, verify rollback instructions, open references/deprecation-policy.md only if public behavior changes, and run scripts/scan-breaking-changes.ts after reading the changed files.

During execution, the agent reads the diff, opens the policy, runs the scanner, compares tool output with its own review, and may call an MCP GitHub tool to inspect comments or CI status. It avoids deployment tools because the skill says review tasks are read-only unless the user explicitly requests deployment.

At verification time, the agent returns changed files reviewed, scanner command and result, confirmed compatible cases, suspected breaking cases, missing docs, and questions for the migration owner. If no breaking change is found, the answer should still show how that conclusion was reached.

This is why creating an agent skill should start from real runs. If the migration review always needs the same scanner, same policy file, same acceptance checklist, and same final evidence, those pieces belong in the skill.

A skill worked when it changed the agent's behavior in the intended direction and left evidence. That is more demanding than "the agent mentioned the skill."

Use five checks. Activation should be precise: the skill fires for the target job and stays quiet for unrelated work. Loading should be economical: the agent reads SKILL.md, then opens only relevant references or assets. Execution should show workflow adherence: inspect source before summarizing, run validation before claiming success, ask before destructive operations, and use primary docs before community commentary. Helper use should be justified: scripts and MCP tools appear when they reduce uncertainty or provide access, not as theater. The final output should be auditable: file paths, command summaries, links near supported claims, screenshots for UI work, test names, changed-file lists, and clearly labeled blockers.

For teams distributing skills through Skillfully, this is the measurement surface: did the skill activate for the right task, load the right references, use the right helpers, and produce reviewable evidence? Ratings and comments help, but the behavioral trace tells a skill author how to improve the package.

Not every skill needs scripts, assets, or MCP. An instruction-only skill is appropriate when the work is mostly judgment, review, facilitation, or writing under constraints.

A founder-interview skill may only need a questioning sequence, stop rules, and examples of strong synthesis. A code-review skill may start instruction-only if the repository already has test and lint commands the agent can discover. A customer-support-response skill may need style rules and escalation boundaries, not a parser.

Add bundled helpers when the same mechanical step appears repeatedly, when a validator would catch errors the model often misses, or when output must match a strict format. Add references for policy, domain knowledge, schemas, or long examples. Add assets when the run should produce a reusable artifact from a known template.

The tradeoff is maintenance. Every script can break, every reference can go stale, and every asset can encode an old brand or policy. A smaller skill is often better while the workflow is still changing. A richer package is worth it once the repeated work is stable enough to standardize.

The cleanest test for an agent skill is a before-and-after run against the same task. Without the skill, capture where the agent drifts: missed source, wrong order, unsupported claim, unsafe tool call, weak final proof, or inconsistent output format. With the skill installed, run the same task again and check whether those failures disappear.

The result does not need to be perfect to be useful. It needs to be attributable. If the agent now starts from official docs, opens the right rubric, runs the validator, refuses an unsafe write, and reports evidence, the skill is doing mechanical work. If the answer is merely longer, the package needs sharper triggers, clearer instructions, better examples, or a helper that removes guesswork.