给AI Agent注入可复用技能:phi中SKILL.md Skills编写与管理实战
给AI Agent注入可复用技能:phi中SKILL.md Skills编写与管理实战
phi 是一款运行在终端里的高速编码智能体(terminal coding agent),它的 Skills(技能)机制允许你用一份份 SKILL.md 文件,把"可复用的工作流"直接注入 AI Agent 的上下文。本文以实战方式讲解:SKILL.md 怎么写、技能放在哪个目录、优先级如何裁决、以及如何在 TUI 面板中手动点选技能,帮你快速把团队规范沉淀为 Agent 的"肌肉记忆"。
什么是 Skills:给Agent注入可复用流程
在 phi 中,一个技能 = 一个目录 + 一份 SKILL.md 文件。文件由两部分组成:
- YAML frontmatter(
---包裹):声明技能的name、description等元信息; - Markdown 正文:Agent 应当遵循的操作指引、步骤、约束。
所有技能会被自动发现并注入 Agent 的上下文,让模型在处理匹配任务时"按章办事",而不是每次从零发挥。解析与加载逻辑集中在 internal/llm/skills/skills.go。
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 的同时保证信息完整:
- 启动会话时,技能目录(name + description + 文件路径)被渲染进系统提示词,模板见 skills-prompt.tmpl,注入逻辑在 skillsBlock;
- 当任务匹配某个技能时,模型会先读取该技能的
SKILL.md全文再执行,且正文中的脚本/资源路径相对于技能所在目录解释; disable-model-invocation: true的技能不在目录里出现,适合"只在需要时手动点名"的场景。
⚠️ 注意:disable-model-invocation 只是目录过滤器,不是权限控制——文件仍可通过磁盘被读到,真正的访问控制要靠权限策略。
在 TUI 中手动点选技能
自动注入之外,TUI 还提供技能面板进行精确点名:
- 在命令面板(
Ctrl+K)输入skills,进入 Select skill 子菜单(面板构建见 buildSkillsPalette); - 勾选一个或多个技能,它们以标签形式显示在输入框中(可退格逐个移除);
- 发送消息时,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 技能面板,无论是个人效率提升还是团队规范落地,都能快速跑起来。

