pix-skills Skill 技能

技能简介

@xynogen/pix-skills 是 Pi 编码 Agent 的扩展，提供 skill 加载工具 + 29 个 bundled skills。它的 read_skills 工具既可读取本地 skills（按 SKILL.md frontmatter 自动发现），也可搜索 Skills.sh 并按需拉取 + 加载个人级 公共 GitHub 仓库里的 Skill，所有远端 skill 都缓存到 ~/.cache/pi/skills.sh/。设计上把"bundle skill 默认不进上下文、发现与加载显式两步走"作为铁律，避免系统 prompt 被无关 skill 描述膨胀。适合 Pi 用户、希望探索 Skills.sh 生态、需要在多个项目间复用 skill 集合的工程师。

核心能力

• read_skills 工具集：浏览本地 skills、按 name 读取 description、full=true 加载完整流程、按 references/ 读取资源、按 output= 复制资源到当前项目。
• 29 个 bundled skills：所有 bundle 的 skill 都在 disable-model-invocation: true 的 frontmatter 下默认不进上下文，按需通过 read_skills 加载。
• Skills.sh 搜索：通过 read_skills(search=) 检索 Skills.sh 而不下载任何东西；只有显式 fetch 才加载。
• 远端 skill 显式缓存：通过 read_skills(source=, name=, full=true) 显式从 GitHub 拉取并加载；refresh=true 重新拉取。
• 远端信任边界：仅从 validated public GitHub owner/repo 拉取；按 SKILL.md frontmatter name 匹配；文件 / 字节限制；只保留 SKILL.md + references/ + scripts/ + assets/。
• $ Skill picker：在 token 边界（行首或空白后）按 $ 打开 picker，本地 skills 模糊匹配，2+ 字符后接入 Skills.sh 搜索；⏎ 插入 name（本地）或 owner/repo@name（远端）。
• 离上下文设计：bundled skills 通过 disable-model-invocation: true 显式不进入系统 prompt，保留精简 baseline context。
• 跨层 skill layout：支持现行 flat layout（skills/debug.md）与目录 bundle（skills/debug/SKILL.md），后者允许带 references/ / scripts/ / assets/。
• 用户级 skill 目录：除 bundled 外还自动发现 ~/.pi/agent/skills/；bundled 同名时优先 bundled。
• 回退到主动注入：可显式删除 frontmatter 让 skill 重新进入自动注入路径。

安装配置

1. 前置环境：已安装 Pi（badlogic/pi）；Node.js 满足 Pi 要求。
2. 作为 Pi 扩展安装：在项目或全局 package.json 添加 "pi": {"extensions": ["@xynogen/pix-skills"]}，自动加载 read_skills 工具与 bundled skills。
3. 可选安装位置：可设置 XDG_CACHE_HOME 自定义缓存目录，默认是 ~/.cache/pi/skills.sh/。
4. Skill picker 配置：在 ~/.pi/agent/settings.json 中设 "enableSkillCommands": false 隐藏 Pi 原生的 /skill:name 入口，让 $ picker 成为唯一方式。
5. 远端资源限制：可在配置中调整远端拉取的字节 / 文件上限；bundled skills 不受影响。
6. 缓存清理：手动删除 ~/.cache/pi/skills.sh/ 下对应目录即可失效指定远端 skill。

使用步骤

1. 安装扩展：按上文把 @xynogen/pix-skills 加入 Pi 扩展；重启 Pi 加载。
2. 浏览本地 skills：调 read_skills() 一行列出所有 bundled skill 名字（独立目录扫描，不走 prompt registry）。
3. 按需加载：调 read_skills(name=, full=true) 把完整 SKILL.md 流程注入到当前上下文。
4. 读取参考资源：调 read_skills(name=, resource=references/) 读取 references 下的 UTF-8 资源。
5. 复制资源到项目：调 read_skills(name=, resource=, output=) 把 references / scripts / assets 复制到当前项目。
6. 搜索 Skills.sh：调 read_skills(search="hallmark") 只检索不下载；浏览结果后选一个。
7. 远端拉取：调 read_skills(source="nutlope/hallmark", name="hallmark", full=true) 显式拉取并加载；refresh=true 重拉。
8. 使用 picker：在 prompt 行首或框中（行首或空白后）按 $ 打开 picker，模糊匹配后 ⏎ 插入对应 token。
9. 回退到主动注入：删除某个 skill frontmatter 中 disable-model-invocation: true 行（或设为 false），让 Pi 启动时按 description 匹配自动加载。

适用场景

• Pi 用户的 Skill 生态接入：希望把 Pi 用作 Skill 加载与缓存的统一入口。
• 跨项目复用 Skill 集合：bundled 29 个 skill + 用户级 ~/.pi/agent/skills/ 让跨项目共享 skill 一行命令完成。
• Skills.sh 浏览与按需加载：希望"先浏览再决定加载"，避免被无关 skill 描述污染上下文。
• 远端 skill 探索：在不自动下载的前提下检索 Skills.sh，需要长按测试后再显式拉取。
• 轻量 baseline context：默认所有 bundled skill 不进系统 prompt，按需加载，控制 token 用量。
• Skill picker 替代原生命令：用 $ picker 替代 /skill:name，减少 prompt 入口。

适用人群

• Pi 编码 Agent 用户：希望把 Pi 武装成完整 Skill 平台。
• AI 编程工具作者：希望让自己的 skill 在 Pi 生态里分发。
• Skills.sh 探索者：希望安全地浏览 + 按需引入远端 skill。
• 多项目开发者：希望共享同一套 bundled skill 集合。

官方链接

• npm 包：https://www.npmjs.com/package/@xynogen/pix-skills
• 仓库：https://github.com/xynogen/pix-mono
• Skill 路径：https://github.com/xynogen/pix-mono/tree/main/packages/pix-skills
• Skills.sh：https://skills.sh/
• License：MIT