command-center/omp-docs/skills/agent-skills.md

type, title, description, tags, timestamp, verified

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

SKILL.md format

---
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 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 — re-fetched 2026-10-19.
• vercel-labs/skills README — compatibility matrix, re-fetched 2026-10-19.

See Also

• Skills CLI — install/use/update tooling.
• Skill Store Wiring — how the fleet provisions skills.
• Skills Ecosystem — registries and leaderboards.