| name | skill-authoring |
| topic | Pi Skill Authoring |
| description | Create SKILL.md files that teach the agent new domains. Use when authoring a new pi skill with frontmatter, body structure, and references. |
| token_cost | 200 |
| keywords | ["skill","author","create","improve","domain"] |
Pi Skills
Skills are Markdown files (SKILL.md) that teach the agent how to do something it doesn't know by default. Each skill covers one or more use cases within a single domain — e.g., "NixOS configuration management" with sub-areas for system updates, home manager, and package search. The agent loads the full file when the user's request matches the trigger description.
File Layout
my-skill/
├── SKILL.md # Frontmatter + workflow instructions (keep under 120 lines)
├── references/ # Deep docs loaded on demand (API specs, advanced patterns)
└── scripts/ # Helper scripts the agent runs directly
Assets go in assets/ for templates and files the agent uses in outputs. Scripts in scripts/ are deterministic code — not rewritten each invocation.
Frontmatter
Every skill requires name, description, and keywords. Additional fields depend on the skill type.
Required Fields
---
name: my-skill-name
description: "Does X. Use when Y."
keywords: ["keyword1", "keyword2", "keyword3"]
---
name: lowercase letters, numbers, hyphens only. No leading/trailing hyphens.description: quoted string. First sentence starts with a verb. Second starts with "Use when".keywords: array of single lowercase words used for scoring. Each word match scores 1.0 — you need at least 2 matches (score >= 2.0) for injection. Pick words users actually type. Avoid sharing keywords with other skills.
Optional Fields by Type
Tool skills (in tools/ directory, name = tool name):
related: [other-skill]
Knowledge skills (domain knowledge):
topic: State-Space Search
token_cost: 120
requires_tools: [read, find]
Protocol skills (behavioral rules):
topic: Conventional Commits
Body Structure (under 120 lines)
# Skill Name
One-line summary of the domain this skill covers.
## Workflow / Commands
Step-by-step examples or command reference with inline code snippets.
## Details
Common variations, edge cases, or tricky parts specific to this domain.
## Constraints / Best Practices
Rules, gotchas, and things the agent must do (or not do).
See [deep reference](references/DEEP.md) for API specs and advanced usage.
- Workflow/Commands: numbered steps with concrete inline examples — command, code snippet, or config.
- Details: short context for variations on the main use cases.
- Link to
references/ for anything deep. One level of linking only.
Examples from Existing Skills
Good — focused domain, multiple use cases:
description: "Switches NixOS/Home Manager configurations, cleans old generations, and performs system maintenance. Use when running os/home switch, pruning the Nix store, or managing system generations."
Good — single use case within a domain:
description: "Transcribes audio files to text using whisper-cpp. Use when converting speech to text, transcribing podcasts, lectures, or meetings."
Validation Checklist
Common Mistakes
- Description uses
> chevron instead of "quoted" — convert to quoted string
- Missing "Use when..." clause — add trigger conditions
- Duplicate content between SKILL.md and references — keep detail only in references
- Long explanations of concepts the agent already knows — delete them
- Extra files the agent never reads (README, changelog) — remove them
