# SophClaw Skill Creator — 路径 A：创建新 skill / 修改已有 skill

适用于 skill 不存在或需要改动 skill 本身（代码、配置、SKILL.md）。

三步流程：需求对齐 → 方案对齐 → 生成代码。

```dot
digraph skill_create {
    rankdir=TB;

    start [label="用户请求创建/修改 skill", shape=oval];
    step1 [label="第一步：需求对齐\n自适应提问，明确需求", shape=box];
    spec1 [label="产出 design.md「需求说明」", shape=box];
    user_ok1 [label="用户确认？", shape=diamond];
    step2 [label="第二步：方案对齐\n设计结构 + 打磨 description", shape=box];
    spec2 [label="产出 design.md「方案设计」+「测试用例」", shape=box];
    user_ok2 [label="用户确认？", shape=diamond];
    step3 [label="第三步：生成代码\ngenerate.py 生成骨架", shape=box];
    edit [label="用户编辑 SKILL.md", shape=box];
    validate [label="validate.py 校验", shape=box];
    check [label="有 ERROR？", shape=diamond];
    done [label="完成 ✅", shape=oval];

    start -> step1;
    step1 -> spec1;
    spec1 -> user_ok1;
    user_ok1 -> step1 [label="否，修改"];
    user_ok1 -> step2 [label="是"];
    step2 -> spec2;
    spec2 -> user_ok2;
    user_ok2 -> step2 [label="否，修改"];
    user_ok2 -> step3 [label="是"];
    step3 -> edit;
    edit -> validate;
    validate -> check;
    check -> edit [label="是，修复"];
    check -> done [label="否"];
}
```

## 第一步：需求对齐

自适应提问，帮用户把 skill 想清楚。每次只问一个问题，多问"为什么"。至少覆盖：

1. **功能**：这个 skill 做什么？输入是什么？输出是什么？
2. **触发场景**：用户会怎么说话来触发它？（这是 description 的核心素材）
3. **上线平台**：确定 type，按以下决策树选择：

```dot
digraph type_select {
    rankdir=TB;

    q1 [label="用户能自己安装？", shape=diamond];
    q2 [label="默认所有用户可见？", shape=diamond];
    q3 [label="已确定长期维护？", shape=diamond];

    store [label="store\n商店可安装\n需中文 displayName/description", shape=box];
    builtin [label="builtin\n系统内置，默认可用", shape=box];
    private [label="private\n内部使用，CLI 不可见", shape=box];
    tmp [label="tmp\n临时/未分类，CLI 不可见", shape=box];

    q1 -> q2 [label="否"];
    q1 -> store [label="是"];
    q2 -> builtin [label="是"];
    q2 -> q3 [label="否"];
    q3 -> private [label="是"];
    q3 -> tmp [label="否/不确定"];
}
```

- `store`：**必须**有中文 displayName 和 description
- `private` / `tmp`：CLI list/download 不可见
4. **是否需要脚本**：涉及 API 调用？复杂数据处理？还是纯指令型的 SKILL.md 就够？
5. **是否需要 references/assets**：有大量参考文档？有模板文件？

确认需求后，产出 `design.md` 的「需求说明」部分，格式：

```markdown
# <skill-name> 设计文档

## 一、需求说明
- 功能描述
- 触发场景（用户怎么说话会触发）
- 输入/输出约定
- 上线平台及 type 选择理由
```

用户确认后进入下一步。

## 第二步：方案对齐

基于需求，设计 skill 结构。重点：

### 复用检查（先做，避免重复造轮子）

在讨论具体方案之前，先检查已有 skill 是否有可复用的代码或模式：

1. **完整读取已有 skill**：遍历 `<skills_dir>/` 下所有子目录，读取每个 skill 的全部文件（skill.json、SKILL.md、scripts/ 下的脚本）
2. **判断复用价值**：根据第一步确认的需求，找出哪些 skill 的代码或设计模式可以复用（如 API 调用封装、输出格式、错误处理、目录结构等）
3. **向用户呈现**：列出可复用的 skill 及具体复用点，问用户是否采纳

> **为什么先做复用检查？** 仓库里已有数十个 skill，很多基础能力已有成熟的实现。直接复用可以减少代码量、保持风格一致、避免引入新的 bug 模式。

