Skills 和 Extensions 是什么

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

日常使用 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 格式示例：

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

# PDF 处理工具

## 安装

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

使用方法

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

## 注意事项

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

SKILL.md 的 frontmatter 规范

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

---
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（优先级从低到高）：

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

直接用 Claude Code 的 Skill

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

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

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

使用 Skill 的命令

写好之后，在 Pi 里调用：

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

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

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

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

Pi 官方的 Skill 仓库

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

github.com/badlogic/pi-skills

目前已有：

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

Anthropic 官方的 Skill 仓库

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

github.com/anthropics/skills

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

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

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

然后在 ~/.pi/settings.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

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

# 代码审查工具

## 审查维度

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

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

## 使用方法

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

评分标准

注意事项

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

常见问题

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

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

Q2：Skill 和 Extension 有什么区别

先用 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 次。