Skill Creator

Skill Creator

Provide guidance for creating effective Pi skills.

Principles

• Conciseness: the agent is already very capable - only domain-specific knowledge, workflows, and tooling it can't infer earn their token cost.
• Progressive disclosure: Pi loads skills in tiers - frontmatter (always in context), body (on trigger), bundled resources (on demand) - so splitting content across them keeps context lean.
• Activation: Pi decides whether to load a skill based solely on the frontmatter description. "When to use" information in the body comes too late.
• Context over directives: the agent makes better decisions when it understands why. For tasks requiring judgment, context like "X helps Y because Z" is more robust than instructions like "You MUST do X".

Pi Agent Skills format

• Required frontmatter: name, description. Directory name must equal name.
• Name rules: 1–64 chars, lowercase letters/digits/hyphens, no leading/trailing/consecutive hyphens.
• Optional frontmatter: license, compatibility, metadata (arbitrary key-value pairs for tooling), allowed-tools (restrict which tools the skill may invoke).
• disable-model-invocation: when set, Pi won't auto-trigger the skill; the user must invoke it explicitly with /skill:name.
• Paths are relative to the skill directory; {baseDir} placeholders are not supported.
• Skill locations: ~/.pi/agent/skills/, .pi/skills/, skills/ in a package, settings skills, or --skill <path>.

Recommended structure

pi-skill/
├── SKILL.md
├── README.md         # Optional: human summary + installation
├── scripts/          # Optional executables
├── references/       # Optional docs loaded on demand
└── assets/           # Optional templates/assets

Workflow

1) Clarify use cases

2-4 concrete example requests usually suffice to scope triggers and functionality.

2) Plan reusable resources

For each example, decide if you need: