skill-creator

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.

Skill Creator

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.

Agent Skills format (Pi-compatible)

• 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 (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.
• Paths are relative to the skill directory; {baseDir} placeholders are not supported.
• Pi loads Agent Skills from ~/.pi/agent/skills/, ~/.agents/skills/, .pi/skills/, .agents/skills/, package skills entries, settings skills, or --skill <path>.

Recommended structure

agent-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

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.

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.

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

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 will not 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.

• scripts/: document each command the agent may call, including inputs and outputs; scripts should be executable.
• references/: link each file from SKILL.md with when to read it; keep references one level deep and avoid duplicating facts.
• assets/: mention only when a workflow needs a specific template, boilerplate, or data file.

8) Validate and test

• Run the bundled validator at 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). A skill needs only SKILL.md; README.md remains optional:

scripts/validate_skill.py /path/to/my-skill
# or, equivalently:
uv run scripts/validate_skill.py /path/to/my-skill

• Before publishing a human-facing package, opt into the stricter README and Installation-section checks:

scripts/validate_skill.py --require-readme /path/to/my-skill

• Load only the skill in Pi to spot warnings:

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

• Invoke it explicitly:

/skill:my-skill

• After edits, use /reload.

9) Publish (optional)

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.