Pi Agent Skills Skill System

Skills are self-contained capability packages that let AI load workflow instructions and tool scripts for specialized domains on demand.

Pi Agent implementsthe Agent Skills standard。

What is a Skill

A Skill is a directory that containsSKILL.mda SKILL.md file.

SKILL.md contains the skill's name, description, and detailed usage instructions. AI will automatically read and execute it when needed.

You can think of a Skill as an AI's "professional training manual" — it doesn't occupy context space normally, and is only loaded when needed.

How Skills Work

The entire loading process consists of four steps, with the core idea being "look at the directory first, then read the full content."

1. When Pi Agent starts, it scans all Skill locations and extracts names and descriptions.
2. Descriptions of all available Skills are embedded in the system prompt in XML format.
3. When a user's task matches a Skill's description, AI automatically loads the full SKILL.md using the read tool.
4. AI works according to the instructions in SKILL.md, using relative paths to reference scripts and resources in the skill directory.

Note that the model may not proactively read it. If necessary, explicitly request it in the prompt, or use/skill:nameto force loading.

This design is called "Progressive Disclosure" — only descriptions are always in context, while full instructions are loaded on demand.

Skill Directory Structure

Only SKILL.md is required; the rest of the directories are created as needed.

my-skill/
├── SKILL.md              # 必需：Frontmatter + 指令
├── scripts/              # 辅助脚本
│   └── process.sh
├── references/           # 详细参考文档（按需加载）
│   └── api-reference.md
└── assets/
    └── template.json

SKILL.md Format

SKILL.md uses YAML Frontmatter to define metadata, followed by the instruction body in Markdown format:

When referencing files in the skill directory, userelative paths。

Frontmatter Fields

Only name and description are required; add other fields as needed.

description is the key basis for AI to decide whether to load your Skill, so be sure to write it specifically and clearly.

A vague description can cause the Skill to be triggered in inappropriate scenarios or ignored in needed ones.

Skill Loading Locations

Pi Agent scans Skills at both the global and project levels, with slightly different discovery rules for different locations.

One more point: in ~/.agents/skills/ and the project's .agents/skills/, nested .md files with valid Frontmatter in grouped subdirectories are also recognized, while top-level .md files without Frontmatter are ignored.

CLI Arguments--no-skillsAutomatic skill discovery can be disabled, but explicitly provided--skill pathswill still be loaded.

Validation and Naming Conflicts

Pi Agent validates Skills according to the Agent Skills standard. Most issues only produce warnings, and the Skill is still loaded.

SKILL.md files missing a description are not loaded; malformed files also only produce a warning and are not loaded.

When Skills with the same name come from different locations, a warning is issued and the first one discovered is kept.

Skill Commands

Each Skill is automatically registered as a/skill:namecommand:

/skill:brave-search
/skill:pdf-tools extract

Arguments after the command will be appended to the Skill content in the form ofUser: argumentsand appended to the Skill content.

Using /skill:pdf-tools extract report.pdf as an example, the expanded content is roughly as follows:

/skill:pdf-tools extract report.pdf

User: extract report.pdf

After receiving this content, AI will follow the instructions in SKILL.md to find and execute scripts in the scripts/ directory.

Skill command registration can be disabled via settings:

You can also use the settingdisable-model-invocationto make certain Skills manually-invocable only, and not automatically appear in the system prompt.

Importing Skills from Other Tools

Pi Agent can load Skills from Claude Code or OpenAI Codex:

The following two configurations are written to the global and project settings.json respectively; adjust the paths according to your actual directories.

For project-level Claude Code Skills:

Instructions in Skills can require AI to perform arbitrary operations, including running executable files.

Before using third-party Skills, it is recommended to review their content.

Complete Skill Example

The following is a complete example of a web search Skill:

Recommended Skill Repositories

These two repositories provide a large number of readily usable Skills, but it is still recommended to read through the content before installation.