Files

T

johnQ d43b414fc9 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 高危；现有测试通过

2026-10-31 22:03:13 +08:00

5.3 KiB

Raw Blame History

name, description, metadata, disable-model-invocation

name

description

metadata

disable-model-invocation

skill-creator

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

invocation	owner
user-invoked	qiudl

true

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

0. 一句话

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

1. 何时用

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

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

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，四节固定顺序：

What it does
When to reach for it
Common questions
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. 评审别人技能时看什么

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

5.3 KiB Raw Blame History Unescape Escape