### 目录结构设计

讨论并确定需要哪些资源目录（scripts/references/assets），产出目录树。

### description 打磨（核心）

这是最容易出问题的地方。**description 是 LLM 匹配 skill 的唯一依据**，必须包含功能+触发场景。

**公式**：`功能 + 触发场景 = 好的 description`

正例：
```yaml
description: 压缩 PNG/JPEG 图片。当用户要求压缩图片、减小图片体积、优化图片大小时使用。
```

反例：
```yaml
# ❌ 太长，没有触发场景
description: 这是一个功能强大的图片处理工具，支持多种格式的压缩、旋转、裁剪、滤镜等操作

# ❌ 只写了功能，没写何时触发
description: 图片压缩工具

# ❌ 写了实现细节
description: 使用 Pillow 库对图片进行有损压缩，支持调整质量和尺寸
```

**与用户协作打磨**：如果用户给的 description 太长或缺少触发场景，指出问题并帮助精简。

### 方案产出

在 `design.md` 中追加「方案设计」和「测试用例」：

```markdown
## 二、方案设计
- 目录结构
- 是否需要脚本及理由
- 架构（ASCII 流程图，展示数据流向和关键分支）
- 职责划分（组件职责表，逐一说明各文件/模块的职责）
- SKILL.md 关键设计决策（决策项 + 理由，帮助维护者理解 WHY）
- 注意事项

## 三、测试用例
| 编号 | 测试场景 | 触发语句 | 预期匹配 | 预期行为 | 预期输出 |
```

> **架构流程图要求**：使用 ASCII 框图展示核心流程，包含关键分支、循环（如轮询）、成功/失败路径。流程图的目的是让接手者在不开代码的情况下理解整体数据流。
>
> **关键设计决策要求**：每条决策需包含「是什么」+「为什么」，帮助维护者理解取舍而非仅知道配置值。例如不应只写"默认模型是 Seedance-2.0"，而应补充选择依据。
>
> **注意事项要求**：覆盖运维和开发层面的关键约束，包括但不限于：`uv run` 执行方式、`[[tool.uv.index]]` 阿里云镜像源配置、`pyproject.toml` 与 `skill.json` 版本同步、外部依赖、运行时约束、路径约定等。

测试用例至少覆盖：正常场景、不触发场景、边界场景。

用户确认后进入下一步。

## 第三步：生成代码

### 生成骨架

```bash
uv run {baseDir}/scripts/generate.py \
  --name <skill-name> \
  --type <builtin|store|private|tmp> \
  --display-name <中文名称> \
  --skill-description <中文描述> \
  --resources scripts,references,assets \
  --output-dir <skills_dir>
```

- `--display-name` 和 `--skill-description`：store 类型必填
- `--resources`：可选，逗号分隔，按需创建

### 用户编辑

生成后提醒用户编辑 `src/SKILL.md` 填充具体内容。编辑注意事项：
- description 已在第二步打磨好，直接填入 frontmatter
- 路径用 `{baseDir}/scripts/xxx.py`（不含 `src/`）
- 命令示范用 `uv run`，不用 `python`
- 不提及其他 skill
- 不写实现细节

### 校验

```bash
uv run {baseDir}/scripts/validate.py <skills_dir>/<skill-name>
```

```dot
digraph validate_loop {
    rankdir=TB;

    run [label="运行 validate.py", shape=box];
    has_err [label="有 ERROR？", shape=diamond];
    has_warn [label="有 WARNING？", shape=diamond];
    fix_err [label="修复 ERROR（必须）", shape=box];
    review [label="审视 WARNING\n决定是否修改", shape=box];
    done [label="通过 ✅", shape=oval];

    run -> has_err;
    has_err -> fix_err [label="是"];
    fix_err -> run [label="重新校验"];
    has_err -> has_warn [label="否"];
    has_warn -> review [label="是"];
    review -> run [label="修改后重新校验"];
    has_warn -> done [label="否"];
}
```

- **ERROR**：结构问题，必须修复（skill.json 缺失、name 不一致、store 缺少中文名等）
- **WARNING**：内容建议，建议审视修改（description 偏长、路径含 src/、用了 python 而非 uv run 等）

STATUS=succeeded 当且仅当无 ERROR。