Heym Skills 技能系统教程:用 SKILL.md 打造可复用的 Agent 能力包

原创2026-10-14 19:12:061,815 阅读

Heym Skills 技能系统教程:用 SKILL.md 打造可复用的 Agent 能力包

Heym 是一款可自托管的 AI Agent 工作流平台,而它的 Skills 技能系统 让你用一个 SKILL.md 文件(外加可选的 Python 脚本)即可给 Agent 节点打包一项"可携带的能力"——拖进去就能用,跨工作流复用,还能导出 .zip 分享给团队。本教程带你从零理解 Heym Skills 的完整用法。

什么是 Heym Skills?

可以把 Skill 想象成"一份岗位说明书 + 一个工具箱":

  • SKILL.md(说明书):描述这个技能是做什么的、何时该调用、接收哪些参数。运行时会自动拼接到 Agent 的系统提示词(system prompt)前面,模型据此决定何时调用它。
  • Python 文件(工具箱):每个包含 .py 文件的技能会变成一个名为 skill_{技能名} 的可调用工具(tool),Agent 在对话循环中像调用普通工具一样调用它。
  • 捆绑资源(assets):模板、字体、图片等文件也可以打进同一个包,供 Python 代码按相对路径读取。

官方对 Skills 的定位是"portable capability bundles"(可携带能力包),完整概念介绍见 why-heym.md,节点级参考文档见 agent-node.md。

Heym Agent 技能包创建演示:自然语言生成 SKILL.md 并挂载到 Agent 节点

快速上手:三种方式创建技能

方式一:拖拽上传(最简单)

在 Agent 节点的属性面板中找到 Skills 区域,直接把 .zip 或 .md 文件拖进去即可:

  1. 把 SKILL.md 和可选的 .py 脚本放进一个文件夹,压缩为 .zip(或直接拖单个 .md);
  2. 拖到 Skills 区域,Heym 自动解析 frontmatter 中的 name 字段作为技能名;
  3. 展开技能卡片后,还可以继续拖文件进去追加/替换捆绑资源(PDF、图片等二进制资产也支持)。

技能包解析逻辑由 skill_archive.py 实现,它会自动把目录中包含 SKILL.md 的文件夹识别为一个技能,并过滤掉 __MACOSX、.DS_Store 等系统噪音文件。

方式二:AI Build(对话式创建,推荐)

不想手写代码?Heym 内置了 AI Build 技能构建器:

  • 点击 Skills 区域的 ✨ AI Build 按钮,用自然语言描述需求,例如"帮我生成一个把 Markdown 转成 PDF 报表的技能";
  • 左侧是与 AI 的流式对话,右侧实时预览生成的 SKILL.md 和 main.py;
  • 可以把模板文件直接拖进输入框,AI 会读取其内容并生成引用它的代码;
  • 满意后点 Save & Add 保存回 Agent 节点,或点 Download ZIP 仅导出预览;
  • 点击已有技能卡片上的 ✨ 图标,还能让 AI 修改现有技能(多轮微调)。

后端接口 /api/ai/skill-builder 通过 SSE 流式返回,核心实现见 skill_builder.py。

方式三:AI Assistant 对话挂载

在 AI 助手对话中直接上传技能 ZIP,模型会调用 apply_skill 工具把它挂到 Agent 节点上;多个 Agent 可能挂载时会先询问你指定目标,避免误操作。相关逻辑见 skill_apply.py。

SKILL.md 标准格式详解

一个规范的 SKILL.md 由 YAML frontmatter + 正文组成:

---
name: pdf-report
description: 将给定的 Markdown 内容生成为 PDF 报表
parameters:
  - name: markdown
    type: string
    description: 需要渲染为 PDF 的 Markdown 内容
    required: true
outputs:
  - name: status
    type: string
    description: 生成结果状态
timeout: 30
---

## Description
本技能接收 Markdown 文本并输出 PDF 文件……

## Parameters
- **markdown** (string, 必填): 需要渲染的正文内容

## Returns
- **status**: 执行状态

关键字段说明:

字段 作用
name 技能名,与现有技能同名即为"更新",新名即为"新增"
description 模型读取它来决定何时调用技能,务必写清楚
parameters 输入参数定义(名称、类型、说明、是否必填)
outputs 返回值定义
timeout Python 执行超时(秒),默认 30

💡 提示:description 和 SKILL.md 正文就是模型的"使用说明书",写得越准确,Agent 越不容易误调用或漏调用。

