| name | skills-md |
| description | Use this skill before creating/modifying any skill (global, project, or package-level). It defines hard rules for writing tight, information-dense `SKILL.md` files, valid frontmatter, and when to move details into `references/` or `scripts/`.
|
Skill authoring rules (mandatory)
Use before any create/edit/move/split of SKILL.md.
Locations
Apply these rules to skills loaded from:
- global (source of truth in this setup):
~/.dotfiles/pi/agent/skills/ (synced to ~/.pi/agent/skills/)
- project:
.pi/skills/
- package-provided skill directories
- custom paths from settings
skills entries or CLI --skill
SKILL.md requirements
- Hard cap: 500 tokens max.
- Frontmatter must include
name and description.
name must match parent directory and use lowercase letters/numbers/hyphens.description should state when to use the skill, why it exists, and what it covers.- Keep body terse, imperative, and action-oriented.
- Put only the default/high-value path in
SKILL.md.
- Avoid duplicating global guidance or other skills; reference instead.
references/ and scripts/
- Use
references/*.md for progressive disclosure (edge cases, deep dives, examples, troubleshooting).
- Use
scripts/ for reusable runnable helpers.
- In
SKILL.md, explicitly say when to consult a reference or run a script.
Quality gate
Before finishing, verify:
- Common-case execution is possible from
SKILL.md alone.
- Every line has operational value (no filler).
- Wording is clear, firm, and unambiguous.
If you changed a skill
Summarize: (1) what changed, (2) why this scope/structure.
