Pi 官方文档
Skills（技能）
Pi 可以创建 Skill。告诉它你的使用场景，让它帮你构建一个。
Skills（技能）
Skill 是自包含的能力包，agent 会按需加载。一个 Skill 会为特定任务提供专用工作流、安装说明、辅助脚本和参考文档。
Pi 实现了 Agent Skills standard，会对大多数违规给出警告，但仍然保持宽松。即使标准不允许，Pi 也允许 skill 名称与父目录不同；因为这个要求对被多个 agent harness 共享的 Skill 目录并不理想。
目录
位置
安全提示： Skill 可以指示模型执行任何操作，并且可能包含模型会调用的可执行代码。使用前请先检查 Skill 内容。
Pi 会从以下位置加载 Skill：
- 全局：
~/.pi/agent/skills/~/.agents/skills/
- 项目（仅在项目被信任后）：
.pi/skills/- 当前工作目录
cwd及其祖先目录中的.agents/skills/（直到 git 仓库根目录；如果不在仓库中，则直到文件系统根目录）
- 包：
skills/目录，或package.json中的pi.skills条目 - 设置：
skills数组，里面可以放文件或目录 - CLI：
--skill <path>（可重复；即使加了--no-skills也会追加加载）
发现规则：
- 在
~/.pi/agent/skills/和.pi/skills/中，根目录下的.md文件会被识别为单独的 Skill - 在所有 Skill 位置中，包含
SKILL.md的目录都会被递归识别 - 在
~/.agents/skills/和项目的.agents/skills/中，根目录下的.md文件会被忽略
可以用 --no-skills 关闭发现；显式指定的 --skill 路径仍会加载。
从其他 Harness 中使用 Skill
要在 Claude Code 或 OpenAI Codex 中使用 Skill，请把它们的目录加入设置：
{
"skills": [
"~/.claude/skills",
"~/.codex/skills"
]
}
对于项目级 Claude Code Skill，请添加到 .pi/settings.json：
{
"skills": ["../.claude/skills"]
}
Skill 的工作方式
- 启动时，pi 会扫描 Skill 位置并提取名称和描述
- system prompt 会按照 specification 以 XML 格式包含可用 Skill
- 当任务匹配时，agent 会用
read加载完整的SKILL.md（模型不一定总会这么做；可以通过提示或/skill:name强制） - agent 按照说明执行，引用脚本和资源时使用相对路径
这就是渐进式披露：上下文里始终只有描述，完整指令则按需加载。
Skill 命令
Skill 会注册为 /skill:name 命令：
/skill:brave-search # Load and execute the skill
/skill:pdf-tools extract # Load skill with arguments
命令后面的参数会以 User: <args> 的形式追加到 Skill 内容中。
可以在交互模式下通过 /settings 切换 Skill 命令，也可以在 settings.json 中切换：
{
"enableSkillCommands": true
}
Skill 结构
一个 Skill 就是一个包含 SKILL.md 文件的目录。其他内容都可自由编排。
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 格式
---
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>
```
请从 Skill 目录使用相对路径：
See [the reference guide](/docs/REFERENCE) for details.
Frontmatter
根据 Agent Skills specification：
| 字段 | 必需 | 说明 |
|---|---|---|
name | 是 | 最多 64 个字符。只允许小写 a-z、0-9 和连字符。不同于标准，Pi 不要求它与父目录同名，因为这个标准要求对被多个工具共享的 Skill 目录并不理想。 |
description | 是 | 最多 1024 个字符。说明这个 Skill 做什么，以及何时使用。 |
license | 否 | 许可证名称，或指向随包文件的引用。 |
compatibility | 否 | 最多 500 个字符。环境要求。 |
metadata | 否 | 任意键值映射。 |
allowed-tools | 否 | 以空格分隔的预先批准工具列表（实验性）。 |
disable-model-invocation | 否 | 为 true 时，Skill 不会出现在 system prompt 中。用户必须使用 /skill:name。 |
名称规则
- 1-64 个字符
- 只能使用小写字母、数字和连字符
- 不能以连字符开头或结尾
- 不能出现连续连字符 Pi 不要求名称与父目录一致。Agent Skills standard 要求这样做，但这个要求对被多个工具使用的共享 Skill 目录并不理想。
有效：pdf-processing, data-analysis, code-review
无效：PDF-Processing, -pdf, pdf--processing
description 最佳实践
description 决定 agent 何时加载这个 Skill。要写具体。
好：
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
差：
description: Helps with PDFs.
校验
Pi 会按 Agent Skills standard 校验 Skill。大多数问题只会给出警告，但仍会加载 Skill：
- 名称超过 64 个字符，或包含无效字符
- 名称以连字符开头或结尾，或包含连续连字符
- description 超过 1024 个字符
未知的 frontmatter 字段会被忽略。
例外： 缺少 description 的 Skill 不会被加载。
名称冲突（不同位置出现同名 Skill）会给出警告，并保留先找到的那个 Skill。
示例
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" # 基础搜索
./search.js "query" --content # 包含页面内容
```
## Extract Page Content
```bash
./content.js https://example.com
```
Skill 仓库
- Anthropic Skills - 文档处理（docx、pdf、pptx、xlsx），web 开发
- Pi Skills - 网页搜索、浏览器自动化、Google APIs、转写