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, warning about violations but remaining lenient.

Table of Contents

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

Locations

Security: Skills can instruct the model to perform any action and may include executable code the model invokes. Review skill content before use.

Pi loads skills from:

• Global:
  • ~/.pi/agent/skills/
  • ~/.agents/skills/
• Project:
  • .pi/skills/
  • .agents/skills/ in cwd and ancestor directories (up to git repo root, or filesystem root when not in a repo)
• 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:

• In ~/.pi/agent/skills/ and .pi/skills/, direct root .md files are discovered as individual skills
• In all skill locations, directories containing SKILL.md are discovered recursively
• In ~/.agents/skills/ and project .agents/skills/, root .md files are ignored

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

Using Skills from Other Harnesses

To use skills from Claude Code or OpenAI Codex, add their directories to settings:

{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

For project-level Claude Code skills, add to .pi/settings.json:

{
  "skills": ["../.claude/skills"]
}

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 per the specification
3. When a task matches, the agent uses read to load the full SKILL.md (models don't always do this; use prompting or /skill:name to force it)
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 via /settings in interactive mode or in settings.json:

{
  "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:

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. Most issues produce warnings but still load the skill:

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

Unknown frontmatter fields are ignored.

Exception: Skills with missing description are not loaded.

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