# Scope — ai-proj-helper 技能的收录门槛

本仓库是团队每天在用的技能集，**不是技能收藏夹**。技能目录会在每次会话启动时占用模型的上下文预算，所以「多加一个」永远是有代价的。

## 门槛

新技能或改动**默认拒绝**，只有同时满足两条才进入评审：

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

规模不重要：一个词的修改和一次重写按同一标准审。

## 分桶

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

新技能一律先进 `beta`；promoted 需要真实使用记录 + evals 通过。

## 调用模式

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

判定：这件事是不是「人下命令才开始」？是 → user-invoked。

## 已经拒绝的想法

每个被拒概念一个文件，写在 [`.out-of-scope/`](./.out-of-scope/) 下，先读再提。当前已有：

- [`new-skills.md`](./.out-of-scope/new-skills.md)
- [`harness-specific-branches.md`](./.out-of-scope/harness-specific-branches.md)
- [`personal-workflow-tweaks.md`](./.out-of-scope/personal-workflow-tweaks.md)

## 提交流程

1. 先过 [`skill-creator`](./skills-core/skill-creator-plugin/skills/SKILL.md) 的收录门槛与质量门禁。
2. `python3 scripts/validate-skills.py` 通过。
3. `./scripts/scan-skill.sh` 无高危项。
4. `python3 scripts/generate-catalog.py` 更新 `catalog.json`。
5. 版本号 + CHANGELOG 更新，走 PR。

## 覆盖率路线图（evals 与四段式文档）

目标集合：`promoted` 且 `model-invoked` 的技能（当前 40 个）。用户级命令技能（`user-invoked`）只要求四段式文档，不强制 evals。

| 阶段 | 范围 | 验收 |
| --- | --- | --- |
| 第 1 周 | `core/` + `req/` 类（约 15 个） | `--coverage` 里这些类目缺口为 0 |
| 第 2 周 | `dev/` 类（约 20 个） | 同上 |
| 第 3–4 周 | 其余（`integration/`、`biz/` 里仍 model-invoked 的） | 全量缺口为 0 |

每个技能的最低要求：`evals/evals.json` 3 条（正常 / 边界 / 失败恢复）+ `docs/skills/<name>.md` 四段式（What it does / When to reach for it / Common questions / It's working if）。

先用 `python3 scripts/validate-skills.py --coverage` 看当前缺口，再按阶段补。