技能自动生产工具

声明式 SKILL.md 自动编译为可执行组合工具，零代码实现技能到工具的转化

Crab Claw 独创的 Skill-to-Tool Codegen 系统，能够将声明式 SKILL.md 技能定义自动编译为可执行的组合工具。无需编写任何代码，只需声明"做什么"，系统自动生成"怎么做"。

核心理念

Skills 是 CRD（声明你要什么），Tools 是 Controller（执行怎么做）

传统工具开发需要编写 Go/Rust 代码、注册路由、更新能力树——周期长、门槛高。Skill-to-Tool Codegen 将这一过程简化为：

在 SKILL.md 中声明 tool_schema（输入/输出/执行步骤）
系统自动编译为 skill_ 前缀的组合工具
自动注册到能力树，智能体即刻可用

端到端流程

shell

SKILL.md (声明)
  │
  ├─ frontmatter.go 解析 tool_schema
  │   ├─ 输入 Schema (JSON Schema)
  │   ├─ 输出 Schema
  │   └─ 执行步骤 (steps[])
  │
  ├─ composed.Codegen 编译
  │   ├─ JSON Schema 校验
  │   ├─ 工具存在性验证 (能力树查找)
  │   ├─ 审批级别推导
  │   └─ 名称规范化 (skill_ 前缀)
  │
  ├─ ComposedToolDef 持久化
  │   └─ ~/.crabclaw/state/composed_tools.json
  │
  ├─ 能力树注册
  │   └─ Owner="composed_subsystem", Kind=Tool
  │
  └─ 运行时可用
      └─ skill_xxx 工具可被智能体调用
SKILL.md (声明)
  │
  ├─ frontmatter.go 解析 tool_schema
  │   ├─ 输入 Schema (JSON Schema)
  │   ├─ 输出 Schema
  │   └─ 执行步骤 (steps[])
  │
  ├─ composed.Codegen 编译
  │   ├─ JSON Schema 校验
  │   ├─ 工具存在性验证 (能力树查找)
  │   ├─ 审批级别推导
  │   └─ 名称规范化 (skill_ 前缀)
  │
  ├─ ComposedToolDef 持久化
  │   └─ ~/.crabclaw/state/composed_tools.json
  │
  ├─ 能力树注册
  │   └─ Owner="composed_subsystem", Kind=Tool
  │
  └─ 运行时可用
      └─ skill_xxx 工具可被智能体调用

SKILL.md 工具声明

在 SKILL.md 的 frontmatter 中添加 tool_schema 段：

yaml

---
name: "竞品监控"
description: "自动监控竞品动态并生成报告"
tool_schema:
  input:
    type: object
    properties:
      competitors:
        type: array
        items:
          type: string
        description: "竞品名称列表"
      depth:
        type: string
        enum: [shallow, deep]
        default: shallow
    required: [competitors]
  output:
    type: object
    properties:
      report:
        type: string
      findings_count:
        type: integer
  steps:
    - tool: web_search
      input:
        query: "{{input.competitors}} 最新动态"
    - tool: web_fetch
      input:
        url: "{{steps.0.output.url}}"
    - tool: write_file
      input:
        path: "/tmp/competitor-report.md"
        content: "{{steps.1.output.content}}"
---
---
name: "竞品监控"
description: "自动监控竞品动态并生成报告"
tool_schema:
  input:
    type: object
    properties:
      competitors:
        type: array
        items:
          type: string
        description: "竞品名称列表"
      depth:
        type: string
        enum: [shallow, deep]
        default: shallow
    required: [competitors]
  output:
    type: object
    properties:
      report:
        type: string
      findings_count:
        type: integer
  steps:
    - tool: web_search
      input:
        query: "{{input.competitors}} 最新动态"
    - tool: web_fetch
      input:
        url: "{{steps.0.output.url}}"
    - tool: write_file
      input:
        path: "/tmp/competitor-report.md"
        content: "{{steps.1.output.content}}"
---

编译后自动生成 skill_竞品监控 工具，智能体可直接调用。

变量模板引擎

步骤间通过变量模板传递数据，支持三种模式：

