co-mono/packages/coding-agent/docs/skills.md

pi can create skills. Ask it to build one for your use case.

Skills

Skills are self-contained capability packages that the agent loads on-demand. A skill provides specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks.

Pi implements the Agent Skills standard.

Table of Contents

• Locations
• How Skills Work
• Skill Commands
• Skill Structure
• Frontmatter
• Validation
• Example
• Skill Repositories

Locations

Pi loads skills from:

• Global: ~/.pi/agent/skills/
• Project: .pi/skills/
• Packages: skills/ directories or pi.skills entries in package.json
• Settings: skills array with files or directories
• CLI: --skill <path> (repeatable, additive even with --no-skills)

Discovery rules:

• Direct .md files in the skills directory root
• Recursive SKILL.md files under subdirectories

Disable discovery with --no-skills (explicit --skill paths still load).

How Skills Work

1. At startup, pi scans skill locations and extracts names and descriptions
2. The system prompt includes available skills in XML format
3. When a task matches, the agent uses read to load the full SKILL.md
4. The agent follows the instructions, using relative paths to reference scripts and assets

This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.

Skill Commands

Skills register as /skill:name commands:

/skill:brave-search           # Load and execute the skill
/skill:pdf-tools extract      # Load skill with arguments

Arguments after the command are appended to the skill content as User: <args>.

Toggle skill commands in settings:

{
  "enableSkillCommands": true
}

Skill Structure

A skill is a directory with a SKILL.md file. Everything else is freeform.

my-skill/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Helper scripts
│   └── process.sh
├── references/           # Detailed docs loaded on-demand
│   └── api-reference.md
└── assets/
    └── template.json

SKILL.md Format

---
name: my-skill
description: What this skill does and when to use it. Be specific.
---

# My Skill

## Setup

Run once before first use:
\`\`\`bash
cd /path/to/skill && npm install
\`\`\`

## Usage

\`\`\`bash
./scripts/process.sh <input>
\`\`\`

Use relative paths from the skill directory:

See [the reference guide](references/REFERENCE.md) for details.

Frontmatter

Per the Agent Skills specification:

Field	Required	Description
name	Yes	Max 64 chars. Lowercase a-z, 0-9, hyphens. Must match parent directory.
description	Yes	Max 1024 chars. What the skill does and when to use it.
license	No	License name or reference to bundled file.
compatibility	No	Max 500 chars. Environment requirements.
metadata	No	Arbitrary key-value mapping.
allowed-tools	No	Space-delimited list of pre-approved tools (experimental).
disable-model-invocation	No	When true, skill is hidden from system prompt. Users must use /skill:name.

Name Rules

• 1-64 characters
• Lowercase letters, numbers, hyphens only
• No leading/trailing hyphens
• No consecutive hyphens
• Must match parent directory name

Valid: pdf-processing, data-analysis, code-review Invalid: PDF-Processing, -pdf, pdf--processing

Description Best Practices

The description determines when the agent loads the skill. Be specific.

Good:

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.

Poor:

description: Helps with PDFs.

Validation

Pi validates skills against the Agent Skills standard and warns (but still loads) non-compliant skills:

• Name doesn't match parent directory
• Name exceeds 64 characters or contains invalid characters
• Name starts/ends with hyphen or has consecutive hyphens
• Description missing or exceeds 1024 characters
• Unknown frontmatter fields

Name collisions (same name from different locations) warn and keep the first skill found.

Example

brave-search/
├── SKILL.md
├── search.js
└── content.js

SKILL.md:

---
name: brave-search
description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content.
---

# Brave Search

## Setup

\`\`\`bash
cd /path/to/brave-search && npm install
\`\`\`

## Search

\`\`\`bash
./search.js "query"              # Basic search
./search.js "query" --content    # Include page content
\`\`\`

## Extract Page Content

\`\`\`bash
./content.js https://example.com
\`\`\`

Skill Repositories

• Anthropic Skills - Document processing (docx, pdf, pptx, xlsx), web development
• Pi Skills - Web search, browser automation, Google APIs, transcription