Flue Skills 实战指南:用 SKILL.md 为 Agent 打包可复用的专家技能

原创2026-10-10 20:15:18392 阅读
文章标签:人工智能AI AgentAgent 框架工具调用MCP 服务AI 技能Agent 沙箱

Flue Skills 实战指南:用 SKILL.md 为 Agent 打包可复用的专家技能

本指南围绕 flue(sandbox agent framework)的 Skills 机制展开:它教你如何把一段可复用的"操作规程"写成标准 SKILL.md,通过导入或工作区发现两种方式挂载给 Agent,并在激活时才注入完整指令。读完你将掌握渐进式披露技能目录的完整编写规范、useSkill / defineSkill 两种挂载写法、activate_skill 与 read_skill_resource 的底层激活流程,以及打包时的安全边界。

什么是 Skill:与 Tool 的本质区别

在 Flue 中,skill 把可复用的专家能力打包成 Markdown 指令(可选附带支撑文件),Agent 只在需要时加载它。与 tool 指南 中"执行应用代码"的工具不同,skill 教给 Agent 的是一个流程:tool 是执行器,skill 是说明书。

Skill 遵循开放的 Agent Skills 格式,因此为 Flue 编写的技能也能在同样支持该格式的其他 harness 中原样运行,第三方技能也能不改动地放入你的 Agent。

Skill 的三要素

每个技能由三部分组成:

  • name —— 短标识符(如 refunds、review-pr),模型用它来激活技能。
  • description —— 一两句话说明技能"做什么"以及"何时用"。这是模型始终可见的唯一部分,整个路由决策都由它承载。
  • instructions —— 完整操作流程,仅在激活时加载。

技能还可以携带支撑文件(checklist、模板、参考资料),在模型明确读取之前保持未加载状态。

渐进式披露:挂载几十个技能也不涨 Token

技能采用**渐进式披露(progressively disclosed)**设计:每个已挂载技能在系统提示词中只占一行常驻目录条目(name + description),除此之外直到模型判定当前任务匹配为止不再增加任何内容。激活时才收到完整指令,支撑文件按需读取。因此一个 Agent 可以携带几十个技能,却不必为它们的内容在每个回合付出上下文代价。

编写技能目录:SKILL.md 格式

磁盘上的技能是一个包含 SKILL.md 的目录。frontmatter 存放 name 和 description,Markdown 正文就是 instructions,目录内其他文件都成为支撑文件:

src/skills/refunds/
├─ SKILL.md        # frontmatter + instructions
└─ POLICY.md       # supporting file, loaded only if read

一个完整的退款技能示例:

---
name: refunds
description: Process a customer refund request end-to-end. Use when a customer asks for a refund or disputes a charge.
---

Follow this procedure for every refund request:

1. Confirm the order ID and the reason for the refund.
2. Read `POLICY.md` and check the eligibility rules for that reason.
3. If eligible, issue the refund with the `issue_refund` tool and confirm the amount to the customer.
4. If not eligible, explain which rule applies and offer the alternatives listed in the policy.

description 是模型判断技能是否适用时唯一阅读的内容——务必同时写明能力和触发条件("Use when…")。SKILL.md 正文应专注于流程本身,把体积大的参考资料挪进 instructions 指向的支撑文件。

仓库自带的真实例子完全符合该结构:imported-skill 示例 声明了 review 技能并指向同目录的 CHECKLIST.txt;hello-world 的工作区技能 则演示了带触发条件的 description。

Frontmatter 字段与校验规则

Flue 对每一个 SKILL.md 都按 Agent Skills 规范校验,无论技能是导入的还是在工作区发现的。校验逻辑实现在 skill-frontmatter.ts:

  • name(必填)—— 小写字母、数字和连字符;不能以连字符开头/结尾,不能出现连续连字符;最长 64 字符;必须与技能目录名一致。实现层面通过正则 ^[a-z0-9-]+$ 加首尾/连续连字符检查逐项验证,目录名不匹配会直接报错。
  • description(必填)—— 非空,最长 1024 字符,说明技能做什么以及何时用。
  • license(可选)—— 接受,仅作信息记录。
  • compatibility(可选)—— 接受,最长 500 字符,仅作信息记录。
  • metadata(可选)—— 接受,字符串到字符串的映射,Flue 不解释其含义。
  • allowed-tools(可选)—— 接受但不强制。该字段在 Agent Skills 规范中尚属实验性,不同实现支持程度不一;Flue 仅为兼容性保留它,不据此执行任何行为。

安全提示:allowed-tools 只是技能作者"预期使用"的工具清单,它不限制技能实际能调用什么。授权边界要在你自己的工具和 approval gates 里落实。

未知的 frontmatter 字段会被忽略——这样携带宿主特定扩展字段的第三方技能仍能正常加载。parseSkillMarkdown 使用 YAML 的 FAILSAFE_SCHEMA 解析 frontmatter(与 skills-ref 参考实现保持一致),确保 version: 1.0 这类未加引号的值仍按字符串处理。如果你想要更严格的作者侧检查,可以使用规范自带的 skills-ref 校验器来标记未知字段。

导入并挂载一个技能

