feat(skill): 技能治理 v0.2 —— 分桶/调用模式/校验/安全/清单/安装矩阵
- 新增 SCOPE.md 收录门槛 + .out-of-scope/ 拒绝档案 - 生命周期分桶 promoted/beta/deprecated，marketplace 只发布 promoted - 调用模式 model-invoked/user-invoked（user-invoked 不占模型目录） - 新增脚本 validate-skills.py / generate-catalog.py / scan-skill.sh(+allowlist) - 新增 beta 技能 skill-creator、ai-proj-helper-entry、verification-before-completion（各带 evals） - install-skills.sh: --agent dsh / --link / --audit / --include-beta / --no-validate - 融合：dev-review 接收评审意见、req-design 依赖边、agent-swarm 并行编排、dev-test TDD - catalog.json 61 个技能（58 promoted / 3 beta）；validate 0 错误；scan 0 高危；现有测试通过
This commit is contained in:
johnQ
@@ -0,0 +1,127 @@
|
||||
---
|
||||
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. 是否触碰红线（自审批、绕过门禁、绝对路径、凭据）
|
||||
Reference in New Issue
Block a user