| name | frontmatter |
| description | Pi skill frontmatter reference and template. Use when creating or reviewing project skills so they conform to Pi's Agent Skills frontmatter rules, naming constraints, and description requirements. |
| compatibility | Intended for Pi skills stored in .agents/skills, .pi/skills, or compatible Agent Skills directories. |
Skill Frontmatter
Purpose
Use this skill when creating or reviewing SKILL.md files for Pi.
Required Frontmatter
Every skill must begin with frontmatter like:
---
name: example-skill
description: Specific description of what the skill does and when to use it.
---
Rules
name
- required
- 1-64 characters
- lowercase letters, numbers, hyphens only
- no leading or trailing hyphens
- no consecutive hyphens
- must match the parent directory name
description
- required
- max 1024 characters
- should clearly say what the skill does and when to use it
- missing descriptions prevent the skill from loading
Optional fields
licensecompatibilitymetadataallowed-toolsdisable-model-invocation
Unknown frontmatter fields are ignored, but keeping frontmatter minimal is better.
Recommended Template
---
name: skill-name
description: What this skill does and when to use it. Be specific.
compatibility: Optional environment or repo constraints.
---
# Skill Name
## Use When
- condition 1
- condition 2
## Workflow
1. Step one.
2. Step two.
3. Step three.
## References
- `relative/path/to/file`
Review Checklist
Before finalizing a skill:
- Confirm the directory name matches
name exactly.
- Confirm the description is specific enough for the model to load it appropriately.
- Confirm the skill uses relative references where possible.
- Keep instructions focused on a real repeatable workflow, not a task log.
Source Reference
Pi frontmatter rules are documented in:
~/development/pi-mono/packages/coding-agent/docs/skills.md