配套 main.py 的写法

技能 Python 入口需要实现顶层的 execute(params, files) -> dict 函数:参数经 JSON 从 stdin 传入,结果以 JSON 从 stdout 返回。Heym 运行时预装了常用第三方库:

  • reportlab(生成 PDF)、python-docx(生成 DOCX)
  • Pillow(图片处理)、pypdf(读取 PDF)
  • pypandoc(Markdown/HTML/DOCX 互转)、requests(HTTP 请求)

让技能"产文件"

如果技能需要生成文件(PDF、CSV、图片等),只要把文件写入环境变量 _OUTPUT_DIR 指向的目录即可,不要把文件字节放进返回值。运行结束后 Heym 会自动收集这些文件,生成下载链接,并挂在输出的 _generated_files 数组里。完整机制见 file-generation.md。

生成的文件会自动进入平台的 Drive 文件区,可分享、加密、设有效期;下游节点还可以用 $agentLabel._generated_files[0].id 拿到文件 ID,交给 Drive 节点做权限管理。

技能卡片:日常操作清单

每个技能卡片下方有 4 个常用操作:

按钮 说明
Edit with AI 打开 Skill Builder,用对话修改技能
Download 导出为 .zip 归档,用于备份或复用到其他工作流
Remove 从当前 Agent 节点删除该技能
History 查看技能历史版本(从工作流编辑历史快照派生),支持预览、载入编辑、AI 微调或一键回滚单个技能

Heym 可视化画布:Agent 节点与技能、子 Agent、MCP 节点协同编排

进阶:读取 Heym Drive 文件

在技能卡片上打开 Enable Drive files 开关后,技能运行时会自动获得一个 heym_drive.py 助手模块,Python 代码即可调用 list_drive_files、read_drive_text、read_drive_file、read_drive_base64 等函数,按文件 ID 或精确文件名读取 Drive 中的文档——非常适合"先上传合同、再让 Agent 审阅"这类流程。

技能安全沙箱

技能 Python 属于不受信代码(可能来自共享工作流或模板),因此默认运行在强化隔离的"兄弟容器"中,规则定义在 skill_python_executor.py:

  • 非 root 用户、丢弃全部 Linux capabilities、只读根文件系统、CPU/内存/PID 严格限额;
  • 拿不到 Docker socket,也无法接触后端密钥与环境变量(仅放行 PATH、HOME、代理等少量白名单变量);
  • 保留网络出口和可写工作区(技能合法地需要生成文件、读取 Drive);
  • 通过 HEYM_PYTHON_TOOL_SANDBOX 环境变量控制沙箱模式,auto(默认)在 Docker 不可用时会直接报错而非降级执行,杜绝"静默不安全"。

验证技能是否生效

技能执行完,建议在两处检查:

  1. 画布 Debug 面板 / 执行历史:查看 skill_xxx 工具调用的入参、返回和生成的文件链接;
  2. Traces 标签页:查看传给模型的完整请求(包含拼入系统提示词的 SKILL.md 内容)、token 用量与美元成本,排查"模型为什么没调用技能"这类问题。

Heym LLM Traces 面板:查看技能调用相关的模型请求、响应、token 用量与成本

常见问题 FAQ

Q:AI Assistant 会把技能里的 Python 也发给模型吗? 不会。当工作流已含技能时,AI 助手只把每个技能的 SKILL.md 放入构建上下文,.py 与二进制资源会被剔除,避免撑爆模型上下文窗口。

Q:同一个技能能用在多个工作流吗? 能。点 Download 导出 .zip,再拖到任何 Agent 节点的 Skills 区域即可——这正是 Skills 设计为"能力包"的意义。

Q:技能执行超时了怎么办? 调整技能卡片上的超时设置(默认 30 秒),或在 SKILL.md frontmatter 的 timeout 字段中声明。

Q:技能历史能回滚吗? 可以。History 对话框支持仅回滚"这一个技能"到某个历史版本,其余节点保持不动。

小结

Heym Skills 把"给 Agent 加能力"变成了三件事:写一份 SKILL.md、拖一个 ZIP、点一下 AI Build。技能指令自动注入系统提示词,Python 自动变成可调用的工具,产物自动进入 Drive,全程受沙箱保护并可追溯。结合 Agent Architecture 参考,你可以进一步把技能与子 Agent、MCP、HITL 审批组合,搭建出真正可上生产的 Agent 系统。

登录后查看全文
heym