技能

技能是独立的能力包，代理按需加载。技能为特定任务提供专门的流程、设置说明、辅助脚本和参考文档。

Pi 实现了 Agent Skills 标准，会警告大多数违规行为但仍然宽容。Pi 允许技能名称与父目录不同，即使标准禁止这样做；该规则对于跨多个代理框架使用的共享技能目录来说是最优的。

位置

安全： 技能可以指示模型执行任何操作，并且可能包含模型调用的可执行代码。使用技能前请审查内容。

Pi 从以下位置加载技能：

全局：
- ~/.pi/agent/skills/
- ~/.agents/skills/
项目（仅在项目被信任后）：
- .pi/skills/
- cwd 和祖先目录中的 .agents/skills/（一直到 git 仓库根目录，或不在仓库中时到文件系统根目录）
包：skills/ 目录或 package.json 中的 pi.skills 条目
设置：skills 数组（包含文件或目录）
CLI：--skill <路径>（可重复，即使使用 --no-skills 也累加）

发现规则：

在 ~/.pi/agent/skills/ 和 .pi/skills/ 中，直接根目录的 .md 文件被识别为独立技能
在所有技能位置，包含 SKILL.md 的目录会被递归发现
在 ~/.agents/skills/ 和项目 .agents/skills/ 中，根目录的 .md 文件被忽略

使用 --no-skills 禁用发现（显式 --skill 路径仍会加载）。

使用其他框架的技能

要使用来自 Claude Code 或 OpenAI Codex 的技能，将其目录添加到设置中：

json

{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

对于项目级的 Claude Code 技能，添加到 .pi/settings.json：

json

{
  "skills": ["../.claude/skills"]
}

技能如何工作

启动时，pi 扫描技能位置并提取名称和描述
系统提示包含 XML 格式可用的技能，遵循规范
任务匹配时，代理使用 read 加载完整的 SKILL.md（模型不一定这样做；使用提示或 /skill:名称 强制加载）
代理遵循说明，使用相对路径引用脚本和资源

这是渐进式披露：描述总是在上下文中，完整说明按需加载。

技能命令

技能注册为 /skill:名称 命令：

bash

/skill:brave-search           # 加载并执行该技能
/skill:pdf-tools extract      # 带参数的技能

命令后的参数会附加到技能内容作为 User: <参数>。

通过交互模式中的 /settings 或 settings.json 切换技能命令：

json

{
  "enableSkillCommands": true
}

技能结构

技能是一个包含 SKILL.md 文件的目录。其余内容是自由格式。

my-skill/
├── SKILL.md              # 必需：前导元数据 + 说明
├── scripts/              # 辅助脚本
│   └── process.sh
├── references/           # 按需加载的详细文档
│   └── api-reference.md
└── assets/
    └── template.json

SKILL.md 格式

markdown

---
name: my-skill
description: 此技能的作用及何时使用它。要具体。
---

# 我的技能

## 设置

首次使用前运行一次：
```bash
cd /path/to/skill && npm install
```

## 用法

```bash
./scripts/process.sh <输入>
```

从技能目录使用相对路径：

markdown

查看 [参考指南](references/REFERENCE.md) 获取详细信息。

前导元数据

遵循 Agent Skills 规范：

字段	必需	说明
`name`	是	最大 64 个字符。仅限小写字母 a-z、数字、连字符。与标准不同，Pi 不要求此名称必须匹配父目录，因为该标准要求对于共享技能目录不是最优的。
`description`	是	最大 1024 个字符。技能的作用及何时使用它。
`license`	否	许可证名称或引用打包文件。
`compatibility`	否	最大 500 个字符。环境要求。
`metadata`	否	任意键值映射。
`allowed-tools`	否	空格分隔的预先批准工具列表（实验性）。
`disable-model-invocation`	否	为 `true` 时，技能不会出现在系统提示中。用户必须使用 `/skill:名称`。

名称规则

1-64 个字符
仅限小写字母、数字、连字符
不能以或尾随连字符
不能有连续连字符

Pi 不要求名称与父目录匹配。Agent Skills 标准要求，但这对于多个工具使用的共享技能目录不是最优的。

有效：pdf-processing、data-analysis、code-review 无效：PDF-Processing、-pdf、pdf--processing

描述最佳实践

描述决定了代理何时加载技能。要具体。

好的：

yaml

description: 从 PDF 文件提取文本和表格，填充 PDF 表单，并合并多个 PDF。当处理 PDF 文档时使用。

差的：

yaml

description: 帮助处理 PDF。

验证

Pi 根据 Agent Skills 标准验证技能。大多数问题会产生警告但仍然加载技能：

名称超过 64 个字符或包含无效字符
名称以或尾随连字符，或有连续连字符
描述超过 1024 个字符

未知的前导字段被忽略。

例外： 缺少描述的不会被加载。

名称冲突（来自不同位置的相同名称）会警告并保留找到的第一个技能。

示例

brave-search/
├── SKILL.md
├── search.js
└── content.js

SKILL.md：

markdown

---
name: brave-search
description: 通过 Brave Search API 进行网络搜索和内容提取。用于搜索文档、事实或任何网页内容。
---

# Brave Search

## 设置

```bash
cd /path/to/brave-search && npm install
```

## 搜索

```bash
./search.js "查询"              # 基本搜索
./search.js "查询" --content    # 包含页面内容
```

## 提取页面内容

```bash
./content.js https://example.com
```

技能仓库

Anthropic Skills - 文档处理（docx、pdf、pptx、xlsx），网络开发
Pi Skills - 网络搜索、浏览器自动化、Google API、转录

技能 ​

目录 ​

位置 ​

使用其他框架的技能 ​

技能如何工作 ​

技能命令 ​

技能结构 ​

SKILL.md 格式 ​

前导元数据 ​

名称规则 ​

描述最佳实践 ​

验证 ​

示例 ​

技能仓库 ​

技能

目录

位置

使用其他框架的技能

技能如何工作

技能命令

技能结构

SKILL.md 格式

前导元数据

名称规则

描述最佳实践

验证

示例

技能仓库