Post

Skills

Posted
By soong
19 min read
Skills

带 CLI、Reference 和输出样例的 Skill 写作 SOP

目标

这份 SOP 用来规范一类常见但容易写散的 skill：它需要指导 agent 调用某个 CLI，同时有较多参考资料、命令参数、工作流、输出样例和错误处理。

这类 skill 的目标不是把 CLI 手册复制给 agent，而是让 agent 在真实任务里稳定做到：

  • 选对工具和命令域
  • 不猜参数、不猜 ID、不误路由
  • 写操作先 dry-run，再确认
  • 能读懂 CLI 输出并判断任务是否完成
  • 遇到错误能按约定恢复或把关键信息交给用户

一句话原则：

SKILL.md 是 agent 操作规程；references/ 是完整资料库；输出样例是判定样本；evals/ 是防回归测试。

适用场景

适合使用本 SOP 的 skill 通常有以下特征：

  • 有明确 CLI，例如 fooctl、bytedcli <domain>、kubectl 包装工具、内部平台 CLI。
  • 命令面较大，包含多个子命令、参数、站点、环境或鉴权模式。
  • 有查询和写操作混合场景。
  • CLI 输出包含 JSON、状态码、错误码、request_id、异步任务状态等，需要 agent 判断。
  • 有相邻平台容易误触发，例如发布平台 A 和发布平台 B 名称相近。
  • 用户常给 URL、ID、工单号、仓库上下文或自然语言描述，而不是完整命令。

不适合使用本 SOP 的场景：

  • 只有一两个固定命令，普通 README 足够。
  • 纯写作风格、纯思维方法、纯代码模式类 skill。
  • 没有稳定 CLI 或 API，主要靠网页人工操作。

推荐目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

skill-name/
  SKILL.md
  references/
    invocation.md
    command-reference.md
    workflows.md
    output-shapes.md
    troubleshooting.md
    examples/
      success.json
      dry-run.json
      running.json
      auth-error.json
      validation-error.json
  scripts/
    validate_payload.py
    parse_output.py
  evals/
    README.md
    evals.json

各目录职责：

  • SKILL.md：只放 agent 每次执行都应该读的操作规程。
  • references/invocation.md：安装、鉴权、站点、全局参数、JSON/debug 输出。
  • references/command-reference.md：完整命令树、参数、字段说明。
  • references/workflows.md：复杂多步骤流程。
  • references/output-shapes.md：成功、失败、dry-run、异步状态的输出结构和判定逻辑。
  • references/troubleshooting.md：常见错误和恢复路径。
  • references/examples/：真实或脱敏后的输出样例。
  • scripts/：可重复、容易出错的解析、校验、payload 生成逻辑。
  • evals/：路由、缺参、输出判断、写操作确认等评测用例。

SKILL.md 标准模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

---
name: your-cli-skill
description: "Use when users mention <domain>, <platform>, <object>, <URL pattern>, <ID type>, <error code>, or need <query/create/debug workflow> through <CLI name>."
---

# Your CLI Skill

## When to use
- 用户提到哪些平台、对象、URL、ID、错误码时使用
- 典型任务：查询、创建、更新、发布、排障、导出

## Do not use
- 相邻但不属于本 CLI 的平台或流程
- 不满足确认条件的写操作
- 只能网页人工处理、CLI 不覆盖的能力

## Preconditions
- 安装方式
- 鉴权要求
- site / region / env 要求
- 权限或网络要求

## Invocation
- 默认调用方式
- 全局参数位置
- JSON 输出方式
- debug / trace 方式
- 完整说明见 `references/invocation.md`

## Critical agent protocol
- 不确定命令名或参数时先看 `--help`
- 写操作默认 dry-run
- 缺参数时先追问或查询候选
- 多候选时让用户选择
- 不伪造 ID、版本、分支、region、scope
- 失败时保留 request_id、error.code、error.hint

## Quick start
```bash
cli --json domain resource get --id 123
cli domain resource list --limit 20
```

## Command tree
```text
cli
`- domain
   |- resource
   |  |- get
   |  |- list
   |  `- create
   `- task
      |- get
      `- wait
```

## Main workflows
1. 查询流程：...
2. 创建流程：...
3. 异步任务流程：...
4. 排障流程：...

## Output handling
- 成功输出 envelope 见 `references/output-shapes.md`
- 必须读取哪些字段判断成功
- 哪些状态是中间态，不能当完成
- 错误输出如何恢复

## References
- `references/invocation.md`
- `references/command-reference.md`
- `references/workflows.md`
- `references/output-shapes.md`
- `references/troubleshooting.md`

写作流程

1. 明确 skill 类型

先判断 skill 是哪一类：

  • Router skill：命令面很大，主要做路由和分域跳转。
  • Domain CLI skill：一个具体平台或命令域的操作指南。
  • Workflow skill：强调多步骤流程、状态判断、确认节点。
  • Reference skill：主要帮助 agent 查资料、查字段、查命令。
  • Script-backed skill：需要脚本做校验、解析、生成或报告。

