自定义技能

编写 SKILL.md 声明式技能定义

你可以通过编写 SKILL.md 文件为智能体添加新的领域知识和自动化能力。

SKILL.md 格式

每个技能文件包含 YAML frontmatter 和 Markdown 指令正文：

markdown

---
name: my-skill
description: "技能简短描述（不超过 120 字符）"
tools:
  - bash
  - read_file
metadata:
  crabclaw:
    tree_id: runtime/bash
    tree_group: runtime
    min_tier: task_light
    approval_type: exec_escalation
---

# 技能指令

这里写给智能体的使用说明...
---
name: my-skill
description: "技能简短描述（不超过 120 字符）"
tools:
  - bash
  - read_file
metadata:
  crabclaw:
    tree_id: runtime/bash
    tree_group: runtime
    min_tier: task_light
    approval_type: exec_escalation
---

# 技能指令

这里写给智能体的使用说明...

Frontmatter 字段

字段	必填	说明
`name`	是	技能标识符
`description`	是	简短描述，用于 LLM 发现（不超过 120 字符）
`tools`	否	绑定的能力树工具名称数组
`metadata.crabclaw.tree_id`	否	能力树节点 ID
`metadata.crabclaw.tree_group`	否	工具组名称
`metadata.crabclaw.min_tier`	否	最低意图层级
`metadata.crabclaw.approval_type`	否	审批类型

技能放置位置

位置	优先级	说明
`docs/skills/`	高	工作区技能（随项目）
`~/.crabclaw/skills/`	中	用户全局技能
内置	低	系统默认技能

组合技能 (tool_schema)

通过 tool_schema 定义多步骤自动化流水线：

yaml

metadata:
  crabclaw:
    tool_schema:
      input:
        type: object
        properties:
          filepath: { type: string, description: "文件路径" }
        required: ["filepath"]
      output:
        type: object
        properties:
          summary: { type: string }
      steps:
        - action: "读取文件"
          tool: read_file
          input_map:
            path: "{{input.filepath}}"
          output_as: file_content
        - action: "分析内容"
          tool: bash
          input_map:
            command: "wc -l <<< '{{file_content}}'"
          output_as: line_count
          on_error: skip
metadata:
  crabclaw:
    tool_schema:
      input:
        type: object
        properties:
          filepath: { type: string, description: "文件路径" }
        required: ["filepath"]
      output:
        type: object
        properties:
          summary: { type: string }
      steps:
        - action: "读取文件"
          tool: read_file
          input_map:
            path: "{{input.filepath}}"
          output_as: file_content
        - action: "分析内容"
          tool: bash
          input_map:
            command: "wc -l <<< '{{file_content}}'"
          output_as: line_count
          on_error: skip

Step 字段

字段	说明
`action`	步骤描述
`tool`	调用的工具名称
`input_map`	输入映射，支持 `{{var.path}}` 模板
`output_as`	输出变量名（供后续步骤引用）
`on_error`	错误策略: `abort`/`skip`/`retry`
`approval`	审批类型覆盖
`loop_over`	循环变量路径（对数组逐项执行）

编译与测试

bash

# 编译所有含 tool_schema 的技能
crabclaw skills codegen

# 预览编译结果
crabclaw skills codegen --dry-run

# 查看已编译的组合工具
crabclaw skills codegen --status
# 编译所有含 tool_schema 的技能
crabclaw skills codegen

# 预览编译结果
crabclaw skills codegen --dry-run

# 查看已编译的组合工具
crabclaw skills codegen --status

编译后的组合工具以 skill_ 前缀注册到能力树，智能体可直接调用。

调试技巧

使用 --dry-run 预览编译结果，检查步骤引用是否正确
检查 tool 字段引用的工具是否存在于能力树
使用 on_error: skip 让非关键步骤失败时不中断流水线
查看 ~/.crabclaw/state/composed_tools.json 确认编译产物