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.

Provide guidance for creating effective Pi skills.

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

Required frontmatter: name, description. Directory name must equal name.
Name rules: 1–64 chars, lowercase letters/digits/hyphens, no leading/trailing/consecutive hyphens.