---
type: concept
title: The Agent Skills Standard
description: "The open Agent Skills standard: SKILL.md format, frontmatter fields, directory structure, progressive-disclosure loading, authoring practice, and how skills differ from extensions."
tags:
  - skills
  - agent-skills
  - specification
  - authoring
timestamp: 2026-10-19
verified: 2026-10-19
---

# The Agent Skills Standard

A **skill** is a directory containing a `SKILL.md` file: YAML frontmatter
(`name` + `description`) followed by markdown instructions, plus optional
`scripts/`, `references/`, and `assets/`. The standard is maintained at
[agentskills.io](https://agentskills.io) and adopted by 79 coding agents
(upstream agent registry, checked 2026-10-19), so one skill works across
harnesses. The `skills` CLI installs them; see
[Skills CLI](/skills/skills-cli.md).

## SKILL.md format

```markdown
---
name: my-skill
description: What the skill does and when to use it.
---

# My Skill
Instructions the agent follows when the skill activates.
```

### Frontmatter fields

| Field | Required | Notes |
|-------|----------|-------|
| `name` | yes | Max 64 chars; lowercase `a-z`, `0-9`, hyphens; no leading/trailing or consecutive hyphens (`pdf-processing` good, `PDF-Processing`, `-pdf`, `pdf--processing` bad). Pi does not require the name to match the parent directory; the standard does. |
| `description` | yes | Max 1024 chars. The only text the agent sees when deciding whether to activate the skill. First sentence: what it does. Second: when to use it. |
| `license` | no | License name or reference to a bundled file. |
| `compatibility` | no | Max 500 chars; environment requirements. |
| `metadata` | no | Arbitrary key/value mapping. `metadata.internal: true` hides the skill from discovery unless `INSTALL_INTERNAL_SKILLS=1` (skills CLI convention). |
| `allowed-tools` | no | Space-delimited pre-approved tools (experimental; agent support varies — Zencoder and Kiro do not implement it). |
| `disable-model-invocation` | no | When `true`, the skill is hidden from the system prompt; users invoke it explicitly (`/skill:name`). |

### Directory structure

```
my-skill/
├── SKILL.md       # Required entry point
├── scripts/       # Helper scripts (bash, js, python, ...)
├── references/    # Detailed docs, loaded on demand
├── assets/        # Templates, configs, binary data
└── config.json    # Optional skill settings
```

Everything except `SKILL.md` is freeform. Scripts save tokens and improve
reliability when the same code would otherwise be regenerated per run.

## Loading: progressive disclosure

Harnesses (pi, omp, Claude Code, ...) load skills the same way:

1. At startup, scan configured skill locations; extract `name` + `description` only.
2. Inject the metadata list into the system prompt.
3. On a matching task, the agent reads the full `SKILL.md` and follows it,
   referencing bundled scripts by relative path.

Only descriptions live in context permanently; full instructions load on demand.
On omp the load order is priority-ranked: authored `agent/skills/` (100) beats
the `~/.agents` store provider, which beats auto-learned
`agent/managed-skills/` (5). See [Skill Store Wiring](/skills/store-wiring.md).

## Skills vs extensions

| | Skills | Extensions |
|---|--------|------------|
| Format | Markdown (`SKILL.md`) + scripts | TypeScript (`.ts`) |
| Purpose | Instructions for the model | Code intercepting events, registering tools |
| Execution | The agent reads and follows | Runs in the harness runtime |
| Loading | On demand | Always loaded at startup |
| Trust model | Review the text (it instructs the model) | Review the code (it executes) |

A harness package may bundle both (pi did; omp extensions live in
`agent/extensions/`).

## Authoring practice

- Descriptions beat clever bodies: activation depends entirely on the description matching the user's words. "Extracts text and tables from PDF files, fills forms, merges documents" beats "Helps with PDFs."
- Keep `SKILL.md` focused; push long detail into `references/` (files load whole; split past roughly 500 lines).
- Skills instruct the model to run arbitrary commands, and scripts run with full user permissions. Review content before installing from untrusted sources.
- Document dependencies (tools, API keys, setup steps) inside the skill.

## Citations

- [Agent Skills specification](https://agentskills.io) — re-fetched 2026-10-19.
- [vercel-labs/skills README](https://github.com/vercel-labs/skills) — compatibility matrix, re-fetched 2026-10-19.

## See Also

- [Skills CLI](/skills/skills-cli.md) — install/use/update tooling.
- [Skill Store Wiring](/skills/store-wiring.md) — how the fleet provisions skills.
- [Skills Ecosystem](/skills/ecosystem.md) — registries and leaderboards.