第 02 模块 · 3 节

技能命令与跨 Harness 复用

《Pi 进阶实战》02 自定义技能 Skills · 本节时长 32 分钟

贯穿项目技能写好了，得让它能「一键调用」——这就是 /skill:md-tools。更妙的是，技能标准是跨工具的，你写的这个包甚至可以给 Claude Code、Codex 用。这一节让 md-tools 技能真正可复用。

用 /skill:name 调用技能

技能会注册成 /skill:name 形式的命令。官方示例：

/skill:brave-search              # 加载并执行技能
/skill:pdf-tools extract         # 加载技能并带参数

命令后的参数会作为 User: 追加到技能内容后面。对我们的 md-tools：

/skill:md-tools
/skill:md-tools stats README.md    # 直接指定参数

这样就不依赖模型「自动想起来」加载技能，而是你主动、确定地触发它。

贯穿项目实战里推荐把「先预览再执行」写进技能正文，这样无论模型自动加载还是你 /skill:md-tools 手动调用，安全规则都会跟着生效。

/skill:name 这类命令可以用设置开关。官方给的是在 settings.json 里：

{
  "enableSkillCommands": true
}

也可以在交互模式下用 /settings 切换。默认开、你想关就关，灵活控制。

这是技能系统最香的能力之一。Claude Code、OpenAI Codex 的技能目录，可以直接塞给 Pi 用。 官方示例是在设置里加目录：

{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

也就是说，你（或团队）在别的工具里沉淀的技能资产，Pi 能直接继承。反过来同理——你给 Pi 写的技能，只要遵循标准，也能被别的工具加载。写一次、处处用。

贯穿项目把 md-tools 技能放进 ~/.pi/agent/skills/（全局），它就能在所有项目里用；再把它加进别的工具的 skills 设置，就能跨 Harness。这就是「封装一次、处处复用」的回报。

对于项目级的 Claude Code 技能，官方给了 .pi/settings.json 里的写法：

{
  "skills": ["../.claude/skills"]
}

用相对路径指向项目里其他工具的技能目录。这样同一个项目里，Claude Code 和 Pi 能共享一套技能，不用重复维护。

怎么判断做对了？——/skill:md-tools 能展开技能内容，带参数也能透传；补全列表能看到它。

卡住了怎么办？ /skill: 没反应 → 检查 enableSkillCommands。参数没进去 → 确认参数写在命令后面、空格隔开。想跨工具 → 用 settings.json 的 skills 数组指向对应目录。

容易踩的坑：技能放进了 .pi/skills/（项目级），却指望所有项目都能用。项目级技能只在本项目生效（且需信任），全局才能处处用。

想清楚你的技能是「给谁用的」：团队共享、跨项目 → 放全局 ~/.pi/agent/skills/；只服务某个项目 → 放 .pi/skills/。位置错了，复用的效果就没了。

下一节进入 M03——提示词模板，用 $1 / $@ 固化你的常用命令。