模式	语法	示例
纯变量引用	`{{input.field}}`	`{{input.competitors}}`
字符串插值	`"文本 {{var}}"`	`"分析 {{input.name}} 的数据"`
点路径查找	`{{steps.N.output.field}}`	`{{steps.0.output.url}}`
循环变量	`{{item}}`	遍历数组时引用当前元素

执行引擎

组合工具的执行流程：

循环检测：执行前检查步骤引用是否成环
输入映射：解析变量模板，替换为实际值
工具调用：按步骤顺序执行底层工具
重试策略：失败时最多重试 2 次
错误处理：支持 abort（终止）和 skip（跳过）两种策略
输出采集：每步输出存入变量表，供后续步骤使用

错误处理策略

yaml

steps:
  - tool: web_fetch
    input:
      url: "{{input.url}}"
    on_error: skip      # 失败时跳过，继续下一步
  - tool: write_file
    input:
      content: "{{steps.0.output.content}}"
    on_error: abort     # 失败时终止整个工具执行
steps:
  - tool: web_fetch
    input:
      url: "{{input.url}}"
    on_error: skip      # 失败时跳过，继续下一步
  - tool: write_file
    input:
      content: "{{steps.0.output.content}}"
    on_error: abort     # 失败时终止整个工具执行

能力树集成

编译后的组合工具自动注册到能力树：

节点类型：Tool（与原生工具同级）
所有者标识：composed_subsystem
审批推导：根据步骤中使用的最高权限工具，自动推导组合工具的审批级别
前缀分发：tool_executor.go 检测 skill_ 前缀 → 委托 ComposedSubsystem.ExecuteTool

审批级别推导示例

shell

步骤 1: web_search  → 无审批
步骤 2: write_file  → plan_confirm
步骤 3: bash        → exec_escalation

组合工具审批级别 = max(无, plan_confirm, exec_escalation) = exec_escalation
步骤 1: web_search  → 无审批
步骤 2: write_file  → plan_confirm
步骤 3: bash        → exec_escalation

组合工具审批级别 = max(无, plan_confirm, exec_escalation) = exec_escalation

RPC 接口

路由	说明
`skills.codegen`	触发技能编译（指定技能 ID 或全量）
`skills.codegen.status`	查看编译状态与已注册工具列表
`skills.codegen.remove`	移除已编译的组合工具

与其他系统的协作

与子智能体工厂的协作

蓝图可以在 capabilities.allow 中引用 skill_ 前缀的组合工具，子智能体即获得该组合能力：

yaml

capabilities:
  allow: [skill_竞品监控, web_search, memory_search]
capabilities:
  allow: [skill_竞品监控, web_search, memory_search]

与能力树的协作

编译时通过 ToolTreeLookup 接口验证步骤中引用的工具是否存在
注册时使用 AddNode + treeMutationMu 锁保证并发安全
支持增量编译：仅编译新增或修改的技能

与技能系统的协作

共享 SKILL.md frontmatter 解析（frontmatter.go）
无 tool_schema 段的技能不会触发编译
MCP 工具步骤暂不支持编译（P6 路线图）

设计亮点

设计	说明
零代码创建工具	SKILL.md 声明即工具，无需 Go/Rust 开发
自动审批推导	根据子步骤最高权限自动设定安全等级
循环依赖检测	编译时静态分析，防止步骤间循环引用
原子化持久化	composed_tools.json 原子写入，防数据损坏
增量编译	仅处理变更的技能，编译效率高
接口解耦	`ToolTreeLookup` 接口避免循环依赖

代码位置

组件	位置
核心编译引擎	`backend/internal/agents/composed/codegen.go`
执行引擎	`backend/internal/agents/composed/executor.go`
类型定义	`backend/internal/agents/composed/types.go`
持久化存储	`backend/internal/agents/composed/store.go`
能力树注册	`backend/internal/agents/composed/tree_register.go`
前缀分发	`backend/internal/agents/runner/tool_executor.go`
frontmatter 解析	`backend/internal/agents/skills/frontmatter.go`

相关文档：技能系统 · 能力树与权限 · 子智能体工厂