Pi Coding Agent 使用教程（二）：Skill、插件、MCP 与常用扩展

一、先理解四种扩展方式

能力	主要作用	是否直接增加工具	典型位置
Skill	给模型一套按需加载的知识和流程	通常否	`~/.pi/agent/skills/`、`.pi/skills/`
Extension（插件）	用 TypeScript 改变 Pi 行为	是，可以	`~/.pi/agent/extensions/`、`.pi/extensions/`
Prompt Template	保存可复用提示词	否	`~/.pi/agent/prompts/`、`.pi/prompts/`
Theme	定制终端外观	否	`~/.pi/agent/themes/`、`.pi/themes/`
Pi Package	打包并分发上述资源	视内容而定	npm 或 Git

Pi 的“插件”在官方术语中通常指 Extension；npm/Git 上的 Pi Package 则可能同时包含多个 Extension、Skill、Prompt 和 Theme。

二、如何使用 Skill

2.1 创建一个最小 Skill

在项目中创建 .pi/skills/review/SKILL.md：

# Review Skill

当用户要求代码审查时使用本 Skill。

## 步骤

1. 先读取项目上下文和测试配置。
2. 只检查与任务相关的文件。
3. 按严重程度列出问题，并给出文件和行号。
4. 不要擅自修改代码，除非用户明确要求。

Pi 官方支持的 Skill 目录包括：

全局：~/.pi/agent/skills/
兼容 Agent Skills 约定的：~/.agents/skills/
项目级：.pi/skills/、.agents/skills/
当前目录向上级目录搜索到的同名目录
Pi Package 中声明的 Skill

2.2 调用 Skill

在交互模式输入：

/skill:review

也可以直接提出符合描述的任务，让 Pi 自动判断是否加载。需要重新发现新增资源时执行：

/reload

命令行还可以显式加载 Skill：

pi --skill ./.pi/skills/review "审查当前项目"

2.3 写好 Skill 的原则

描述触发条件，而不是堆积泛泛知识。
给出可执行步骤、输入输出和停止条件。
明确哪些操作必须先征得确认。
不在 Skill 中写入密钥、Cookie 或私人路径。
一个 Skill 聚焦一个工作流，避免做成巨型系统提示词。
将稳定规范放入 AGENTS.md，将按需流程放入 Skill。

三、如何使用 Extension（插件）

3.1 加载已有插件

pi -e ./extensions/my-extension.ts
pi --extension npm:@example/pi-tools
pi --extension git:github.com/user/repo

也可以把 Extension 放到以下目录，让 Pi 自动发现：

~/.pi/agent/extensions/
.pi/extensions/
Pi Package 的 extensions 目录

3.2 一个简单插件

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerCommand("hello", {
    description: "显示一条测试消息",
    handler: async (_args, ctx) => {
      ctx.ui.notify("Hello from Extension", "info");
    },
  });
}

启动后输入：

/hello

实际 ExtensionAPI 的具体类型和回调字段应以当前版本示例、类型定义和官方 Extension 文档为准；不要只复制旧教程中的 API。

3.3 插件适合做什么

注册项目专用命令和工具。
增加部署前确认、路径保护和权限门。
接入 Git 检查点、测试流水线或远程执行。
实现计划模式、子 Agent 编排或自定义压缩。
添加 MCP 客户端适配层。
修改状态栏、消息界面和快捷键。

3.4 安全注意事项

Extension 是可执行 TypeScript 代码。Pi 官方说明，插件可以拥有完整系统权限，因此安装第三方插件前要检查源码、依赖、网络请求、命令执行和凭据处理。对于不可信插件，优先在隔离环境中测试。

四、如何使用 Pi Package

4.1 安装、查看和更新

pi install npm:@foo/pi-tools
pi install npm:@foo/pi-tools@1.2.3
pi install git:github.com/user/repo@v1
pi list
pi config
pi update --extensions
pi update --all
pi remove npm:@foo/pi-tools

项目级安装使用 -l：

pi install -l npm:@foo/pi-tools

4.2 创建 Package

package.json 可以声明：

