# 技能

> 技能的加载位置、工作原理、SKILL.md 结构、frontmatter 字段与校验规则。

---

LLMS 索引： [llms.txt](/llms.txt)

---

> pi 可以创建技能。可以让它为你的用例构建一个。

技能是智能体按需加载的自包含能力包。一个技能为特定任务提供专门的工作流、安装说明、辅助脚本和参考文档。

Pi 实现了 [Agent Skills 标准](https://agentskills.io/specification)，对大多数违规情况只给出警告但保持宽容。Pi 允许技能名称与其父目录不同，尽管标准不允许；对于在多个智能体框架之间共享的技能目录来说，那条规则并不理想。

## 目录 {#table-of-contents}

- [位置](#locations)
- [技能的工作原理](#how-skills-work)
- [技能命令](#skill-commands)
- [技能结构](#skill-structure)
- [Frontmatter](#frontmatter)
- [校验](#validation)
- [示例](#example)
- [技能仓库](#skill-repositories)

## 位置 {#locations}

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

Pi 从以下位置加载技能：

- 全局：
  - `~/.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` 文件只要带有合法的技能 frontmatter 且 `description` 非空，就会被识别为独立技能
- 在所有技能位置中，包含 `SKILL.md` 的目录会被递归发现
- 在 `~/.agents/skills/` 和项目级 `.agents/skills/` 中，根目录下的 `.md` 文件会被忽略，但分组文件夹中嵌套的 `.md` 文件在声明了技能 frontmatter 后会被发现
- 除 `SKILL.md` 外，其他看起来不像技能的根级 Markdown 文件会被静默忽略

使用 `--no-skills` 可以禁用发现（显式指定的 `--skill` 路径仍会加载）。

### 使用来自其他智能体框架的技能 {#using-skills-from-other-harnesses}

要使用来自 Claude Code 或 OpenAI Codex 的技能，把它们的目录加入设置：

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

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

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

## 技能的工作原理 {#how-skills-work}

1. 启动时，pi 扫描技能位置并提取名称和描述
2. 系统提示词按照[规范](https://agentskills.io/integrate-skills)以 XML 格式包含可用技能
3. 当任务匹配时，智能体使用 `read`（在 `read` 不可用时使用 `bash`）加载完整的 SKILL.md（模型并不总会这样做；可以用提示词或 `/skill:name` 强制加载）
4. 智能体遵循其中的指令，使用相对路径引用脚本和资源

这就是渐进式披露：上下文中始终只有描述，完整指令按需加载。

## 技能命令 {#skill-commands}

技能会注册为 `/skill:name` 命令：

```bash
/skill:brave-search           # Load and execute the skill
/skill:pdf-tools extract      # Load skill with arguments
```

命令之后的参数会以 `User: <args>` 的形式附加到技能内容后面。

在交互模式下通过 `/settings`，或在 `settings.json` 中切换技能命令：

```json
{
  "enableSkillCommands": true
}
```

## 技能结构 {#skill-structure}

一个技能就是一个包含 `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 格式 {#skillmd-format}

````markdown
---
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>
```
````

使用技能目录中的相对路径：

```markdown
详情请参阅参考指南。
```

## Frontmatter {#frontmatter}

依据 [Agent Skills 规范](https://agentskills.io/specification#frontmatter-required)：

| 字段 | 必填 | 说明 |
|-------|----------|-------------|
| `name` | 是 | 最多 64 个字符。仅限小写 a-z、0-9 和连字符。与标准不同，Pi 不要求它与父目录同名，因为该标准要求对共享技能目录而言并不理想。 |
| `description` | 是 | 最多 1024 个字符。说明技能做什么以及何时使用。 |
| `license` | 否 | 许可证名称，或指向包内许可证文件的引用。 |
| `compatibility` | 否 | 最多 500 个字符。环境要求。 |
| `metadata` | 否 | 任意键值映射。 |
| `allowed-tools` | 否 | 以空格分隔的预批准工具列表（实验性）。 |
| `disable-model-invocation` | 否 | 为 `true` 时，技能不会出现在系统提示词中。用户必须使用 `/skill:name`。 |

### 名称规则 {#name-rules}

- 1-64 个字符
- 仅限小写字母、数字和连字符
- 不能以连字符开头或结尾
- 不能有连续的连字符

Pi 不要求名称与父目录一致。Agent Skills 标准有此要求，但对被多个工具共享的技能目录来说，这条要求并不理想。

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

### 描述的最佳实践 {#description-best-practices}

描述决定了智能体何时加载技能，请写得具体。

好的示例：
```yaml
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
```

差的示例：
```yaml
description: Helps with PDFs.
```

## 校验 {#validation}

Pi 会按照 Agent Skills 标准校验技能。大多数问题只产生警告，技能仍会加载：

- 名称超过 64 个字符或包含非法字符
- 名称以连字符开头/结尾，或存在连续连字符
- 描述超过 1024 个字符

未知的 frontmatter 字段会被忽略。

声明为技能但缺少描述的不会被加载。格式错误的 `SKILL.md` 文件以及没有描述的 `SKILL.md` 文件会产生警告且不会被加载。其他不带合法技能 frontmatter 的 Markdown 文件会被忽略。

名称冲突（不同位置出现同名）会产生警告，并保留最先找到的技能。

## 示例 {#example}

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

**SKILL.md：**
````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
```
````

## 技能仓库 {#skill-repositories}

- [Anthropic Skills](https://github.com/anthropics/skills)——文档处理（docx、pdf、pptx、xlsx）、Web 开发
- [Pi Skills](https://github.com/badlogic/pi-skills)——Web 搜索、浏览器自动化、Google API、语音转写