编辑文档 - 把自定义工具装进 Pi：Skills 扩展系统详解

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

## Skills 和 Extensions 是什么

Pi 有两套扩展机制，很多人对这两个概念分不清，先说清楚：

| 机制 | 做什么 | 难度 |
|------|--------|------|
| **Skills** | 文本指令包，告诉 AI「遇到 XX 场景怎么做」 | ⭐ 简单，会写 Markdown 就行 |
| **Extensions** | TypeScript 模块，注册新工具、拦截事件、定制 TUI | ⭐⭐⭐⭐ 需要写代码 |

**日常使用 Skills 就够了。** Skill 就是一个文件夹加一个 `SKILL.md` 文件，不需要写 TypeScript，AI 按需加载。

---

## 为什么需要 Skills

举个例子。

你经常要处理 PDF 文件，每次都跟 AI 说「帮我把 PDF 转成文字」，AI 每次都得从头理解怎么做。

有了 Skill，你写一份文档告诉 AI「遇到 PDF 处理时，用这个方法」，AI 以后遇到同类任务，自动加载这份文档，不需要你重复说。

**Skills 的核心价值：**
- 把经验封装成可复用的能力包
- AI 按需加载，不占用日常上下文
- 支持脚本文件，Skill 里可以带代码
- 跨项目共享，项目级 / 全局级都能用
- **兼容 Agent Skills 标准**——Claude Code、OpenAI Codex 的 Skill 可以直接拿来用

---

## Skill 的目录结构

一个 Skill 是一个文件夹，里面必须有 `SKILL.md`，其他自由发挥：

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

`SKILL.md` 格式示例：

```markdown
---
name: pdf-processing
description: 提取 PDF 文本和表格，填充表单，合并多个 PDF。处理 PDF 文档时使用。
---

# PDF 处理工具

## 安装

```bash
cd /path/to/my-skill && npm install
```

## 使用方法

```bash
./scripts/extract.sh <文件路径>
```
```

## 注意事项

优先用文字模式处理扫描件，图片模式速度较慢。
```

---

## SKILL.md 的 frontmatter 规范

frontmatter 是文件开头的 YAML 区块，告诉 Pi 这个 Skill 是谁、做什么：

```yaml
---
name: my-skill                    # 名称：1-64字符，小写字母、数字、连字符
description: 描述这个技能做什么，什么时候使用，要具体  # 必需
license: MIT                      # 可选：许可证名称
compatibility: Node.js 18+         # 可选：环境要求
allowed-tools:                    # 可选：预批准的工具白名单（实验性）
---
```

**description 最重要。** Pi 用这段文字决定「什么时候加载这个 Skill」。

❌ 差的描述：`Helps with PDFs.`（太泛，AI 分不清什么时候该用）

✅ 好的描述：`提取 PDF 文本和表格，填充 PDF 表单，合并多个 PDF。处理 PDF 文档时使用。`

---

## Skill 存哪里

Pi 按以下顺序查找 Skill（优先级从低到高）：

| 位置 | 路径 | 说明 |
|------|------|------|
| 全局 | `~/.pi/agent/skills/` | 所有项目都能用 |
| 全局（兼容） | `~/.agents/skills/` | 兼容 Claude Code |
| 项目级 | `.pi/skills/` | 只在当前项目生效 |
| 项目级（兼容） | `.agents/skills/` | 兼容 Claude Code |
| npm 包 | `package.json` 里的 `pi.skills` | 通过 npm 分发 |

**最简单的用法**：把你的 Skill 文件夹放进 `~/.pi/agent/skills/`，Pi 启动时自动发现。

---

## 直接用 Claude Code 的 Skill

Pi 支持从其他 Agent 工具导入 Skill，不需要重新写。

```bash
# 共用 Claude Code 的 Skill
# 在 ~/.pi/settings.json 里加一行：
{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}
```

Pi 会自动扫描这些目录，把 Claude Code 写好的 Skill（比如 PDF 处理、网页开发）直接拿来用。

---

## 使用 Skill 的命令

写好之后，在 Pi 里调用：

```bash
/skill:pdf-processing           # 加载并执行
/skill:pdf-processing extract   # 加载并传入参数
```

参数会作为 `User: <args>` 追加到 Skill 内容末尾，AI 知道你要干什么。

**关闭 Skill 自动发现**（如果需要完全控制）：

```bash
pi --no-skills
# 但用 --skill <路径> 仍然可以手动加载
pi --skill ./my-custom-skill
```

---

## Pi 官方的 Skill 仓库

作者 Mario Zechner（@badlogic）在 GitHub 上维护了一个 Skill 合集：

**[github.com/badlogic/pi-skills](https://github.com/badlogic/pi-skills)**

目前已有：

| Skill | 用途 |
|-------|------|
| brave-search | 网页搜索 + 内容提取 |
| browser-tools | 浏览器自动化 |
| gccli | Google Calendar 日历管理 |
| gdcli | Google Drive 文件管理 |
| gmcli | Gmail 邮件收发 |
| transcribe | 音视频转文字 |
| vscode | VS Code 集成操作 |
| youtube-transcript | YouTube 字幕抓取 |

这些 Skill 是 Pi 专属的，比 Claude Code 的 Skill 更轻量，按需加载。

---

## Anthropic 官方的 Skill 仓库

Anthropic 也在维护一套 Skill，支持多种 Agent 工具：

**[github.com/anthropics/skills](https://github.com/anthropics/skills)**

文档处理类 Skill 比较全：docx、pdf、pptx、xlsx 的读取和操作都有。

使用方法（克隆到本地后配置路径）：

```bash
git clone https://github.com/anthropics/skills.git ~/anthropic-skills
```

然后在 `~/.pi/settings.json` 添加：

```json
{
  "skills": [
    "~/.pi/agent/skills",
    "~/anthropic-skills"
  ]
}
```

---

## 怎么写一个好 Skill

**核心原则**：description 要具体，AI 靠这段文字决定什么时候加载。

❌ 常见错误：
- description 太模糊：`Helps with data processing.`
- 没有告诉 AI 在什么场景用
- 步骤写得太细，AI 不需要你手把手教

✅ 好的 Skill：
1. **description** 说清楚「在什么场景用」，不是「做什么」
2. **Setup** 写一次性安装命令（如果需要）
3. **Usage** 写清楚脚本怎么调用
4. **边界情况** 写清楚 AI 容易踩的坑

---

## 实战：写一个「代码审查 Skill」

场景：你经常需要 AI 帮你做代码审查，你希望 AI 每次都按统一标准来做。

**Step 1：创建目录**

```
~/.pi/agent/skills/code-review/
```

**Step 2：写 SKILL.md**

```markdown
---
name: code-review
description: 对代码进行结构化审查，检查命名规范、安全漏洞、性能问题、可读性。适用于 Pull Request 审查或日常代码检查。
---

