Chapter 9 · Skills System

Chapter goals: Understand the progressive disclosure工作原理 of skills; master the SKILL.md structure and frontmatter fields;动手编写 a script-resource-carrying reusable skill.

9.1 What a Skill Is: On-Demand Loaded Capability Packs

A skill is a self-contained capability pack: providing专用工作流, install instructions, helper scripts, and reference docs for specific tasks. pi implements the open Agent Skills standard (tolerant of小偏差 to the spec; e.g. allowing the skill name to differ from the directory name).

The core design is progressive disclosure:

At startup: scan all skills → inject only 「name + description」 into the system prompt
At runtime: task匹配s a skill → the agent loads the full SKILL.md via the read tool
At execution: follow SKILL.md instructions;引用 relative paths to scripts/resources

Even with dozens of skills installed; the常驻上下文 cost is only dozens of lines of description; full instructions only进入 the对话 when真正 needed.

9.2 Discovery Locations and Safety Premise

pi loads skills from these locations (--no-skills可禁用 discovery; explicit --skill <path>仍生效):

Global:  ~/.pi/agent/skills/    ~/.agents/skills/
Project: .pi/skills/            .agents/skills/ (walk upward from cwd to the git root)
                      ↑ The project location加载 only after the project is trusted (see Chapter 7)
Package: skills/ directory or the pi.skills declaration in package.json
Settings: skills array explicitly specifying files or directories

Discovery rule细节: root-level散落 .md files in ~/.pi/agent/skills/ and .pi/skills/ are also识别 as独立 skills; but root-level .md files in ~/.agents/skills/ and the project .agents/skills/ are ignored —只有含 SKILL.md 的目录才算 skill;且目录递归扫描.

Review Before Using

The官方反复强调: skills can instruct the model to execute任意 operations; and may携带 executable code the model will call.务必阅读内容 before installing community skills.

Reusing skills from其他 tools只需加路径 — Claude Code / Codex's skill库直接兼容:

// ~/.pi/agent/settings.json
{
  "skills": ["~/.claude/skills", "~/.codex/skills"]
}

9.3 SKILL.md Structure and Frontmatter

A skill is a directory containing SKILL.md;其余内容自由发挥:

pdf-tools/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Helper scripts
│   └── merge.sh
├── references/           # On-demand detailed docs
│   └── api-reference.md
└── assets/
    └── template.json

Frontmatter fields (依据 Agent Skills spec):

Field	Required	Description
name	✅	≤64 chars; lowercase letters/digits/hyphens; no hyphen at start/end or consecutive
description	✅	≤1024 chars; 决定 the agent何时加载 it
license	—	License
compatibility	—	Environment requirements (≤500 chars)
metadata	—	arbitrary key-value pairs
allowed-tools	—	Pre-approved tool list (experimental)
disable-model-invocation	—	Set true to隐藏 from the system prompt; only /skill:name manually callable

Validation hard rules to remember two硬线: skills missing description are not loaded;其余违规 (name too long; illegal chars etc.) only warn; not block.同名冲突时保留先发现的并警告.

The description is the skill's most critical一行字 — it is the "when to use me"判断依据. Comparing the官方给出的示例:

# Good: specific; includes trigger phrases
description: Extracts text and tables from PDF files; fills PDF forms; and merges multiple PDFs. Use when working with PDF documents.

# Bad: vague; the agent无法判断适用时机
description: Helps with PDFs.

9.4 Walkthrough: Writing a changelog-check Skill

Below is a complete; immediately usable skill: checking whether CHANGELOG covers this version's changes before release.

mkdir -p ~/.pi/agent/skills/changelog-check/scripts

<!-- ~/.pi/agent/skills/changelog-check/SKILL.md -->
---
name: changelog-check
description: Before release; check whether CHANGELOG.md covers all important changes since the last git tag. Use when the user is准备发版 or mentions changelog.
---

# Changelog Check

## Steps

1. Find the previous release tag:
   ```bash
   git describe --tags --abbrev=0

2. List commits since that tag (git log <tag>..HEAD --oneline); classify into Added / Changed / Fixed.
3. Read CHANGELOG.md; check every classified commit appears in the unreleased section.
4. Report: output missing entries as a list; print "OK" if全部覆盖.

Rules

• Do not modify CHANGELOG.md unless the user explicitly asks.
• Ignore merge commits and chore: commits with no user impact.

Keep-a-Changelog format details见 references/format.md.

::: warning On the Example's Language and Format
Above is **the raw content of a complete file** (so no教程式 subsection numbers). The skill body is自然语言 instructions for the model to read; Chinese or English both work — English便于跨团队共享; directly写 Chinese is完全没问题 for internal teams (the model understands both languages). The `name` field is the例外: must be lowercase letters/digits/hyphens; no Chinese.
:::

Two usage方式:

```bash
/skill:changelog-check          # Manually force-load and execute
/skill:changelog-check v2.1     # Parameters appended after the skill content as User: <args>
# Or just say "准备发版吧"; the agent自动匹配 the description to load

The body structure is自由的

The above ## Steps, ## Rules are just普通 markdown conventions for the model to read — pi only parses frontmatter (name/description etc.); how to分节 the body is完全 by you (the官方示例惯用 ## Setup/## Usage). What真正被"执行" is the natural language instructions the model reads.

Key回顾:引用 resources in the body must use paths relative to the skill directory (e.g. references/format.md above); the enableSkillCommands setting (default on) controls whether to注册 the /skill:name command.

9.5 Getting Skills from the Community

两个官方推荐的技能仓库:

• Anthropic Skills — docx/pdf/pptx/xlsx document processing; web development;
• Pi Skills — web search; browser automation; Google API; transcription.

After cloning; add the path to the skills array in settings (配合第 13 章的包机制还能做到版本化管理). You can also直接让 pi写 one — the官方文档原话 is "ask pi to build one for your use case".

Chapter Summary

• Skill = a directory containing SKILL.md; progressive disclosure:平时 only name+description进入上下文;
• Project skill dirs (.pi/skills/, .agents/skills/) are受 Project Trust门控;
• Frontmatter hard rules: name lowercase-hyphen ≤64 chars; description missing → not loaded;其余 violations仅警告;
• How specific the description is written directly决定 the auto-trigger可靠性;
• Body引用 scripts/references/assets via相对 paths; /skill:name [args] manual trigger.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What does "progressive disclosure" mean for pi skills?

2. Which skill gets直接拒绝 loaded by pi?

3. When are skills in the project's .agents/skills/ directory可用?

4. In the SKILL.md body; what is the correct way to reference references/api.md under the skill directory?

🛠️ Hands-on Practice

1.完整实现 this chapter's changelog-check skill (补上 references/format.md);验证 in a repo with真实 tags. 2. Clone the Anthropic Skills repo locally and引入 it via settings;测试其中一个 document processing skill. 3. Add disable-model-invocation: true to your skill;验证 it消失 from the system prompt; only callable via /skill:name.

After completing the exercises; proceed to Chapter 10: Extensions Intro.