技能

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

技能（Skills）是自包含的能力包，代理按需加载。一个技能为特定任务提供专门的工作流、设置说明、辅助脚本和参考文档。

Pi 实现了 Agent Skills 标准，对大多数违规行为给出警告但仍保持宽容。Pi 允许技能名称与父目录不同，尽管标准禁止这样做；该规则对于多个代理工具共享的技能目录并不理想。

目录 Table of Contents

• 位置 Locations
• 技能工作原理 How Skills Work
• 技能命令 Skill Commands
• 技能结构 Skill Structure
• 前置元数据 Frontmatter
• 验证 Validation
• 示例 Example
• 技能仓库 Skill Repositories

位置 Locations

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

Pi 从以下位置加载技能：

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

发现规则：

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

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

使用其他代理中的技能 Using Skills from Other Harnesses

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

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

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

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

技能工作原理 How Skills Work

1. 启动时，pi 扫描技能位置并提取名称和描述
2. 系统提示中包含根据规范以 XML 格式提供的可用技能
3. 当任务匹配时，代理使用 read 加载完整的 SKILL.md（模型并不总是这样做；使用提示或 /skill:name 来强制加载）
4. 代理按照指令操作，使用相对路径引用脚本和资源

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

技能命令 Skill Commands

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

/skill:brave-search           # 加载并执行技能
/skill:pdf-tools extract      # 加载技能并传递参数

命令后的参数会以 User: <args> 的形式追加到技能内容中。

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

{
  "enableSkillCommands": true
}

技能结构 Skill Structure

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

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

SKILL.md 格式 SKILL.md Format

---
name: my-skill
description: 该技能的功能及使用时机。请具体说明。
---

# 我的技能 My Skill

## 设置 Setup

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

## 使用 Usage

```bash
./scripts/process.sh <input>
```

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

详情请参见[参考指南](https://github.com/earendil-works/agent-skills/blob/main/references/REFERENCE.md)。

前置元数据 Frontmatter

根据 Agent Skills 规范：

命名规则 Name Rules

• 1-64 个字符
• 仅限小写字母、数字、连字符
• 不能以连字符开头或结尾
• 不能有连续连字符 Pi 不要求名称与父目录匹配。Agent Skills 标准有此要求，但该要求对于多个工具共享的技能目录并不理想。

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

描述最佳实践 Description Best Practices

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

好的示例：

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

不佳的示例：

description: 帮助处理 PDF。

验证 Validation

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

• 名称超过 64 个字符或包含无效字符
• 名称以连字符开头/结尾或包含连续连字符
• 描述超过 1024 个字符

未知的前置元数据字段会被忽略。

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

名称冲突（同一名称来自不同位置）会发出警告并保留最先找到的技能。

示例 Example

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

SKILL.md：

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

# Brave 搜索 Brave Search

## 设置 Setup

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

## 搜索 Search

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

## 提取页面内容 Extract Page Content

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

技能仓库 Skill Repositories

• Anthropic 技能 - 文档处理（docx、pdf、pptx、xlsx）、Web 开发
• Pi 技能 - 网页搜索、浏览器自动化、Google API、转录