Frank
02883d3ed2
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
71 lines
2.7 KiB
Markdown
71 lines
2.7 KiB
Markdown
---
|
|
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
|