技能系统详解

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：chengflow/skills/、crates/cheng-core/src/domain/skill.rs、crates/cheng-core/src/domain/active_skill.rs、crates/cheng-nodes/src/nodes/builtin/tools/skills_hub、crates/cheng-api/src/rest/handlers/skill/mod.rs

技能把一项能力打包起来，让智能体能够找到它并正确使用它。工具是一个可调用的函数，而技能是一个具名单元，带有使用说明、输入输出 schema，通常还有参考文档——这相当于「给模型一个按钮」和「给模型一本手册」的区别。

技能是什么

Skill
  ├── name              ← slug：至少 2 字符，只允许字母数字、- 和 _
  ├── display_name、description
  ├── instructions      ← 模型据以使用它的说明
  ├── workflow_id?      ← 由工作流实现时，对应的那个工作流
  ├── input_schema / output_schema
  ├── category、tags
  ├── enabled、is_user_invocable
  ├── version           ← 默认 "1.0.0"
  └── workspace_id?     ← 为 None 表示全局

技能属于工作区，workspace_id 为 None 时是全局的。is_user_invocable 把人可以触发的技能与仅供智能体使用的技能区分开。

在磁盘上，一个技能是 skills/<name>/ 目录，其中的 SKILL.md 带有 YAML 前置数据：

---
name: workflow-helper
description: Use this skill when the user has questions about building, debugging,
  or understanding ChengOS workflows — including node selection, port wiring,
  field configuration, error troubleshooting, and pattern recommendations.
---

description 是触发条件，不是功能简介。智能体正是拿它来匹配、判断这个技能是否适用，所以要写成「当……时使用」，而不是一段介绍。较大的技能还会加一个 references/ 目录，由说明正文链接进去。

随附的技能

其中两个特别值得当作范式来研究。

workflow-helper 向运行中的 API 查询实时 schema，而不是内嵌一份快照，因为节点 schema 每次构建都可能变。内嵌的副本一周之内就会过时。

workflow-json-builder 被明确限制在只读接口——模板、节点类型、节点 schema、模型——并禁止调用创建、更新、执行或保存。技能不仅能告诉智能体做什么，也能约束它不能做什么。

SKILLS_INDEX.md 是注册表。在新建技能之前先查一下它，才不会攒出五个高度雷同的能力。

Skills Hub

tools/skills_hub 是统一入口。把它连到智能体上，智能体就能：

节点自身的描述告诉模型一条关键规则：技能目录是动态的。 要用 list 或 search 去发现技能，而不是假定存在哪些技能；调用某技能声明的工具之前先 describe，然后使用返回的工具标识、允许的操作和参数 schema。不要臆测技能或工具的契约。

credential_status 和 approval_status 的存在，是为了让智能体在执行之前就知道自己缺少 API 密钥或将撞上审批门，而不是跑到一半才发现。

更早的 tools/skill 节点（Execute Skill）按名称查找并执行技能。新做的东西请优先用 Hub。

活动技能绑定

当 Skills Hub 通过 describe 成功解析出一个技能时，它会记录一条活动技能绑定。若模型稍后在 Tool Hub 的 execute 命令中省略了 skill_name，这条绑定就提供查找键。

有三条性质保证了它的安全，值得逐条讲清楚，因为「记住我们刚才在用哪个技能」这种便利，往往正是漏洞的来源：

1. 绑定只由可信的运行时代码建立——即 Skills Hub 的解析路径。它绝不从模型文本、对话记忆或普通工作流输入中推导。
2. 绑定只是一个查找键。 Tool Hub 在每次执行前都会依据当前工作区、可见性和规范化 spec 重新解析该技能。一条过期或已撤销的绑定，永远无法独自授权一条命令。
3. 该捷径要求「恰好一个」。 唯一性按「规范名 + 工作区」判定：同一技能被反复解析仍收敛为一条绑定、依然无歧义；而两个不同技能则会让省略捷径变得有歧义，从而不可用。

另外注意，绑定保存的是解析出的规范名，不是模型给出的查找键。

导入外部技能

skill-importer 覆盖了从 URL、Git 仓库或粘贴文本引入技能的整条流水线：

抓取 → LLM 解析与生成 → tools/validate_skill_spec → 审批
     → tools/write_skill_package 写入 skills/<name>/
     → SkillFileWatcher 同步入库

安全性体现在最后一步：导入的技能落库时是 needs_review 且 enabled = false。它不会因为被写到磁盘上就对智能体可用。必须由人启用，在此之前它不会被加入工具目录。

skills/<name>/ 处于监视之下，因此在磁盘上编辑 SKILL.md 无需重启即可同步入库。lock / unlock 接口用于控制监视器是否可以覆盖某个技能。

REST 接口

GET|POST  /skills                       列出、创建
POST      /skills/export-workflow       把工作流转成技能
GET       /skills/uncompleted           草稿
GET       /skills/by-name/:name
POST      /skills/validate              校验技能 YAML
POST      /skills/preview-tools         预览该技能会暴露哪些工具
POST      /skills/:id/execute
POST      /skills/:id/enable | /disable
GET       /skills/:id/credential-status
GET       /skills/:id/runtime-policy
POST      /skills/:id/review
POST      /skills/:id/lock | /unlock
POST      /skills/:id/normalize
          ……以及技能分类与 CLI 工具相关接口

export-workflow 是通往你第一个技能的最短路径：搭一个工作流，导出它，你就得到了一个带 schema、可被智能体发现的具名能力。

怎样写好一个技能

• 把 description 写成触发条件。「当用户询问 X 时使用本技能」优于「本技能做 X」。
• 底层会变的东西，就去查实时数据，别内嵌快照。
• 写明禁止事项。 workflow-json-builder 里最有用的一行，正是它不许调用的 API 清单。
• 先查 SKILLS_INDEX.md，扩展已有技能，而不是再加一个第五个近似品。
• 说明写短，细节放进 references/ 并从说明里链接过去——这样智能体按需加载，而不是每一轮都把整本手册读进来。

下一步

• 工具发现与 Tool Hub——技能与工具如何相遇。
• ReAct 智能体指南——使用它们的那个智能体。
• 接入 MCP Server——用外部能力而非打包能力。