Heym Skills 技能系统教程:用 SKILL.md 打造可复用的 Agent 能力包
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。
快速上手:三种方式创建技能
方式一:拖拽上传(最简单)
在 Agent 节点的属性面板中找到 Skills 区域,直接把 .zip 或 .md 文件拖进去即可:
- 把
SKILL.md和可选的.py脚本放进一个文件夹,压缩为.zip(或直接拖单个.md); - 拖到 Skills 区域,Heym 自动解析 frontmatter 中的
name字段作为技能名; - 展开技能卡片后,还可以继续拖文件进去追加/替换捆绑资源(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 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 不可用时会直接报错而非降级执行,杜绝"静默不安全"。
验证技能是否生效
技能执行完,建议在两处检查:
- 画布 Debug 面板 / 执行历史:查看
skill_xxx工具调用的入参、返回和生成的文件链接; - Traces 标签页:查看传给模型的完整请求(包含拼入系统提示词的 SKILL.md 内容)、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 系统。