{
  "name": "my-pi-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

没有显式 pi 清单时，Pi 也会按约定目录自动发现资源。

五、MCP 在 Pi 中的正确理解

5.1 官方现状

Pi 官方 README 明确写出：Pi 核心不内置 MCP。官方建议使用 CLI 工具配合 README/Skill，或者编写 Extension 来实现 MCP 支持。

这意味着不能假定存在某个内置的 mcp.json、/mcp 命令或与其他 Coding Agent 完全相同的配置格式。不同社区插件可能采用不同配置方式。

5.2 方案 A：把 MCP 服务能力包装成 CLI + Skill

这是最简单、最可审计的方式：

使用 MCP 服务商提供的 CLI 或自行编写一个小型 CLI。
在 Skill 中描述命令参数、返回格式和安全边界。
让 Pi 使用内置 bash 调用它。

例如 Skill 中可以约定：

# Issue Lookup

仅在用户明确要求查询 Issue 时使用。
执行 `./tools/issues get <id> --json`，不要执行写入或关闭 Issue 的命令。
先展示查询结果，再等待用户确认任何修改操作。

优点是流程透明、易测试、易限制权限；缺点是需要自己维护 CLI 和结果解析。

5.3 方案 B：通过 Extension 接入 MCP Client

Extension 可以在启动时创建 MCP 客户端，把远程 MCP 的工具转成 Pi 的自定义工具，再通过 registerTool 暴露给模型。典型流程是：

在 Extension 中读取经过审查的 MCP 配置。
创建 MCP transport 和 client。
获取服务端工具列表。
为每个工具注册输入 Schema 和调用逻辑。
将错误、超时、取消和权限确认传回 Pi。
在 Extension 卸载或进程结束时关闭连接。

因为 Pi 核心不规定 MCP 配置格式，具体 SDK、transport 和字段必须以所选 MCP 客户端库及插件文档为准。不要把远程工具默认视为可信工具，尤其要限制写操作、网络目标和凭据范围。

5.4 MCP 安全清单

优先使用本地、固定版本、可审计的 MCP Server。
为读操作和写操作分开配置。
限制允许访问的目录、网络域名和数据库。
对删除、发布、支付、迁移等工具增加人工确认。
不把 API Key 写入 Skill、Prompt 或仓库。
记录调用日志，但避免记录令牌和敏感业务数据。
对 JSON Schema、返回内容和错误消息做校验，防止提示词注入扩散。
先使用 --tools 或 --exclude-tools 限制可用工具。

六、按高频需求推荐的前 3 类能力

以下不是官方使用量排名，而是面向大多数开发者的“优先安装/构建顺序”。

第 1 类：代码审查与测试 Skill

适合人群： 所有软件项目和文档项目。

常见功能： 读取项目规范、定位入口、检查安全问题、运行针对性测试、输出带文件和行号的报告。

推荐原因： 不需要额外系统权限，收益稳定，最容易通过 SKILL.md 固化团队流程。

建议组合： AGENTS.md 写长期项目规则，review、test、debug 分别写成小 Skill。

第 2 类：Git、变更检查与发布辅助 Extension

适合人群： 需要频繁提交、审查和发布的团队。

常见功能： 查看 diff、生成提交摘要、创建检查点、运行 CI 前检查、发布前确认。

推荐原因： Extension 可以注册命令和权限门，比单纯提示词更能强制执行流程。

注意： 不建议插件自动执行 git push、部署或删除；应默认只读，并在关键动作前请求确认。

第 3 类：外部知识、Issue 和数据库访问能力（CLI 或 MCP Extension）

适合人群： 需要查询 GitHub、工单系统、文档库、数据库或内部 API 的团队。

常见功能： 查询 Issue、读取项目文档、查日志、获取只读数据。

推荐原因： 能把 Pi 从“本地代码助手”扩展为“项目工作流助手”。

建议顺序： 先用只读 CLI + Skill 验证需求，再在确有必要时接入 MCP；最后才开放写操作。

七、常用工作流示例

7.1 使用审查 Skill

/skill:review
审查最近一次提交，先只报告问题，不修改文件。

7.2 加载项目插件

pi --no-extensions -e ./.pi/extensions/safe-git.ts

这会关闭自动发现的 Extension，只加载明确指定的插件，适合排查加载冲突或安全测试。

7.3 限制为只读工具

pi --tools read,grep,find,ls -p "检查当前项目是否存在硬编码密钥"

7.4 组合 Skill 和 Prompt

/skill:release-check
/release
请先检查版本、变更日志、测试和工作区状态，不要执行发布。

八、选择建议

只是补充知识和步骤：用 Skill。
需要新工具、命令、事件或 UI：用 Extension。
需要团队共享一组资源：用 Pi Package。
只是固定一段提示词：用 Prompt Template。
需要外部服务：优先 CLI + Skill，复杂场景再使用 MCP Extension。
需要隔离：使用容器或沙箱；Pi 默认以启动它的用户权限运行。

参考来源

Pi 官方仓库：https://github.com/badlogic/pi-mono
@earendil-works/pi-coding-agent README：https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent
Pi 官方网站：https://pi.dev

Pi Coding Agent 使用教程（二）：Skill、插件、MCP 与常用扩展#

一、先理解四种扩展方式#

二、如何使用 Skill#

2.1 创建一个最小 Skill#

2.2 调用 Skill#

2.3 写好 Skill 的原则#

三、如何使用 Extension（插件）#

3.1 加载已有插件#

3.2 一个简单插件#

3.3 插件适合做什么#

3.4 安全注意事项#

四、如何使用 Pi Package#

4.1 安装、查看和更新#

4.2 创建 Package#

五、MCP 在 Pi 中的正确理解#

5.1 官方现状#

5.2 方案 A：把 MCP 服务能力包装成 CLI + Skill#

5.3 方案 B：通过 Extension 接入 MCP Client#

5.4 MCP 安全清单#

六、按高频需求推荐的前 3 类能力#

第 1 类：代码审查与测试 Skill#

第 2 类：Git、变更检查与发布辅助 Extension#

第 3 类：外部知识、Issue 和数据库访问能力（CLI 或 MCP Extension）#

七、常用工作流示例#

7.1 使用审查 Skill#

7.2 加载项目插件#

7.3 限制为只读工具#

7.4 组合 Skill 和 Prompt#

八、选择建议#

参考来源#