| name | skill-writter |
| description | Always load when you need to write some skill. |
Naming: lowercase hyphens, 1-64 chars, matches folder
Frontmatter:
---
name: skill-name
description: What it does/ When to load
---
Tips:
- Keep under 50 lines
- Use code examples sparingly
- Prefer simple list of rules
- Do not repeat yourself.
- Description helps agent decide when to use
- Frontmatter must match directory name; quote any values containing
: or other YAML-sensitive characters
- Can reference other skills - agent can load them with
skill(name="other-skill")
- In
.pi/agent/skills/ — e.g., ~/.pi/agent/skills/skill-name/SKILL.md
Trigger (Most Important)
The description is the trigger - it tells the agent WHEN to use this skill.
Good triggers:
- "Use when user asks to analyze a task and create a subagent delegation plan"
- "Use when staging or committing"
- "Use when user wants to create, read, edit, or manipulate Word documents"
Bad triggers:
- "Does X" - too vague
- "Helps with Y" - passive, unclear when to activate
- "For Z tasks" - ambiguous
Rule: Write the trigger as "Use when..." in present tense. Specific enough to avoid false matches, general enough to catch all relevant cases.
Checklist:
- Could you write "Use when..." before the description?
- Does it match actual user requests you've seen?
- Will the agent recognize it without ambiguity?
- Is it more specific than "anything related to X"?
Testing
After writing a skill, verify it loads correctly:
- Read the file to check frontmatter matches directory name
- Check syntax (valid YAML frontmatter, no obvious markdown errors)
- Test in context: ask the agent to use the skill
- Check that description triggers loading correctly