大型 CLI 不要写成一个超长 skill。推荐使用 root router + domain skill + references。

2. 写 description

description 是触发入口，应该写“什么时候使用”，不要写完整流程。

好的 description 应包含：

  • 平台名、CLI 名、领域名
  • 用户会说的自然语言关键词
  • URL、ID、错误码、对象名
  • 关键任务类型
  • 相邻概念中的强触发词

示例：

1

description: "Use when users mention Lego, Lego plugin, plugin register/compile, release pipeline/scope, release order create/list/get, manual confirm, or Lego OpenAPI through bytedcli lego."

避免：

1

description: "This skill first checks auth, then runs list, then dry-runs create, then asks the user, then polls status."

原因：description 写太多流程时，agent 可能只照 description 做，跳过正文。

3. 写清边界

每个 CLI skill 都必须写 When to use 和 Do not use。

When to use 解决触发问题：

  • 哪些对象属于本 skill
  • 哪些任务属于本 skill
  • 哪些 URL / ID / 错误码属于本 skill

Do not use 解决误路由问题：

  • 相邻但不同的平台
  • CLI 暂不支持的操作
  • 必须人工确认但用户未确认的操作
  • 只能网页处理的能力

4. 固化调用协议

调用协议不要散落在各处。推荐把通用细节放进 references/invocation.md，正文只保留关键摘要。

必须覆盖：

  • 安装方式：全局安装、npx fallback、本地二进制等
  • 鉴权：登录命令、token/env 优先级、站点隔离
  • site / region：全局参数还是子命令参数，位置在哪里
  • JSON 输出：哪个 flag，放在什么位置
  • debug 输出：HTTP trace、日志、request_id
  • 版本保鲜：如何升级 CLI 和 skill

特别注意：如果全局参数位置错误会导致命令失败，必须在正文给出正反例。

5. 写高风险 agent 协议

凡是写操作、删除、发布、权限、审批、发消息、评论、confirm，都要有明确协议。

推荐规则：

  • 查询操作可以直接执行。
  • 写操作默认 dry-run。
  • dry-run 输出必须展示给用户。
  • 用户明确确认后才加 --yes、--execute 或类似参数。
  • 每个写操作独立确认，不能因为用户确认了第一步就自动执行后续所有写操作。
  • 参数缺失时先追问。
  • 多候选时列出候选让用户选。
  • 资源不存在时中断，不替换成相似资源继续。
  • confirm / approve / publish 这类 live 操作不能循环重试。

6. 写工作流，不只写命令

复杂任务要写成工作流，并给出每一步完成标准。

示例：

1
2
3
4
5
6
7
8

创建并发布流程：
1. 查询资源是否存在。
2. 查询候选版本、scope、pipeline。
3. 让用户选择缺失参数。
4. 执行 create dry-run，展示请求体。
5. 用户确认后执行 create --yes。
6. 轮询 task get，直到进入终态。
7. 如果遇到 manual_confirm，停止自动化，提示用户确认。

避免只写：

1
2

cli resource create ...
cli task get ...

命令示例不能替代流程约束。

7. 设计 output-shapes

CLI skill 必须告诉 agent 如何读输出，而不是只告诉它如何运行命令。

references/output-shapes.md 至少包含：

  • 成功 envelope
  • 错误 envelope
  • dry-run 输出
  • 异步任务 running 输出
  • 最终成功输出
  • 最终失败输出
  • 关键字段解释
  • 状态枚举
  • agent 判定规则

推荐格式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# Output Shapes

## Envelope
```json
{
  "status": "success",
  "data": {},
  "error": null,
  "context": {
    "request_id": "..."
  }
}
```

## Success criteria
- `status == "success"` 只代表命令请求成功，不一定代表异步任务完成。
- 异步任务必须继续检查 `data.task.status`。
- `RUNNING` / `PENDING` / `READY` 是中间态。
- `FINISHED` 才是完成态。
- `FAILED` / `CANCELED` 是失败终态。

## Error handling
- 如果 `error.code == "AUTH_REQUIRED"`，先检查目标 site 的登录状态。
- 如果存在 `context.request_id`，最终反馈必须保留。

输出样例不要只贴“成功”。至少覆盖：

  • success.json
  • dry-run.json
  • running.json
  • failed.json
  • auth-error.json
  • validation-error.json

8. 设计 references 的渐进加载

正文应该告诉 agent “什么时候读哪个 reference”。

推荐写法：

  • 需要确认安装、鉴权、site、JSON 输出时，读 references/invocation.md。
  • 需要完整参数、字段枚举、命令树时，读 references/command-reference.md。
  • 任务跨多个命令或有异步状态时，读 references/workflows.md。
  • 需要解析 JSON 或判断状态时，读 references/output-shapes.md。
  • 命令失败时，读 references/troubleshooting.md。

避免只写：

1
2
3
4

## References
- invocation.md
- command-reference.md
- troubleshooting.md

没有触发条件的 reference 容易被 agent 忽略。

