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)

• Clarify scope: Identify what the skill should do and the trigger phrases that should load it.

• Plan resources: Decide which logic belongs in scripts, references, or assets instead of SKILL.md.

• Write the skill: Add frontmatter, concise instructions, and links to references (one level deep).

• 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.