Pi 的 Extension、Skill 与 Package
图源 · PNG 预览 · 不看图的说明
一句话区分：Skill 是按需读取的工作指导；Extension 是加载到 Pi 进程的代码扩展；Package 是可同时分发两者的容器。 把它们统称“插件”，会掩盖什么时候只是增加上下文、什么时候真正改变工具和事件处理。这里的事实固定在当前 Pi 版本，不自动适用于所有 Agent 产品。
Skill：发现描述，按需读取正文
Pi 的 loadSkills 扫描技能路径并解析 SKILL.md；formatSkillsForPrompt 把可由模型调用的 Skill 的名称、描述和位置放进系统提示，而不是一启动就把全部正文塞进上下文。设置 disable-model-invocation: true 的 Skill 不进入这份提示，但仍可由用户通过 /skill:name 显式调用。加载实现 · 官方使用文档
当任务相关时，模型可经已有的 read 工具读取 SKILL.md；用户也可输入 /skill:name，由 AgentSession._expandSkillCommand 展开完整内容。Skill 可以带脚本、参考资料和资产，并指导模型调用已有工具去运行脚本；但 Skill 文件本身没有注册新工具或订阅事件的 API。因此“不是可执行插件”不等于“没有运行风险”。
Extension：导入模块，注册行为
Extension 是 TS/JS 模块。加载器通过 jiti 导入默认工厂，把 ExtensionAPI 交给它；代码可注册工具、命令和事件处理。加载工厂 · 注册 API · 官方文档
读一个真实而短的示例：仓库自带的 hello.ts。关注默认导出如何取得 API、注册的工具何时成为模型可调用能力，以及工具的参数与结果由谁定义。这里不复制完整源码，读者可以按固定链接逐行看。
二者能组合，但职责仍不同
Extension 可通过 resources_discover 返回 Skill 路径，资源加载流程会再发现这些技能。资源事件链路 · 仓库自带示例。反过来，Skill 可以告诉模型使用某个 Extension 注册的工具，但 Skill 自己并没有变成那个工具。
Pi Package 可从 npm/git 安装并捆绑 Extensions、Skills、Prompt Templates、Themes；它解决分发，不抹平运行权限和提示词边界。第三方 Package 中的 Extension 可执行代码，Skill 可引导模型运行脚本，安装前两者都应审查来源。本篇只做固定源码静态核对，尚未实际安装第三方包或验证沙箱行为。
图的文字说明 · pi-extensions
A 路：Skill 从 Package 或本地目录被发现；loadSkills 解析名称、描述和路径，只有允许模型调用的 Skill 才由 formatSkillsForPrompt 列入系统提示。带有 disable-model-invocation: true 的 Skill 不进入提示，但用户仍可通过 /skill:name 显式展开；提示中可见的 Skill 则可由模型按需经 read 读取。B 路：Extension 的 TS/JS 模块由 jiti 导入，调用 ExtensionAPI 注册工具、事件或命令。同一 Pi Package 可以分发两者；两路也可在 resources_discover 相交，由 Extension 提供新的 Skill 路径。Skill 本身不自动执行脚本，也没有工具注册 API；Skill 附带的脚本由模型经已有工具调用。
本图按固定源码 898ab804 绘制。实现证据见专题正文。
在线预览稿：书稿仍在校稿，系统篇以文内固定源码版本为准；静态阅读不等于运行验收。