--- title: "Agent Skills" description: "Packaging reusable agent instructions, scripts, references, and assets." url: "https://agentsurface.dev/docs/discovery/agent-skills" lastVerified: 2026-09-24 lastModified: 2026-09-25T05:46:01.000Z --- 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 [#folder-shape] A portable skill is a folder with a `SKILL.md` entrypoint: ```text create-api-token/ ├── SKILL.md ├── references/ │ └── scopes.md ├── scripts/ │ └── validate-token.ts └── assets/ └── token-flow.png ``` `SKILL.md` carries metadata and the primary instructions: ```markdown --- 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 [#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: | Weak | Better | | ------------- | ---------------------------------------------------------------------------------------------------- | | API tokens | Use when an agent needs to create, validate, or rotate scoped API tokens for automation. | | Design review | Use when reviewing a rendered web page for visual, responsive, and interaction issues. | | Migration | Use when preparing a database migration PR with schema diff, rollback notes, and verification steps. | 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 [#publishing-skills] For public sites, expose a skill index: ```json { "$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: ```text /.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 [#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](https://agentskills.io) 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](/docs/agents/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-vs-other-files] | File | Role | | --------------- | ------------------------------------------------------------ | | `AGENTS.md` | Repository-level operating instructions for coding agents. | | `llms.txt` | Site/docs index for retrieval. | | `SKILL.md` | Task-specific instructions, scripts, references, and assets. | | MCP server card | Connection metadata for a tool server. | | OpenAPI | HTTP API contract. | Skills complement MCP. MCP exposes callable tools; skills teach an agent when and how to use a workflow. ## Related [#related] * [Reference Links](/docs/reference-links) * [Well-Known Endpoints](/docs/discovery/well-known-endpoints) * [Browser and Sandboxes](/docs/agents/browser-and-sandboxes) * [Agent Knowledge Packaging](/docs/cli-design/agent-knowledge-packaging) * [Context Files](/docs/context-files)