Skip to main content

Documentation Index

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

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

Skills are self-contained capability packages that provide specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks. Pi loads them on demand — either automatically when the task matches the skill’s description, or explicitly via /skill:name. Pi implements the Agent Skills standard, warning about violations but remaining lenient.
Skills can instruct the model to perform any action and may include executable code the model invokes. Review skill content before use.

​
How skills work

1

Discovery at startup

Pi scans skill locations and extracts names and descriptions. Only descriptions are kept in context — full content loads on demand.
2

System prompt listing

Available skills appear in the system prompt in XML format per the Agent Skills specification. The agent reads them to decide when a skill is relevant.
3

On-demand loading

When a task matches, the agent uses the read tool to load the full SKILL.md. Use /skill:name to force it explicitly.
4

Execution

The agent follows the skill’s instructions, using relative paths to reference scripts and assets inside the skill directory.

​
Skill locations

Pi auto-discovers skills from these locations: 
~/.pi/agent/skills/
~/.agents/skills/
Available in all projects.
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 <path> flags still load even when discovery is disabled. You can also point Pi at skills from other tools in settings.json: 
{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

​
SKILL.md format

A skill is a directory with a SKILL.md file. Everything else is freeform — scripts, reference docs, assets. 
my-skill/
├── SKILL.md              # Required
├── scripts/
│   └── process.sh
└── references/
    └── api-reference.md
The SKILL.md file uses YAML frontmatter followed by instructions in Markdown: 
---
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
```
Use relative paths from the skill directory to reference scripts and assets: 
See [the reference guide](references/REFERENCE.md) for details.

​
Frontmatter fields

FieldRequiredDescription
nameYes1–64 chars. Lowercase letters, numbers, hyphens. Must match parent directory name.
descriptionYesUp to 1024 chars. What the skill does and when to use it. Skills without a description are not loaded.
licenseNoLicense name or reference to bundled file.
compatibilityNoUp to 500 chars. Environment requirements.
allowed-toolsNoSpace-delimited list of pre-approved tools (experimental).
disable-model-invocationNoWhen true, skill is hidden from system prompt. Users must invoke via /skill:name.
Name rules: lowercase a-z, 0-9, hyphens; no leading/trailing hyphens; no consecutive hyphens; must match the parent directory name. Description best practice: be specific about when to use the skill. The description is what the agent reads to decide whether to load it. 
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.

​
Using skills

​
Slash command

Type /skill:name in the editor to load and execute a skill: 
/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 skill commands via /settings or in settings.json: 
{
  "enableSkillCommands": true
}

​
Auto-loading

Pi includes skill descriptions in the system prompt. When a task matches the description, the agent loads the full SKILL.md automatically. Write descriptions that clearly state the conditions under which the skill applies.

​
Sharing skills

Package skills in a Pi package to share them via npm or git. Add a skills/ directory to your package and list it in the pi manifest: 
{
  "name": "my-pi-package",
  "keywords": ["pi-package"],
  "pi": {
    "skills": ["./skills"]
  }
}

​
Validation

Pi validates skills against the Agent Skills standard. Most issues produce warnings but still load the skill. Name collisions (same name from different locations) warn and keep the first skill found.

Extensions

TypeScript modules for custom tools, commands, and UI.

Pi packages

Bundle and share skills via npm or git.

Prompt templates

Reusable prompts that expand with a slash command.

Build docs developers (and LLMs) love

Get started for freeTalk to us