skills/pi-agent/references/skills.md
Source: https://pi.dev/docs/latest/skills
Pi implements the Agent Skills standard. Skills are self-contained capability packages loaded on demand, providing workflows, setup instructions, helper scripts, and reference documentation. Pi warns about most spec violations but stays lenient — notably it allows a skill name that differs from its parent directory, because the standard's matching rule is awkward for skill directories shared across harnesses.
Global:
~/.pi/agent/skills/~/.agents/skills/Project, only after project trust:
.pi/skills/.agents/skills/ in cwd and ancestors, up to the git repo root (or filesystem root outside a repo)Also: packages (skills/ directories or pi.skills entries in package.json), the skills settings array, and CLI --skill <path> (repeatable, additive even with --no-skills).
Discovery rules:
~/.pi/agent/skills/ and .pi/skills/, direct root .md files are discovered as individual skills.SKILL.md are discovered recursively.~/.agents/skills/ and project .agents/skills/, root .md files are ignored.To reuse skills from other harnesses, add their directories to settings:
{ "skills": ["~/.claude/skills", "~/.codex/skills"] }
At startup Pi scans skill locations and extracts names and descriptions. The system prompt includes available skills in XML format per the specification. When a task matches, the agent uses read to load the full SKILL.md (models do not always do this — prompt explicitly or force with /skill:name) and follows the instructions using relative paths. Only descriptions stay in context; full instructions load on demand.
Skills register as /skill:name; arguments after the command are appended as User: <args>. Toggle via /settings or "enableSkillCommands": true.
/skill:brave-search
/skill:pdf-tools extract
my-skill/
SKILL.md # required: frontmatter + instructions
scripts/process.sh
references/api-reference.md
assets/template.json
Use relative paths from the skill directory.
| Field | Required | Constraints |
|---|---|---|
name | Yes | Max 64 chars, lowercase a–z, 0–9, hyphens. Pi does not require it to match the parent directory. |
description | Yes | Max 1024 chars — what the skill does and 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. |
allowed-tools | No | Space-delimited pre-approved tools (experimental). |
disable-model-invocation | No | true hides the skill from the system prompt; users must call /skill:name. |
Name rules: 1–64 characters, lowercase letters/numbers/hyphens, no leading or trailing hyphen, no consecutive hyphens. Valid: pdf-processing. Invalid: PDF-Processing, -pdf, pdf--processing.
Most violations warn but still load: over-length or invalid names, leading/trailing/consecutive hyphens, description over 1024 chars. Unknown frontmatter fields are ignored. Exception: a missing description prevents loading. Name collisions across locations warn and keep the first skill found.
Skills can instruct the model to perform any action and may include executable code the model invokes. Review skill content before use.