---
name: shb-skill-creator
description: 创建新技能、修改和改进已有技能。当用户想把当前对话或一段可复用工作流保存成技能(skill)、创建技能、编辑或优化已有技能、让技能更容易被正确触发时,务必使用本技能——即使用户没有明说"创建 skill",只要出现"把这个流程记下来/存成技能/以后还要这样做"之类的意图也应触发。
---

# Skill Creator

用于在 shb chat 里创建新技能并迭代改进它们。

执行环境说明:本环境通过 `write_skill` 工具落地技能(它写 SKILL.md + 可选 references,并即时重载),通过 `shell` 工具运行 shb-cli 验证。**不要**尝试 spawn 子 agent、运行 python 评估脚本、打开浏览器 viewer 或打包技能文件——本环境只有 shell / skill / write_skill 三个工具。这里的循环是:理解意图 → 起草技能 → 用真实 shb-cli 命令验证 → 根据用户反馈改进 → 重复。

## 与用户沟通

使用者的技术熟悉度差异很大。注意语境线索调整措辞:默认情况下,"评估""基准"勉强可以;"JSON""断言"这类要先确认用户懂再用,拿不准就用一句话解释。

## 创建技能

### 1. 捕捉意图(Capture Intent)

先理解用户想要什么。**当前对话里往往已经包含用户想固化的工作流**(比如他说"把这个存成技能")。优先从对话历史里提取:用过哪些 shb-cli 命令、步骤顺序、用户做过的纠正、观察到的输入/输出格式。缺的部分让用户补,推进下一步前请用户确认:

1. 这个技能要让助手能做什么?
2. 什么时候该触发它?(用户会说哪些话/在什么场景)
3. 期望的输出/结果是什么?

### 2. 追问与调研

主动追问边界情况、输入输出格式、示例、成功标准、依赖。带着上下文来,减轻用户负担——比如需要某工单类型的字段时,先用 shell 跑 `shb-cli task field ...` 查清楚,而不是反问用户。

### 3. 写 SKILL.md

根据访谈填好这几部分(用 `write_skill` 工具产出):

- **name**:技能标识,kebab-case(小写字母/数字/连字符),用能力短语命名,如 `task-bulk-export`、`customer-onboarding`。避免 `helper`、`utils` 这类泛名。
- **description**:这是**主要触发机制**——既说"做什么"又说"何时用",所有"何时使用"的信息都放这里,不要放正文。
  - 第三人称陈述。
  - **要稍微"用力"一点(pushy),对抗欠触发**:当前模型倾向于"该用技能时不用"。所以与其写 `导出某类工单的方法`,不如写 `当用户提到导出、批量、某状态/某类型工单,或想把工单数据导出成表格时务必使用本技能,即使没明说"导出"二字`。
  - 具体、含用户会说的关键词。
  - 不要放时效信息(如"2025 年前用旧接口"),这类放正文的"兼容/历史"小节。
- **body**:技能正文(怎么做)。
- **references**(可选):大块细节拆出去。

### 技能写作指南

#### 技能的结构(Anatomy)

```
skill-name/
├── SKILL.md (必需:frontmatter[name/description] + markdown 指令)
└── references/   - 按需读取的文档(字段字典、payload 模板、示例集)
```

(shb-cli chat 的技能以 SKILL.md + references 为主。)

#### 渐进式披露(Progressive Disclosure)

技能分三层加载:

1. **元数据**(name + description)——始终在上下文里(≈100 词)。
2. **SKILL.md 正文**——技能触发时进入上下文(理想 <500 行)。
3. **references 文档**——需要时才读(可较大)。

要点:
- SKILL.md 控制在 500 行内;接近上限就加一层 references,并在正文里清楚指明"什么情况去读哪个文件"。
- 大的 reference(>300 行)给个目录。
- 一个技能支持多个变体/场景时,按变体拆 references:

```
task-export/
├── SKILL.md (流程 + 如何选择)
└── references/
    ├── fields.md
    └── filters.md
```

模型只读相关的那个。

#### 写作风格

- 用祈使句写指令。
- **解释"为什么",而不是堆砌生硬的 MUST/ALWAYS**。今天的模型很聪明、有很好的 theory of mind,给它讲清楚某步为何重要,它能举一反三。如果你发现自己在写全大写的 ALWAYS/NEVER 或极其死板的结构,这是黄线——尽量改成解释原因。
- 让技能通用,不要过拟合到某几个具体例子。
- 先写草稿,再用"新鲜的眼睛"重看一遍改进。

**定义输出格式**示例:

```markdown
## 报告结构
始终用这个模板:
# [标题]
## 概要
## 关键发现
## 建议
```

**举例的写法**:

```markdown
## 命令示例
输入:导出 tcl 维修测试类型下所有处理中的工单
命令:shb-cli task search --data '{"templateId":"<id>","state":"processing"}' --all --format-data --fields taskNo,state,customer,createTime -o table
```

#### 内容安全(Principle of Lack of Surprise)

技能不得包含恶意内容,其意图应与描述一致,不得用于未授权访问、数据外泄等。

#### 可执行脚本(scripts/)

当某步是"单条 shb-cli 表达不了的多步/循环/数据加工"(如批量翻页聚合、字段重算、生成报表)时,技能可附带脚本,放 `scripts/` 下(.sh/.bash/.py/.js/.rb)。机制与安全:

- 用 `write_skill` 的 `scripts` 参数写入,传 `{"scripts/xxx.py": "脚本内容"}`,写入时**用户会逐字审阅每个脚本**并确认。
- 之后用 `run_script(skill, script, args?)` 执行;**每次执行用户都会看到脚本全文 + 危险扫描结果并确认**。
- 脚本运行时 chat 的密钥(SHB_CLI_CHAT_*)已从环境剔除;**绝不要**在脚本里读取或外泄 token、密钥、~/.ssh、凭证文件。
- 脚本里要跑 shb-cli 就直接调(它读本地登录态),不要在脚本里塞 key。
- 优先用 shb-cli 命令 + 正文步骤;只有确实需要程序化逻辑才用脚本。

### 4. 用 write_skill 落地

调用 `write_skill(name, description, body, references?, scripts?)`(写操作,会弹确认)。
- references 传 `{"references/xxx.md": "内容"}`;scripts 传 `{"scripts/xxx.py": "内容"}`。
- 创建后技能本会话即可加载;告诉用户技能名,可直接复用。

### 5. 验证与迭代

shb chat 没有自动评估/基准设施,用轻量方式验证:
- 用 `shell` 跑技能里写的 shb-cli 命令,确认能跑通、字段/参数正确。
- 想几个用户真会说的话,自查这个 description 是否会被正确命中(尤其欠触发)。
- 根据用户反馈改:**从反馈泛化**(别做过拟合的小修小补),**保持精简**(删掉不起作用的部分),**解释 why**。
- 改完重新验证,直到用户满意。

## 改进已有技能

要改已有技能而非新建时:**保留原 name 与目录名不变**。读出现有 SKILL.md,按上面的写作原则修订 description 与正文,用 `write_skill`(overwrite 场景由实现决定)或直接编辑文件。重点关注用户有具体抱怨的地方,空反馈表示那部分没问题。

---

核心循环(再强调一遍):
理解意图 → 起草/编辑技能 → 用真实 shb-cli 命令验证 → 听用户反馈改进 → 重复,直到满意。