---
type: reference
title: Agent Skills Specification
description: The Agent Skills standard that defines SKILL.md format, frontmatter fields, and cross-agent compatibility.
tags:
  - unverified
  - agent-skills
  - specification
  - npm
timestamp: 2026-07-18
verified: 2026-08-28
---

# Agent Skills Specification

Pi implements the [Agent Skills standard](https://agentskills.io/specification), warning about most violations but remaining lenient. The specification defines:

- A **frontmatter block** (YAML) at the top of `SKILL.md` with required `name` and `description` fields
- A **Markdown body** with the skill's instructions
- Optional subdirectories: `scripts/`, `references/`, `assets/`

The specification is designed to be **cross-agent-compatible**: skills written for pi work with Claude Code, Codex CLI, Amp, Droid, and other compatible agents.

## Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | **Yes** | Max 64 chars. Lowercase a-z, 0-9, hyphens only. No leading/trailing hyphens. No consecutive hyphens. |
| `description` | **Yes** | Max 1024 chars. What the skill does and when to use it. **This is the only thing the agent sees when deciding whether to activate the skill.** |
| `license` | No | License name or reference to bundled file. |
| `compatibility` | No | Max 500 chars. Environment requirements. |
| `metadata` | No | Arbitrary key-value mapping. |
| `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental). |
| `disable-model-invocation` | No | When `true`, skill is hidden from system prompt. Users must use `/skill:name` explicitly. |

### Name Rules

Valid: `pdf-processing`, `data-analysis`, `code-review`
Invalid: `PDF-Processing`, `-pdf`, `pdf--processing`

**Note:** Pi does not require the name to match the parent directory. The Agent Skills standard does, but that requirement is suboptimal for shared skill directories.

### Description Best Practices

The description determines when the agent loads the skill. Be specific.

**Good:**
```yaml
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
```

**Poor:**
```yaml
description: Helps with PDFs.
```

## Cross-Agent Compatibility

Skills follow a shared specification that works across:

- Pi (`~/.pi/agent/skills/`)
- Claude Code (`~/.claude/skills/`)
- Codex (`~/.codex/skills/`)
- OpenCode (`~/.config/opencode/skills/`)
- And [68+ other agents](/tools/vercel-labs-skills/agent-support.md)

## Related

* [Skill File Structure](/tools/npx-skills/skill-file-structure.md) — How to organize SKILL.md and its supporting files
* [Ecosystem](/tools/npx-skills/ecosystem.md) — Where to find community skills