Frank
651924a4bc
Three parallel trees documented the same ecosystem: omp-docs/skills/
(two overview pages), tools/npx-skills/ (10 pi-era npm pages), and
tools/vercel-labs-skills/ (11 CLI pages), plus a fourth leaderboard page
at engineering/skills-ecosystem.md. Verbatim overlap (identical SKILL.md
field tables in skills-spec.md vs skill-format.md; 13-agent vs 68-agent
copies of the same upstream table). Consolidated to four concept pages:
- skills/agent-skills.md: standard, format, loading, authoring (merges
skills-spec, skill-format, skill-file-structure, skill-loading,
best-practices, skills-vs-extensions)
- skills/skills-cli.md: CLI reference (merges commands, source-formats,
installation-scope, skill-discovery, lock-file, env-variables,
agent-support, related-links)
- skills/store-wiring.md: moved, fleet ops, links retargeted
- skills/ecosystem.md: replaces skills-ecosystem.md; stale 2026-08-12
top-50 table dropped, replaced with a live top-10 re-queried from the
skills.sh API tonight and the API contract re-verified (zero-based,
200/page, {skills,total,hasMore,page}, total 9909)
All facts re-verified 2026-10-19 against primary sources:
agentskills.io, vercel-labs/skills README + src/cli.ts (command set,
--full-depth) + src/skill-lock.ts (v3 lock, XDG path, wipe-on-old),
live skills.sh API. Deleted superseded core/index-doc.md (old pi-era
docs index). Retargeted all inbound links (tools/index, engineering x3,
packages x3, pi/skills, core/index). Pi-era npm skill packaging is
listed as archived under /pi/.
Refs #29
106 lines
4.7 KiB
Markdown
106 lines
4.7 KiB
Markdown
---
|
|
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.
|