---
name: skill-creator
description: >
  当用户要求创建新 skill、修改现有 skill、或优化 skill 的触发准确性时使用。
  覆盖 skill 的设计、编写、验证和分发全流程。
  触发短语：创建 skill、新建技能、修改 skill、create skill、
  new skill、edit skill、optimize skill description。
---

# 技能创建与维护

在 `.agents/skills/` 下创建或修改 skill，并通过 `npm run sync:skills` 分发到
`.claude/skills/`、`.cursor/skills/`、`.codex/skills/`。

## 项目约束（必须遵守）

- **唯一维护源**：`.agents/skills/` 是 skill 的唯一编辑入口，分发目录不手动修改
- **同步机制**：每次修改后执行 `npm run sync:skills`
- **语言**：description 用中文为主 + 英文触发词；SKILL.md 正文中文
- **入口同步**：新增/删除 skill 后更新 `.agents/skills/README.md`

## 工作流

### 1. 明确意图

确认用户需求：
- 新建 skill？修改已有 skill？优化 description？
- skill 要支持什么功能？何时触发？输出什么？

### 2. 设计

#### 目录结构

```
skill-name/
├── SKILL.md              # 必需
├── references/            # 可选，按需加载的参考文档
├── scripts/               # 可选，可执行脚本
└── assets/                # 可选，输出用文件（模板等）
```

#### Frontmatter（必需字段）

```yaml
---
name: skill-name           # ≤64 字符，小写+连字符，与目录名一致
description: >              # ≤1024 字符，包含触发短语
  中文描述 + 英文触发词。
  触发短语：中文短语1、中文短语2、english phrase1、english phrase2。
---
```

可选字段：`allowed-tools`（预授权工具）、`metadata`（author/version）、`compatibility`（环境要求）。

#### 渐进式披露

| 级别 | 内容 | 加载时机 | 预算 |
|------|------|---------|------|
| L1 | name + description | 始终加载 | ~100 tokens |
| L2 | SKILL.md 正文 | 触发时加载 | < 5000 tokens |
| L3 | references/scripts/assets | 按需加载 | 无硬限 |

### 3. 编写 SKILL.md

#### 推荐分节

1. **定位** — 一句话说清 skill 做什么
2. **核心规则** — ~5-7 条，祈使句，可验证
3. **工作流** — 明确步骤
4. **模板/索引** — 如有 references，列出映射表
5. **输出要求** — 明确不同场景的输出格式

#### 内容优先级（高→低）

1. **Gotchas** — 项目特有的反直觉事实（最高价值）
2. **输出模板** — 具体输出格式结构
3. **检查清单** — 多步骤流程的检查项
4. **验证闭环** — 执行→验证→修复→重复

#### 写作原则

- 用祈使句，不用被动语态
- 解释 **why**，不只写 MUST/NEVER — agent 理解原因后执行更好
- 不教 agent 已知的基础知识
- description 写得"强势"一些——明确列出触发场景，包括间接提及
- 控制粒度匹配任务脆弱性：脆弱操作 → 严格步骤；灵活任务 → 启发式指引

### 4. 验证

```bash
python3 .agents/skills/skill-creator/scripts/quick_validate.py .agents/skills/<name>
```

手动检查：
- description 是否包含中英文触发短语
- SKILL.md 中引用的 references/scripts/assets 路径是否真实存在
- 是否有孤立的 references 文件（存在但未被 SKILL.md 引用）
- 正文语言是否为中文（英文仅用于触发词和必要术语）

### 5. 同步分发

```bash
npm run sync:skills
```

验证同步：`diff .agents/skills/<name>/SKILL.md .claude/skills/<name>/SKILL.md`

新增 skill 时更新 `.agents/skills/README.md`。

### 6. 迭代改进（可选）

用真实任务测试 skill，观察 agent 执行效果，然后改进：
- 读执行过程，不只看最终输出
- 如果 agent 反复写相同辅助代码，固化为 `scripts/`
- 移除没产生价值的指令，保持精简
- 可使用 `scripts/run_loop` 优化 description 触发准确性，详见 `references/schemas.md`

## 核心规则

1. **唯一源 + 同步** — 只改 `.agents/skills/`，改完执行 `npm run sync:skills`
2. **精简至上** — agent 已经很聪明，只写它不知道的内容
3. **先验证后分发** — 检查路径引用、语言规范、结构完整性，再同步
4. **解释 why** — 规则要说明原因，不只下命令