导入 SKILL.md 文件就像导入任何模块一样,通过模块说明符(module specifier)完成。构建时 Flue 识别该导入、校验 frontmatter,并把整个目录打包进应用。导入的值是一个带类型的 SkillReference,用 useSkill hook 挂载:

'use agent';
import { useModel, useSkill } from '@flue/runtime';
import refunds from '../skills/refunds/SKILL.md';

export function SupportAgent() {
  useModel('anthropic/claude-haiku-4-5');
  useSkill(refunds);
  return 'Answer customer support questions clearly and accurately.';
}

没有注册步骤,也没有运行时文件拷贝——导入即声明,并且在项目任何构建场景下都生效:dev server、vite build、flue run。SKILL.md 和 .md 导入的类型声明随 @flue/runtime 一起发布;开发模式下,编辑技能目录中的任何文件都会自动触发热更新。这一转换逻辑位于 markdown-import-plugin.ts:凡是解析到名为 SKILL.md 的导入会被打包成技能模块,其余 .md 导入作为纯文本模块加载。

从 npm 包导入技能同理:

import review from '@acme/review-skills/review/SKILL.md';

包必须发布 SKILL.md 及其支撑文件;如果包定义了 exports 字段,则必须导出被导入的 SKILL.md 子路径。

必须知道的几条规则

  • 技能导入必须是静态的——动态 import('./skills/x/SKILL.md') 属于构建错误(插件通过 AST 扫描 ImportExpression 直接拒绝)。
  • 每个技能名每次渲染只挂载一次;同一渲染内重复挂载同名技能会抛错。useSkill 的实现会检查当前渲染帧已挂载列表,发现重名即抛出 <a href="https://link.gitcode.com/i/8059ab3f21461218c1bfa3f7e8887572" target="_blank">flue] useSkill() mounted the skill name "..." twice in one render.(见 [use-skill.ts)。
  • 打包时会跳过仓库噪音目录(node_modules、.git、dist 等,见插件中维护的 EXCLUDED_DIRECTORIES 集合),对超过 1MB 的文件给出警告,并且拒绝打包机密——.env 文件、私钥、凭据存储以及符号链接都会直接报硬错误。插件把 .aws、.gnupg、.ssh 等敏感目录以及 .key、.pem、.p12、.pfx 后缀和 secrets 前缀的敏感文件列为打包红线。

条件挂载:对话中途解锁技能

挂载可以是条件式的,像所有资源 hook 一样——把 useSkill(...) 建立在 persistent state 之上,就能在对话中途解锁技能。运行时会把目录变更以 resources 信号通告给模型,且不会使已缓存的提示词失效,具体机制见 Dynamic resources。

用 defineSkill 内联声明技能

当技能内容很短、是动态生成或由数据拼装而来时,可以直接用 defineSkill(...) 在代码里声明:

import { defineSkill } from '@flue/runtime';

export const escalation = defineSkill({
  name: 'escalation',
  description:
    'Escalate an unresolved case to a human specialist. Use when the customer asks for a human or the issue is out of scope.',
  instructions:
    'Summarize the case so far, tag the conversation with the escalation reason, and hand off with the `escalate_case` tool.',
});

把结果像导入一样传给 useSkill(escalation)。一个定义等价于一个技能目录:instructions 就是 SKILL.md 正文,可选的 files 映射以相对路径为键携带支撑资源:

const reviewSkill = defineSkill({
  name: 'review-pr',
  description: 'Review a pull request against the team checklist. Use when asked to review code.',
  instructions: 'Read CHECKLIST.md, then review the diff against every item.',
  files: { 'CHECKLIST.md': checklistText },
});

defineSkill 的实现(skill-definition.ts)会校验定义并返回冻结(Object.freeze)的对象——定义时不做任何打包。当技能第一次被需要时,运行时才把它打包成与 SKILL.md 导入完全相同的形态,并自行写出规范合法的 frontmatter(serializeSkillMarkdown 会生成带 name/description 的 YAML 头部并按字母序排序 metadata 键)。packageSkillDefinition 用 WeakMap 按定义对象缓存打包结果,反复激活不会重复序列化。

defineSkill 还能把名字不是 SKILL.md 的 Markdown 转成技能。裸 .md 导入只会作为普通字符串加载、不做打包,因此把它传给 defineSkill 即可成为技能:

import { defineSkill } from '@flue/runtime';
import runbook from './incident-runbook.md'; // plain markdown text

export const incidents = defineSkill({
  name: 'incidents',
  description:
    'Run the incident response procedure. Use when an outage or security event is reported.',
  instructions: runbook,
});

useSkill(...) 也接受直接在调用处书写的定义对象,校验逻辑完全相同。每个字段及其约束见 SkillDefinition 的类型定义(types.ts):instructions 必填;files 的值可以是字符串或 Uint8Array(支持二进制支撑文件);files 的键必须是安全相对路径,且不允许是 SKILL.md、以 / 开头/结尾、含 \ 或空字节、含 ./.. 段。

激活机制如何工作

挂载的技能会出现在系统提示词的 Available Skills 区块中——每个技能一行,只有 name 和 description。同时运行时提供 activate_skill 工具。当模型判断某任务匹配某个技能描述时,它调用该工具并传入技能名,完整指令以工具结果的形式返回。

这一区块的组装可见 context.ts 的 composeSystemPrompt:

## Available Skills

The following skills provide specialized instructions for specific tasks. When a task matches a skill description, call the `activate_skill` tool with that skill name before proceeding so its full instructions are loaded. Skill instructions and supporting resources stay lazy until activation or explicit file reads.

- **refunds** — Process a customer refund request end-to-end. ...

activate_skill 的工具规范是完全静态的(agent.ts 中 createActivateSkillTool):name 参数只是一个普通字符串,而不是技能名的字面量联合——否则每次动态技能变更都会重写工具规范、击穿提供商的提示缓存。激活未知技能名不是错误,结果会列出当前可用的技能清单(session.ts 的 activateSkillForTool 对未注册名字返回 factual miss:Skill "..." is not available. Available skills: ...)。

由于指令以工具结果到达,系统提示词在技能激活时从不改变,提供商缓存的提示词前缀得以保留。

用指令引导激活

因为激活是一次工具调用,你的指令可以直接引导它:

useSkill(refunds);
return 'Activate the `refunds` skill before handling any refund request.';

同样的引导也适用于应用代码:一个 harness tool 的 harness.prompt(...) 以 Agent 渲染后的完整配置运行(同一份系统提示词、技能目录和工具),所以只要在提示文本中指名技能即可让模型在那里也完成激活——包括工作区发现的技能。仓库的 with-imported-skill.ts 正是这个模式:useSkill(review) 后,一个 harness 工具再通过 harness.prompt('Use the "review" skill and report its result.') 在子提示中复用同一技能目录。

需要 Agent 始终携带的内容不要用技能:把 Markdown 作为字符串导入并折叠进 instructions,或传给 useInstruction(...)。

支撑文件在运行时的行为

已打包技能的支撑文件随应用 bundle 一起分发,而不是放进 Agent 的工作区。沙箱里不会拷贝任何东西:运行时把每个文件以只读虚拟路径提供,激活简报会列出全部资源及其精确读取路径。模型的读文件工具对这些路径透明解析——包括只要某个已挂载技能携带支撑文件就追加的 read_skill_resource 工具——而工作区本身保持不动。

底层实现(agent.ts):打包技能被挂载到 /.flue/packaged-skills/ 虚拟根下,overlayPackagedSkills 拦截 readFile,对该根路径从内存目录中提供内容(未知路径报"not found"),其余路径照常委托给真实环境;createPackagedSkillReadTool 暴露 read_skill_resource 工具,支持 offset/limit 分页读取。激活时,result.ts 的 buildPackagedSkillPrompt 生成 Run the skill named "refunds".、<skill_instructions> 正文以及 <skill_resources> 资源清单(每个资源一行 路径 → read_skill_resource <id>/<path>)。如果技能调用带有参数或 result schema,简报中还会附加参数 JSON 与结果工具说明。

同一份 bundle 在你的笔记本、Node.js 或 Cloudflare 上提供相同的文件——无需按环境配置文件系统,Agent 也永远不可能意外编辑自己的技能内容。

工作区技能(Workspace Skills)

有 sandbox 的 Agent 还有一条获取技能的途径:从工作区发现。会话启动时,运行时扫描沙箱工作目录下的 .agents/skills/,每个合法的 <name>/SKILL.md 都会加入技能目录——无需导入,也无需 useSkill(...) 调用:

<cwd>/.agents/skills/
└─ greet/
   └─ SKILL.md

扫描实现在 context.ts 的 discoverLocalSkills:只解析 frontmatter 来填充系统提示词的 Available Skills 区块,技能正文刻意不保留——自主激活时重新读取 SKILL.md 再注入指令,这样既能保持相对引用可解析,也能拾取会话中途的编辑而无需重新初始化 Agent。

工作区技能留在工作区:

  • 指令在激活时从磁盘读取,会话中途的编辑会被拾取;
  • 支撑文件就是普通的工作区文件,模型直接读取;
  • 格式损坏的工作区 SKILL.md 会跳过并给出警告而不是让会话失败(对比:导入技能在构建期严格校验,那时硬错误才可操作);
  • 工作区技能名与已声明技能同名冲突会报错(mergeSkillCatalog 直接抛出)。

在 examples/hello-world/.agents/skills/greet/SKILL.md 可以看到一个真实的工作区技能。选择建议:当专长随工作区交付——比如仓库 checkout、CI 环境或带有自身约定的预置运行时工作区,任何在其中工作的 Agent 都能受益——就用工作区技能;当专长归属于你的应用本身时,用声明式技能。

下一步

  • Agent Hooks —— useSkill 如何与 Agent 的其余能力组合。
  • Agent Hooks API —— useSkill、defineSkill、SkillDefinition 的完整契约。
  • Tools 指南 —— 可执行的应用能力,以及什么时候工具优于技能。
  • Subagents 指南 —— 把整个流程委托给专家 Agent,而不是教给它。
  • Sandboxes 指南 —— 工作区技能被发现的地方。
登录后查看全文
flue