// Create or update Agent Skills (SKILL.md plus optional scripts, references, or assets). Use when someone asks to design a new Agent Skill, refine an existing one, or structure skills for Pi discovery, packaging, or other Agent Skills-compatible clients.
Guide for changing or extending Pi's behaviour. Use when someone wants to modify how Pi behaves, add capabilities, decide which Pi extension point or artifact to use, build or package an extension, create an Agent Skill, add prompt templates/themes/context/model providers, configure Pi resources, or asks whether a Pi internal patch is needed.
Long-running iterative development loops with pacing control and verifiable progress. Use when tasks require multiple iterations, many discrete steps, or periodic reflection with clear checkpoints; avoid for simple one-shot tasks or quick fixes.
| name | skill-creator |
| description | Create or update Agent Skills (SKILL.md plus optional scripts, references, or assets). Use when someone asks to design a new Agent Skill, refine an existing one, or structure skills for Pi discovery, packaging, or other Agent Skills-compatible clients. |
Provide guidance for creating effective Agent Skills that Pi and other compatible agent clients can load. Use Agent Skill / Agent Skills terminology, and keep Pi-specific discovery or packaging notes clearly scoped to Pi.
name, description. Directory name must equal name.license, compatibility, metadata (arbitrary key-value pairs for tooling), allowed-tools (experimental; support varies by client).disable-model-invocation: when set, Pi will not auto-trigger the skill; the user must invoke it explicitly with /skill:name.{baseDir} placeholders are not supported.~/.pi/agent/skills/, ~/.agents/skills/, .pi/skills/, .agents/skills/, package skills entries, settings skills, or --skill <path>.agent-skill/
├── SKILL.md
├── README.md # Optional: human summary + installation
├── scripts/ # Optional executables
├── references/ # Optional docs loaded on demand
└── assets/ # Optional templates/assets
2–4 concrete example requests usually suffice to scope triggers and functionality.
For each example, decide if you need:
An Agent Skill needs a directory containing a SKILL.md. Only add resource sub-directories that are actually needed.
mkdir -p ~/.pi/agent/skills/my-skill
touch ~/.pi/agent/skills/my-skill/SKILL.md
Use .agents/skills/ when you want the same skill directory to be naturally discoverable by other Agent Skills-compatible clients too.
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.
# My Skill
Short summary for humans discovering the skill.
## Installation
`pi install git:github.com/org/my-skill`
Use only the fields you need. In Pi, automatic loading is driven by description, so put when-to-use triggers there.
---
name: my-skill
description: What it does + when to use it.
---
If you need to hide auto-invocation in Pi, set:
disable-model-invocation: true
SKILL.md is the agent's interface to the skill.
scripts/validate_skill.py from this skill-creator directory (uses uv via a PEP 723 shebang, so PyYAML is provisioned in an ephemeral environment — no system install needed):scripts/validate_skill.py /path/to/my-skill
# or, equivalently:
uv run scripts/validate_skill.py /path/to/my-skill
pi --no-skills --skill /path/to/my-skill
/skill:my-skill
/reload.When the user wants to share an Agent Skill with Pi users, read references/PUBLISHING.md. In short: make it installable with pi install from npm, git, or a local source; use either a package.json pi.skills manifest or the conventional skills/ directory; Pi does not use .skill archives.