9. 可重复逻辑放 scripts

如果 agent 每次都会手写同一段解析、校验或 payload 生成逻辑，应考虑放到 scripts/。

适合脚本化的内容：

  • JSON schema 校验
  • payload 生成
  • govaluate / SQL / workflow 语法检查
  • diff 过滤
  • 输出解析
  • 报告生成
  • 异步任务轮询包装

正文只需要说明：

  • 何时调用脚本
  • 输入是什么
  • 输出是什么
  • 脚本失败后怎么办

10. 写 evals 验证 skill

带 CLI 的 skill 至少应该测这些情况：

  • 正向触发：用户提到领域对象时触发。
  • 负向不触发：相邻平台不应触发。
  • 缺参数：agent 必须追问，不能臆造。
  • 多候选：agent 必须让用户选择。
  • 写操作：必须 dry-run + 用户确认。
  • 状态判断：不能把中间态当完成。
  • 输出解析：能读关键字段。
  • 错误处理：能保留 request_id / hint 并按规则恢复。
  • 参数位置：能识别全局参数和子命令参数的位置。
  • 资源不存在：不能替换成相似资源继续。

evals/evals.json 推荐结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "skill_name": "your-cli-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "帮我创建一个 demo 资源",
      "expected_output": "应触发 skill；缺少 owner 和 region，应先追问；写操作必须 dry-run，不能直接 --yes。",
      "expectations": [
        "Triggered the skill",
        "Recognized missing required params",
        "Did NOT fabricate owner or region",
        "Planned dry-run before live write",
        "Did NOT pass --yes without explicit confirmation"
      ]
    }
  ]
}

推荐检查清单

写完 skill 后逐项检查：

  • name 只包含小写字母、数字、连字符，并与目录名一致。
  • description 写触发条件，不写完整流程。
  • When to use 覆盖用户真实说法、对象、URL、ID、错误码。
  • Do not use 覆盖相邻平台和误触发场景。
  • 调用方式清晰，包含安装、鉴权、site/env、JSON、debug。
  • 全局参数和子命令参数的位置有正反例。
  • 写操作有 dry-run 和用户确认协议。
  • 缺参数和多候选处理明确。
  • 明确禁止伪造 ID、版本、分支、region、scope。
  • 异步任务有轮询和终态判断。
  • 输出样例覆盖成功、失败、dry-run、running。
  • 错误处理保留 request_id、error.code、hint。
  • Reference 有触发条件，不是简单文件列表。
  • 重复逻辑已考虑脚本化。
  • evals 覆盖正向、负向、缺参、写操作、输出判断、错误处理。

常见反模式

把 CLI 手册整段塞进 SKILL.md

问题：正文过长，agent 抓不住每次必读的执行约束。

修正：正文保留操作规程，完整命令放 references/command-reference.md。

只有命令示例，没有流程

问题：agent 会跳过校验、确认、轮询和收尾。

修正：为复杂任务写“查询 -> 校验 -> dry-run -> 确认 -> 执行 -> 轮询 -> 终态”的流程。

只贴输出样例，不写判定规则

问题：agent 不知道哪个字段代表完成，容易把中间态当成功。

修正：在 output-shapes.md 写 success criteria 和状态枚举。

没有 Do not use

问题：相邻平台或相似关键词会误触发。

修正：列出明确边界和反例。

写操作没有确认协议

问题：agent 可能直接发布、删除、confirm 或审批。

修正：写操作默认 dry-run，用户确认后才 live write。

evals 只测 happy path

问题：skill 看起来能用，但压力场景下仍会猜参数、误路由、误判状态。

修正：evals 必须覆盖负向和失败场景。

一页版模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

---
name: <skill-name>
description: "Use when users mention <domain/tool/object/url/error> or need <task> through <cli>."
---

# <Skill Name>

## When to use
- ...

## Do not use
- ...

## Preconditions
- Install/auth/site/env requirements.

## Invocation
- Use `cli ...`.
- Use `cli --json ...` for machine-readable output.
- Read `references/invocation.md` for install/auth/site/debug.

## Critical agent protocol
- Query before write.
- Dry-run before live write.
- Ask when params are missing or candidates are multiple.
- Do not fabricate IDs, versions, branches, regions, scopes.
- Preserve request_id/error.hint on failure.

## Quick start
```bash
cli --json domain get --id <id>
cli domain list --limit 20
```

## Workflows
1. Query: ...
2. Create/update: ...
3. Async wait: ...
4. Troubleshooting: ...

## Output handling
- Read `references/output-shapes.md` before judging completion.
- `status=success` means CLI call succeeded, not necessarily task finished.
- Terminal states: ...
- Intermediate states: ...

## References
- `references/invocation.md`: install/auth/site/json/debug.
- `references/command-reference.md`: full command tree and parameters.
- `references/workflows.md`: multi-step flows.
- `references/output-shapes.md`: output examples and completion criteria.
- `references/troubleshooting.md`: error recovery.
Agent
Agent
This post is licensed under CC BY 4.0 by the author.