Skill Authoring Best Practices

Use this skill when you need to create or refactor a pi skill. Keep it short and defer to the canonical reference for full rules and examples.

Canonical Reference

Follow the full specification and patterns here:

• agent/skills/pi/references/skills.md

Only repeat details in this file when they are essential to the current task.

Authoring Workflow (Condensed)

1. Clarify scope: Identify what the skill should do and the trigger phrases that should load it.
2. Plan resources: Decide which logic belongs in scripts, references, or assets instead of SKILL.md.
3. Write the skill: Add frontmatter, concise instructions, and links to references (one level deep).
4. Validate and iterate: Use the skill on real tasks, note friction, and tighten wording.

Content Placement Heuristics

• SKILL.md: Overview, decision points, and minimal instructions.
• references/: Deep guides, specs, or domain docs the agent should read on demand.
• scripts/: Deterministic code you don’t want rewritten every time.
• assets/: Files used in outputs (templates, logos, etc.).

Red Flags

• Duplicate information between SKILL.md and references.
• Long explanations of obvious concepts.
• Extra docs (README, changelog) that won’t be used by the agent.