# 技能重写与新增规范

这份规范供以后重写技能包、或者往包里加新技能时使用。它记下了第一次重写时踩到的坑。

## 一、最重要的一条：附件分两类，不能一刀切

第一次重写时规定「一律单文件、不要附件」，结果把方法类内容全压掉了，知识密度掉了 19%（1533 行降到 1237 行），代码与模板块从 34 个变成 0 个。教训是附件要分两类：

| 类型 | 例子 | 怎么处理 |
|---|---|---|
| **模板类**（规定某个文件里写什么） | 教学立意的四个字段、学习记录格式、ADR 格式、术语表条目格式 | **压进正文**。信息不丢，还少一个文件 |
| **方法类**（怎么做的知识） | mock 准则、深模块词汇表、代码坏味道清单、设计两次的流程、反馈回路手段菜单 | **必须留附件**。压不进一屏，压了就真没了 |
| **机制类**（不做会静默出错） | DSH 的 frontmatter 规则、名称不匹配会被丢弃、阶段边界的取舍 | **必须留附件**，而且优先级最高 |

**正文保持一屏内（30 到 80 行），方法类和机制类内容写进同目录的附件，正文用一行指针指过去。**

## 二、机制类内容清单（不做会出硬性错误）

写技能、写 `AGENTS.md`、写任何给模型读的文档时，这些必须讲到：

- `name` 必须与技能目录名一致，不一致会被 DSH 静默丢弃，且不给任何提示
- DSH 认的 frontmatter 字段只有：`name`、`description`、`whenToUse`、`disable-model-invocation`、`user-invocable`；`argument-hint`、`metadata`、`agents/openai.yaml` 一概不认
- 模型可调用的技能，`description` 是常驻成本，要写触发场景；只允许人工发起的技能，`description` 是给人看的，不写触发词
- 什么时候该继续当前会话、什么时候该开新会话、什么时候该做交接——选错是单向损失

## 三、正文怎么写

- **长度**：一屏以内，30 到 80 行
- **祈使句**：直接写动作，不写「你应该……」
- **正向表述**：写要做什么。禁令会把被禁止的行为拉进注意力（第一次重写把禁令从 81 处降到 39 处，这是对的）
- **每步给完成标准**：写清「怎么算这一步完了」，要能判定。第一次重写把完成标准从 6 处提到 51 处，这是最大的收获，要保持
- **description 写用户的原话**：把用户可能说的句子放进去，自动触发才准

## 四、统一术语

| 用 | 不用 |
|---|---|
| 缝（seam） | 接口点、接入点 |
| 深模块（deep module） | 大模块 |
| 曳光弹（tracer bullet） | 垂直切片 |
| 反馈回路 | 测试基线 |
| 票据 | 任务卡、工单 |
| 规格（spec） | 需求文档、PRD |
| 影响半径 | 影响范围 |
| 上下文窗口的舒适区 | 智能区、smart zone |
| 一轮问一批 | 前沿、frontier |

## 五、DSH 适配

- 调用别的技能：写「用 `skill` 工具加载技能 X」
- 并行干活：写「用 `subagent` 工具在同一条消息里发起」
- 票据与规格：`docs/agents/tickets/<编号>-<短名>.md`，一个文件一张，编号从 1 递增，依赖写「阻塞于 #N」，顶部一行状态（`待确认` / `已就绪` / `进行中` / `已完成`）
- 票据约定：`docs/agents/issue-tracker.md`，由内置技能 `setup-tickets` 创建
- 项目说明文件叫 `AGENTS.md`
- 没有工作树隔离，改动直接在当前工作区做
- 不写具体文件路径和代码片段，要表达决策就写决策本身

## 六、只允许人工发起的技能

`handoff`、`implement`、`teach`、`to-spec`、`to-tickets`、`to-questionnaire`、`wait-what`、`retro`、`improve-codebase-architecture`

这九个加 `disable-model-invocation: true`，其余不加。检查脚本会核对。

## 七、写完怎么验收

```
node check-pack.mjs      # frontmatter、长度、人工发起标记、禁用术语、附件统计
node verify.mjs          # 插件整体自测
```

`check-pack.mjs` 只管形式。形式和机制之外的东西——内容够不够、有没有把该留的方法压掉——只能靠人读。**改完技能包之后，至少抽读三个技能，重点看附件有没有替正文承担该承担的细节。**