Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/badlogic/pi-mono/llms.txt

Use this file to discover all available pages before exploring further.

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, ensuring compatibility with other agent harnesses like Claude Code and OpenAI Codex.

​
Quick Start

1
Create Skill Directory
2
mkdir -p ~/.pi/agent/skills/my-skill
cd ~/.pi/agent/skills/my-skill
3
Write SKILL.md
4
Create SKILL.md with YAML frontmatter:
5
---
name: my-skill
description: Brief description of what this skill does and when to use it. Be specific.
---

# My Skill

## Setup

Run once before first use:

```bash
cd ~/.pi/agent/skills/my-skill && npm install
6
Usage
7
./scripts/process.sh <input>
8
See the reference guide for details.
9

### Test the Skill

```bash
pi
10
The skill appears in the system prompt automatically. Use /skill:my-skill to load it explicitly.

​
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 the read tool 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 Structure

A complete skill directory: 
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

The only required file. Must include:
  1. YAML frontmatter with name and description
  2. Markdown content with instructions
---
name: my-skill
description: What this skill does and when to use it. Be specific.
---

# My Skill

Instructions for the agent go here.

​
Frontmatter Fields

FieldRequiredDescription
nameYesMax 64 chars. Lowercase a-z, 0-9, hyphens. Must match parent directory.
descriptionYesMax 1024 chars. What the skill does and when to use it.
licenseNoLicense name or reference to bundled file.
compatibilityNoMax 500 chars. Environment requirements.
metadataNoArbitrary key-value mapping.
allowed-toolsNoSpace-delimited list of pre-approved tools (experimental).
disable-model-invocationNoWhen 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. 
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.

​
Complete Example

1
Create Directory Structure
2
mkdir -p ~/.pi/agent/skills/brave-search
cd ~/.pi/agent/skills/brave-search
3
Add Scripts
4
Create search.js:
5
#!/usr/bin/env node
const query = process.argv[2];
const includeContent = process.argv.includes('--content');

// Search implementation
const results = await searchBrave(query, { includeContent });
console.log(JSON.stringify(results, null, 2));
6
Make it executable:
7
chmod +x search.js
8
Write SKILL.md
9
---
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 ~/.pi/agent/skills/brave-search && npm install
export BRAVE_API_KEY=your-key
11
./search.js "query"              # Basic search
./search.js "query" --content    # Include page content
12
Extract Page Content
13
./content.js https://example.com
14

### Test It

```bash
pi
15
Then ask:
16
Search for "TypeScript best practices"

​
Skill Locations

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)
  • Packages: skills/ directories or pi.skills entries in package.json
  • Settings: skills array with files or directories
  • CLI: --skill <path> (repeatable)

​
Using Skills from Other Harnesses

To use skills from Claude Code or OpenAI Codex, add to ~/.pi/agent/settings.json: 
{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}
For project-level Claude Code skills, add to .pi/settings.json: 
{
  "skills": ["../.claude/skills"]
}

​
Skill Commands

Skills register as /skill:name commands: 
/skill:brave-search           # Load and execute
/skill:pdf-tools extract      # Load with arguments
Arguments after the command are appended to the skill content as User: <args>. Toggle via /settings or in settings.json: 
{
  "enableSkillCommands": true
}

​
Relative Paths

Use relative paths from the skill directory: 
See [the reference guide](references/REFERENCE.md) for details.

Run the setup script:

```bash
./scripts/setup.sh


Pi resolves these paths relative to the skill's base directory.

## Validation

Pi validates skills against the Agent Skills standard:

- Name doesn't match parent directory → Warning
- Name exceeds 64 characters → Warning
- Name contains invalid characters → Warning
- Description exceeds 1024 characters → Warning
- Missing description → Skill not loaded

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

## Dynamic Skills from Extensions

Extensions can provide skills dynamically:

```typescript
import type { ExtensionAPI, Skill } from "@mariozechner/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  const skill: Skill = {
    name: "dynamic-skill",
    description: "Skill provided by extension",
    content: "# Dynamic Skill\n\nInstructions here.",
    source: "extension",
  };

  pi.on("resources_discover", async (event) => {
    return {
      skills: [skill],
    };
  });
}
See packages/coding-agent/examples/extensions/dynamic-resources/ for a complete example.

​
Skill Repositories

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

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us