---
name: skill-creator
description: 团队技能的标准流程：收录门槛、分桶生命周期、调用模式、SKILL.md 规范、evals 全量、四段式文档、路由回改。当要新建技能、大改现有技能、或评审一个技能是否合格时使用。
metadata:
  invocation: user-invoked
  owner: qiudl
disable-model-invocation: true
---

# 技能创建（团队标准流程）

## 0. 一句话

先有真实失败，再写技能；没有 evals 的技能不算完成；**技能目录是预算，不是收藏夹**。

## 1. 何时用

- 新建技能
- 大改现有技能（改 description、改核心流程、改门禁）
- 评审别人提上来的技能
- 判断某个想法「该不该做成技能」

何时不用：只改错别字/格式 → 直接改；一次性个人偏好 → 放个人技能，不进团队。

## 2. 收录门槛（先过这一关，再谈怎么写）

新技能**默认拒绝**，只有同时满足两条才立项：

1. **真实失败**：能说出在哪个真实任务/会话里出了问题——跑了什么、期望什么、实际什么。假想改进（「这样会更好」）不算。
2. **组合不出来**：用现有技能组合做不到；能组合的，就改现有技能，不新增。

被拒的想法记进仓库 `.out-of-scope/<概念>.md`，写清理由，避免下次重复讨论。

## 3. 分桶与生命周期

| 桶 | 含义 | 是否安装 | 是否进 README / plugin.json |
| --- | --- | --- | --- |
| `promoted` | 已验证、日常在用 | 默认安装 | 必须出现 |
| `beta` | 公开试跑，收反馈 | 需 `--include-beta` | 不进默认清单 |
| `deprecated` | 不再用 | 不安装 | 留文档，标弃用 |

- 新技能一律先进 `beta`，跑够真实使用 + evals 通过才 `promoted`。
- 只有 `promoted` 能进模型目录；beta 不占目录预算。

## 4. 调用模式（省目录 token 的关键）

每个技能二选一，写进 frontmatter：

- **`model-invoked`**（默认）：进模型目录，agent 自己判断何时用。
- **`user-invoked`**：只由人下命令触发，**不进模型目录**；必须同时写 `disable-model-invocation: true` 和 `metadata.invocation: user-invoked`。

判定口径：这件事是不是「人下命令才开始」？是 → user-invoked。典型：publish、retro、triage、发布 runbook、建技能。

## 5. SKILL.md 硬约束（Agent Skills 规范）

- 目录：`SKILL.md` + 可选 `scripts/`、`references/`、`assets/`
- frontmatter 必填：`name`（小写字母/数字/连字符，≤64）、`description`（≤1024，写清「做什么 + 何时用」）
- 可选：`license`、`compatibility`、`metadata`、`allowed-tools`
- **非标准字段**一律进 `metadata`
- 正文 ≤20KB（约 5000 token），细节拆 `references/`
- 只写 agent 不知道的东西：项目约定、边界、坑；不写通用常识

## 6. 正文结构模板

```
# 名称
## 0. 一句话
## 1. 何时用 / 何时不用
## 2. 步骤（可执行、有顺序）
## 3. 硬约束与红线
## 4. 常见坑（gotchas）
## 5. 验证清单
## 6. 参考（references/ 链接）
```

## 7. evals（强制、全量）

- 路径：`evals/evals.json`；至少 3 条：正常路径 / 边界输入 / 失败恢复
- 跑「有技能 / 无技能」对比，结果存 `iteration-<N>/`，按 rubric 打分，PR 附结果

## 8. 四段式文档（每个 promoted 技能一篇）

`docs/skills/<name>.md`，四节固定顺序：

1. **What it does**
2. **When to reach for it**
3. **Common questions**
4. **It's working if**（必须给可验证证据，不许写「感觉对了」）

beta 不写文档；弃用保留文档并标 archived。

## 9. 路由回改（硬规则）

所有技能增、删、改名、改行为后，**必须同步回改入口技能 `ai-proj-helper-entry` 和 `catalog.json`**。一个没提到新技能、或还在路由到已删技能的路由器，就是假的路由器。

## 10. 质量门禁（提 PR 前逐条打勾）

- [ ] 过了收录门槛（真实失败 + 组合不出来）
- [ ] 桶与调用模式已标，`beta` 不得出现在默认清单
- [ ] `name`/`description` 合规，description 含「何时用」
- [ ] 正文 ≤20KB，细节已拆 references
- [ ] evals ≥3 条，有「有/无技能」对比
- [ ] 四段式文档已写（promoted 才需要）
- [ ] 入口路由与 `catalog.json` 已回改
- [ ] `plugin.json` 已登记 `install_name`/`install_type`/`dir_category`/`status`/版本号
- [ ] `python3 scripts/validate-skills.py` 通过
- [ ] `./scripts/scan-skill.sh` 无高危项
- [ ] 版本号与 CHANGELOG 已更新
- [ ] 无绝对路径、无凭据、无内网地址

## 11. 反模式

- 一次写 800 行「大全」，什么都想覆盖
- description 写成「各种任务都能用」
- 没有 evals 就提 PR；没有四段式文档就 promoted
- 直接复制外部技能，不改写成我们的 REQ/ai-proj 语境
- 把临时排障步骤固化成团队技能（这类放 personal）
- 技能改名后忘了回改路由

## 12. 评审别人技能时看什么

1. 收录门槛过没过（有没有真实失败）
2. description 能不能让模型判断「何时用」
3. 桶与调用模式是否正确（该 user-invoked 的别占目录）
4. 和现有技能是否重复（先查 `catalog.json`）
5. evals 是否覆盖失败路径、文档是否有「It's working if」
6. 是否触碰红线（自审批、绕过门禁、绝对路径、凭据）