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.

Example use cases:

• Web search and content extraction (Brave Search API)
• Browser automation via Chrome DevTools Protocol
• Google Calendar, Gmail, Drive integration
• PDF/DOCX processing and creation
• Speech-to-text transcription
• YouTube transcript extraction

See Skill Repositories for ready-to-use skills.

When to Use Skills

Need	Solution
Always-needed context (conventions, commands)	AGENTS.md
User triggers a specific prompt template	Slash command
Additional tool directly callable by the LLM (like read/write/edit/bash)	Custom tool
On-demand capability package (workflows, scripts, setup)	Skill

Skills are loaded when:

• The agent decides the task matches a skill's description
• The user explicitly asks to use a skill (e.g., "use the pdf skill to extract tables")

Good skill examples:

• Browser automation with helper scripts and CDP workflow
• Google Calendar CLI with setup instructions and usage patterns
• PDF processing with multiple tools and extraction patterns
• Speech-to-text transcription with API setup

Not a good fit for skills:

• "Always use TypeScript strict mode" → put in AGENTS.md
• "Review my code" → make a prompt template
• Need user confirmation dialogs or custom TUI rendering → make a custom tool

Skill Structure

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

my-skill/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Helper scripts (bash, python, node)
│   └── process.sh
├── references/           # Detailed docs loaded on-demand
│   └── api-reference.md
└── assets/               # Templates, images, etc.
    └── 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>
\`\`\`

## Workflow

1. First step
2. Second step
3. Third step

Frontmatter Fields

Per the Agent Skills specification:

Field	Required	Constraints
name	Yes	Max 64 chars. Lowercase a-z, 0-9, hyphens only. Must match parent directory name.
description	Yes	Max 1024 chars. What the skill does and when to use it.
license	No	License name or reference to bundled license file.
compatibility	No	Max 500 chars. Environment requirements (system packages, network access, etc.).
metadata	No	Arbitrary key-value mapping for additional metadata.
allowed-tools	No	Space-delimited list of pre-approved tools (experimental).

Name Validation

The name field must:

• Be 1-64 characters
• Contain only lowercase letters (a-z), numbers (0-9), and hyphens
• Not start or end with a hyphen
• Not contain consecutive hyphens (--)
• Match the parent directory name exactly

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

Description Best Practices

The description is critical. It determines when the agent loads the skill. Be specific about both what it does and when to use it.

Good:

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

Poor:

description: Helps with PDFs.

File References

Use relative paths from the skill directory:

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

Run the extraction script:
\`\`\`bash
./scripts/extract.py input.pdf
\`\`\`

Skill Locations

Skills are discovered from these locations (later wins on name collision):

1. ~/.pi/agent/skills/ (global)
2. <cwd>/.pi/skills/ (project)
3. Paths listed in settings.json under skills
4. CLI --skill paths (additive even with --no-skills)

Discovery rules for each directory:

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

Configuration

Configure skill paths in ~/.pi/agent/settings.json:

{
  "skills": ["~/my-skills-repo", "/path/to/skill/SKILL.md"],
  "enableSkillCommands": true
}

Use project-local settings in <cwd>/.pi/settings.json to scope skills to a single project.

Setting	Default	Description
skills	[]	Additional skill file or directory paths
enableSkillCommands	true	Register skills as /skill:name commands

CLI Additions

Use --skill to add skills for a specific invocation:

pi --skill ~/my-skills/terraform
pi --skill ./skills/custom-skill/SKILL.md

Use --no-skills to disable automatic discovery (CLI --skill paths still load).

How Skills Work

1. At startup, pi scans skill locations and extracts names + 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/assets

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

Skill Commands

Skills are automatically registered as slash commands with a /skill: prefix:

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

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

Toggle skill commands via /settings or in settings.json:

{
  "enableSkillCommands": true
}

Setting	Default	Description
enableSkillCommands	true	Register skills as /skill:name commands

Validation Warnings

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
• Name 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: Web Search Skill

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

For inspiration and ready-to-use skills:

• Anthropic Skills - Official skills for document processing (docx, pdf, pptx, xlsx), web development, and more
• Pi Skills - Skills for web search, browser automation, Google APIs, transcription

Disabling Skills

CLI:

pi --no-skills

Use --no-skills to disable automatic discovery while keeping explicit --skill paths.