给AI Agent注入可复用技能:phi中SKILL.md Skills编写与管理实战

原创2026-10-31 23:33:591,857 阅读

给AI Agent注入可复用技能:phi中SKILL.md Skills编写与管理实战

phi 是一款运行在终端里的高速编码智能体(terminal coding agent),它的 Skills(技能)机制允许你用一份份 SKILL.md 文件,把"可复用的工作流"直接注入 AI Agent 的上下文。本文以实战方式讲解:SKILL.md 怎么写、技能放在哪个目录、优先级如何裁决、以及如何在 TUI 面板中手动点选技能,帮你快速把团队规范沉淀为 Agent 的"肌肉记忆"。

phi终端编码智能体界面,SKILL.md Skills技能系统的宿主环境

什么是 Skills:给Agent注入可复用流程

在 phi 中,一个技能 = 一个目录 + 一份 SKILL.md 文件。文件由两部分组成:

  • YAML frontmatter(--- 包裹):声明技能的 name、description 等元信息;
  • Markdown 正文:Agent 应当遵循的操作指引、步骤、约束。

所有技能会被自动发现并注入 Agent 的上下文,让模型在处理匹配任务时"按章办事",而不是每次从零发挥。解析与加载逻辑集中在 internal/llm/skills/skills.go。

phi Agent 按技能与工具协同执行任务的过程,思考链与Shell命令流

SKILL.md 结构速览:5 个 frontmatter 字段

一个完整的技能文件长这样:

---
name: Test Report
description: 编写结构化测试报告,覆盖用例、结果与结论
license: MIT
compatibility: claude, openai
disable-model-invocation: false
---
当用户要求输出测试报告时:
1. 先运行 `go test ./...` 收集结果
2. 按「用例 / 结果 / 结论」三段输出
3. 失败用例必须附上关键日志

各字段含义:

字段 说明
name 技能展示名;缺省时用目录名兜底
description 技能用途说明,是模型判断"该不该用"的关键
license 许可证声明(可选)
compatibility 适配的模型系列(可选)
disable-model-invocation 设为 true 后技能从系统提示词目录中隐藏,但仍可在面板手动选中

两个容易踩坑的细节:

  • frontmatter 只支持扁平的 key: value(含 >、| 块标量),不支持嵌套 YAML,详见 Parse 实现;
  • 解析失败的文件会被静默跳过,一个坏文件不会拖垮其他技能(见 LoadSkills)。

技能放在哪里:4 类加载目录与优先级

phi 按固定顺序搜索技能目录,同名技能由靠前的目录胜出:

优先级 目录 适用场景
1 skill_path 指定的目录(默认 ~/.phi/skills/) 你个人最常用的技能库
2 ~/.agents/skills/ 通用 Agent Skills 规范的全局技能
3 项目内 .agents/skills/(从工作目录逐级向上,直到 git 仓库根) 随仓库分发的项目级技能

三种自定义方式:

  • 配置文件 ~/.phi/config.yaml 中设置 skill_path: ~/my-skills;
  • 环境变量 PHI_SKILL_PATH(优先级更高,见 配置解析);
  • 什么都不配——直接用默认目录,零配置开箱即用。

目录裁决逻辑在 resolveSkillPaths,同名去重由 LoadAll 完成。这意味着:团队把技能放进项目 .agents/skills/ 随仓库走,个人想覆盖时放进 ~/.phi/skills/ 即可"本地化改写"。

技能如何进入 Agent 的上下文

技能注入采用"目录 + 按需展开"的渐进式策略,节省 token 的同时保证信息完整:

  1. 启动会话时,技能目录(name + description + 文件路径)被渲染进系统提示词,模板见 skills-prompt.tmpl,注入逻辑在 skillsBlock;
  2. 当任务匹配某个技能时,模型会先读取该技能的 SKILL.md 全文再执行,且正文中的脚本/资源路径相对于技能所在目录解释;
  3. disable-model-invocation: true 的技能不在目录里出现,适合"只在需要时手动点名"的场景。

⚠️ 注意:disable-model-invocation 只是目录过滤器,不是权限控制——文件仍可通过磁盘被读到,真正的访问控制要靠权限策略。

在 TUI 中手动点选技能

自动注入之外,TUI 还提供技能面板进行精确点名:

  1. 在命令面板(Ctrl+K)输入 skills,进入 Select skill 子菜单(面板构建见 buildSkillsPalette);
  2. 勾选一个或多个技能,它们以标签形式显示在输入框中(可退格逐个移除);
  3. 发送消息时,phi 会追加一条强制指令:"You MUST read these skill files first with the read tool and follow them"(实现见 pendingSkillsInstruction),确保模型第一时间遵循所选技能。

这套"勾选 → 注入 → 强制读取"的链路,让同一个 Agent 能按不同任务切换"专业模式",例如写文档时挂 test-report、发布前挂 release-checklist。

实战:编写你的第一个技能

第 1 步:创建技能目录

mkdir -p ~/.phi/skills/test-report

第 2 步:编写 SKILL.md(frontmatter + 正文,正文写清步骤与输出格式)

第 3 步:重启 phi 并验证

  • 系统提示词目录中应出现该技能的 name 与 description;
  • 相关任务中,Agent 会先读 SKILL.md 再动手;
  • 也可用 Ctrl+K → skills 手动选中确认生效。

编写技巧:description 要写清"何时使用"(模型靠它做匹配);正文用编号步骤、给出可复制的命令;把常用脚本放进技能目录,正文里用相对路径引用。

常见问题与安全提示

  • 技能没出现? 检查 frontmatter 是否以 --- 开头并正确闭合——格式错误会被跳过且不报错;
  • 同名技能冲突? 按上文优先级表,skill_path 永远优先于 ~/.agents/skills,后者优先于项目目录;
  • 安全:技能文件属于工作区内容,不是可信输入——项目里的 .agents/skills/ 会被无确认加载,请先审查再信任一个仓库(官方提醒见 README.zh-CN.md)。

小结

phi 的 Skills 机制用最小的成本解决了 AI Agent 的能力复用问题:一个目录 + 一份 SKILL.md,就能把测试流程、发布清单、文档规范沉淀为可分发、可覆盖、可手动点选的资产。配合 skill_path 配置、多级目录优先级与 TUI 技能面板,无论是个人效率提升还是团队规范落地,都能快速跑起来。

登录后查看全文
phi