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:

• scripts/ for deterministic tasks
• references/ for long docs or schemas
• assets/ for templates or boilerplate

3) Create the skeleton

A skill needs a directory containing a SKILL.md. Only add resource sub-directories that are actually needed.

bash
mkdir -p ~/.pi/agent/skills/my-skill
touch ~/.pi/agent/skills/my-skill/SKILL.md

4) Optional: Write README.md (humans + installation)

If you plan to share the skill with humans, a README.md helps discovery and installation. If you have a README, installation info can live there to save space in SKILL.md.

markdown
# My Skill

Short summary for humans discovering the skill.

## Installation
`pi install git:github.com/org/my-skill`

5) Write frontmatter

Use only the fields you need.

markdown
---
name: my-skill
description: What it does + when to use it.
---

If you need to hide auto-invocation, set:

yaml
disable-model-invocation: true

6) Write the body

• Imperative phrasing works well for procedural instructions; context framing works better for guidance (see Principles).
• ~500 lines is a practical ceiling for SKILL.md; beyond that, split content into references.
• The agent won't know a reference file exists unless SKILL.md says when to read it.

7) Add resources

SKILL.md is the agent's interface to the skill — usage examples and input/output descriptions let it call scripts without needing to understand internals.

• scripts/: usage examples in SKILL.md inform the agent how to call them; scripts should be executable.
• references/: a table of contents helps the agent navigate files longer than ~100 lines. References work best one level deep from SKILL.md, and each fact should live in one place (SKILL.md or a reference, not both).
• assets/: templates, boilerplate, or data used in final output — typically not loaded into context.

8) Validate and test

• Run the validator script:

bash
scripts/validate_skill.py /path/to/my-skill

• Load only the skill to spot warnings:

bash
pi --no-skills --skill /path/to/my-skill

• Invoke it explicitly:

bash
/skill:my-skill

• After edits, use /reload.

9) Publish (optional)

To share beyond a single machine, publish as a Pi package (package.json-based, not a .skill archive).

• Add package.json with a pi manifest (or rely on the conventional skills/ directory).
• Add "keywords": ["pi-package"] for discoverability.
• Publish to npm or host in git; install with pi install <source> and enable via pi config if needed.

json
{
  "name": "my-pi-skills",
  "keywords": ["pi-package"],
  "pi": { "skills": ["./skills"] }
}