自定义 Skill 开发 (Archive)

Archived original-language source from the legacy CrabClaw docs. This page is intentionally not machine-translated.

本教程将手把手带你创建一个组合技能：每日报告生成器。它会读取指定目录的文件，生成摘要，并通过消息频道发送。

目标

创建一个 daily-report 技能，包含以下步骤：

列出目标目录的文件
读取关键文件内容
生成摘要并发送

第一步：创建技能文件

在工作区创建技能目录：

bash

mkdir -p docs/skills/operations/daily-report
mkdir -p docs/skills/operations/daily-report

创建 docs/skills/operations/daily-report/SKILL.md：

markdown

---
name: daily-report
description: "读取工作目录文件并生成每日摘要报告"
metadata:
  crabclaw:
    tree_group: operations
    min_tier: task_light
    tool_schema:
      input:
        type: object
        properties:
          directory:
            type: string
            description: "要扫描的目录路径"
          channel:
            type: string
            description: "发送报告的频道"
        required: ["directory"]
      steps:
        - action: "列出目录文件"
          tool: list_dir
          input_map:
            path: "{{input.directory}}"
          output_as: file_list
        - action: "读取 README"
          tool: read_file
          input_map:
            path: "{{input.directory}}/README.md"
          output_as: readme_content
          on_error: skip
        - action: "统计文件数量"
          tool: bash
          input_map:
            command: "ls -la {{input.directory}} | wc -l"
          output_as: file_count
        - action: "发送报告"
          tool: message
          input_map:
            text: "每日报告\n目录: {{input.directory}}\n文件数: {{file_count}}\n文件列表:\n{{file_list}}"
            channel: "{{input.channel}}"
          on_error: skip
---

生成指定目录的每日摘要报告，包含文件列表和统计信息。
如果目录包含 README.md，会一并读取其内容。
报告会发送到指定的消息频道。
---
name: daily-report
description: "读取工作目录文件并生成每日摘要报告"
metadata:
  crabclaw:
    tree_group: operations
    min_tier: task_light
    tool_schema:
      input:
        type: object
        properties:
          directory:
            type: string
            description: "要扫描的目录路径"
          channel:
            type: string
            description: "发送报告的频道"
        required: ["directory"]
      steps:
        - action: "列出目录文件"
          tool: list_dir
          input_map:
            path: "{{input.directory}}"
          output_as: file_list
        - action: "读取 README"
          tool: read_file
          input_map:
            path: "{{input.directory}}/README.md"
          output_as: readme_content
          on_error: skip
        - action: "统计文件数量"
          tool: bash
          input_map:
            command: "ls -la {{input.directory}} | wc -l"
          output_as: file_count
        - action: "发送报告"
          tool: message
          input_map:
            text: "每日报告\n目录: {{input.directory}}\n文件数: {{file_count}}\n文件列表:\n{{file_list}}"
            channel: "{{input.channel}}"
          on_error: skip
---

生成指定目录的每日摘要报告，包含文件列表和统计信息。
如果目录包含 README.md，会一并读取其内容。
报告会发送到指定的消息频道。

第二步：编译技能

bash

# 预览编译结果（不写入）
crabclaw skills codegen --dry-run
# 预览编译结果（不写入）
crabclaw skills codegen --dry-run

确认输出无误后正式编译：

bash

crabclaw skills codegen
crabclaw skills codegen

预期输出：

shell

Compiled 1 skill(s):
  skill_daily_report — 4 steps, max_approval: exec_escalation
Compiled 1 skill(s):
  skill_daily_report — 4 steps, max_approval: exec_escalation

第三步：查看编译结果

bash

crabclaw skills codegen --status
crabclaw skills codegen --status

输出应包含 skill_daily_report，说明编译成功。

编译产物存储在 ~/.crabclaw/state/composed_tools.json。

第四步：测试

在聊天中测试：

shell

> 对 ~/projects/my-app 目录生成每日报告
> 对 ~/projects/my-app 目录生成每日报告

智能体会自动匹配并调用 skill_daily_report，按步骤执行。

理解执行流程

shell

LLM 调用 skill_daily_report
  → Step 1: list_dir(~/projects/my-app)
  → Step 2: read_file(~/projects/my-app/README.md)  [失败则跳过]
  → Step 3: bash(ls -la ... | wc -l)
  → Step 4: message(报告内容)  [失败则跳过]
  → 返回组合结果
LLM 调用 skill_daily_report
  → Step 1: list_dir(~/projects/my-app)
  → Step 2: read_file(~/projects/my-app/README.md)  [失败则跳过]
  → Step 3: bash(ls -la ... | wc -l)
  → Step 4: message(报告内容)  [失败则跳过]
  → 返回组合结果

调试技巧

编译报错：tool not found

确认 tool 字段的值是能力树中存在的工具名。使用 crabclaw skills codegen --status 查看可用工具。

步骤执行失败

设置 on_error: skip 让非关键步骤失败不中断
设置 on_error: retry 允许最多重试 2 次
检查 input_map 中的模板变量是否拼写正确

变量引用为空

确认前置步骤的 output_as 名称与后续步骤的 {{var}} 引用一致。

进阶：循环处理

使用 loop_over 对数组逐项执行：

yaml

steps:
  - action: "发布到多个平台"
    tool: message
    loop_over: "{{input.platforms}}"
    input_map:
      channel: "{{item}}"
      text: "{{input.content}}"
steps:
  - action: "发布到多个平台"
    tool: message
    loop_over: "{{input.platforms}}"
    input_map:
      channel: "{{item}}"
      text: "{{input.content}}"

{{item}} 是循环变量，依次取数组中的每个元素。