Agent Skills

Agent Skills are portable capability folders for agents. A skill teaches an agent how to do a specific task without putting every instruction into the base prompt.

Use Agent Skills when a workflow is repeatable, procedural, and specific enough that a general docs page is not enough. Good skills are narrow: "create a scoped API token", "run the design review workflow", "prepare a migration PR". They are not broad knowledge dumps.

Folder Shape

A portable skill is a folder with a SKILL.md entrypoint:

create-api-token/
├── SKILL.md
├── references/
│   └── scopes.md
├── scripts/
│   └── validate-token.ts
└── assets/
    └── token-flow.png

SKILL.md carries metadata and the primary instructions:

---
name: create-api-token
description: Use when an agent needs to create a scoped API token for automation.
---

# Create API Token

## Steps

1. Read `references/scopes.md`.
2. Ask for the minimum required scope.
3. Create the token through the settings API.
4. Run `scripts/validate-token.ts` before returning it to the caller.

## Safety

- Never create admin-scoped tokens unless explicitly requested.
- Never print token values into logs.

The name and description fields are the minimum portable metadata. Add scripts, references, and assets only when they help the agent perform the task correctly.

Progressive Disclosure

Skills work because agents can index a lightweight catalog first, then load the full skill only when needed.

That means descriptions matter. Write them as routing instructions:

Do not inline every workflow into a catalog file. Point to the skill and let the agent load details only when the task calls for it.

Publishing Skills

For public sites, expose a skill index:

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "create-api-token",
      "type": "skill-md",
      "description": "Use when an agent needs to create a scoped API token for automation.",
      "url": "https://example.com/.well-known/agent-skills/create-api-token/SKILL.md",
      "digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  ]
}

Publish it at:

/.well-known/agent-skills/index.json

This is the discovery v0.2 shape. type: skill-md means the URL returns a SKILL.md document directly. digest is the SHA-256 of the exact bytes returned by that URL, including line endings. Recompute it whenever the artifact changes.

Validate discovery as a chain, not as two unrelated files:

1. Parse the index against its declared schema.
2. Fetch each skill URL and reject redirects to login pages, HTML shells, placeholders, or empty bodies.
3. Hash the fetched bytes and compare them with digest.
4. Parse the SKILL.md frontmatter and require name and description.
5. Confirm that the description explains when the skill should be activated.

Only publish skills that are real, reviewed, and kept current with the product. An index returning HTTP 200 does not count when its skill is stale, malformed, or does not match the published digest.

Runtime Consumption

Skills started as a coding-CLI convention: a folder an assistant reads off disk while you work in a repository. That is no longer the only consumer. The Agent Skills specification is now loaded at runtime by agent frameworks, which point a workspace at one or more skill directories and expose them to the agent as tools, and by hosted model platforms, which attach skill folders directly to a platform-managed execution environment and unpack them server-side.

Only the catalog - each skill's name and description - goes into the system message; the body of a skill and its supporting files cost nothing until the agent calls for them. That is the same progressive-disclosure economics described above, and it is why description has to work as a routing instruction for a running agent, not only as a label a human scans.

See Frameworks for how a given runtime wires skill directories into tool calls. The format - the folder, SKILL.md, and its frontmatter - is what stays portable across a CLI, a framework workspace, and a hosted platform runtime.

Skills Vs Other Files

Skills complement MCP. MCP exposes callable tools; skills teach an agent when and how to use a workflow.

Related

• Reference Links
• Well-Known Endpoints
• Browser and Sandboxes
• Agent Knowledge Packaging
• Context Files