# 代码审查工具

## 审查维度

每次审查从以下四个维度打分：

1. **命名规范**：变量/函数/文件名是否清晰一致
2. **安全漏洞**：硬编码凭证、SQL 注入风险、未处理的异常
3. **性能问题**：循环内查数据库、N+1 查询、同步阻塞
4. **可读性**：过长函数（>50行）、嵌套过深（>3层）、无注释关键逻辑

## 使用方法

```bash
./review.sh <文件或目录路径> [--verbose]
```

## 评分标准

| 分数 | 说明 |
|------|------|
| A | 四个维度全部达标 |
| B | 一个维度有改进空间 |
| C | 存在安全漏洞，需修复 |
| D | 存在严重问题，建议重构 |

## 注意事项

- 优先审查最近修改的文件，不是整个代码库
- 对框架特有写法（如 React Hooks 规则）先确认项目规范
- 安全类问题必须给出具体修复代码，不只是描述
```

---

## 常见问题

### Q1：Pi 启动时没发现我的 Skill

检查三点：
1. `SKILL.md` 是否在 Skill 文件夹根目录
2. `name` 字段是否符合规范（小写字母、数字、连字符）
3. `description` 是否存在（缺 description 的 Skill 不加载）

### Q2：Skill 和 Extension 有什么区别

| 对比 | Skill | Extension |
|------|-------|----------|
| 技术栈 | Markdown + 脚本 | TypeScript |
| 加载方式 | 按需（AI 判断） | 启动时加载 |
| 能做的事 | 指令 + 脚本 | 注册工具、拦截事件、定制 UI |
| 写起来 | 5 分钟 | 1-2 小时 |

先用 Skill，试不下来再考虑 Extension。

### Q3：Skill 里的脚本需要安装依赖

Skill 的 `scripts/` 目录在 `SKILL.md` 的 `Setup` 段落写清楚安装命令，AI 第一次使用时知道怎么装。

### Q4：Skill 的 description 会不会浪费上下文

不会。Pi 只有在判断需要时才加载完整 SKILL.md，日常对话只加载 description（几句话），上下文占用极小。

---

## 写在最后

Skills 是 Pi 最被低估的功能之一。

内置工具解决的是「AI 能做什么」，Skills 解决的是「你让它做什么更专业」——把团队的经验、项目踩过的坑，封装成 Skill 教给 AI，每次遇到同类问题，AI 自动走对的路。

**别小看这一步**：一个好的 Skill = 你花 1 小时写的经验，能给 AI 用 100 次。

---

摘要

标签多个标签用逗号分隔

分类