# Writing Skills

> 当需要创建新技能、修订已有技能、优化 description 触发精度，或验证某个技能在压力下是否真的有效时使用。 症状：你要教 AI 一个非显而易见的技术、模式、工作流或参考流程；你已经写了指令， 但还没有基于真实智能体行为验证它；技能描述触发不准（误触发/漏触发）。 不适用于：项目级约定、一次性解决方案、应由自动化强制执行的机械规则，或 AI 已经 掌握的通用标准实践。

- Skill: `tomorrowlm/writing-skills` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add tomorrowlm/writing-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomorrowlm/writing-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: TomorrowLM (https://skillmd.com/u/tomorrowlm)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomorrowlm/writing-skills

---


# Writing Skills

把技能当作给 AI 的可执行工作流文档，而不是给人的说明书。写技能 = 把 TDD 用在文档上：先观察失败，再写最小规则，再堵住漏洞。

**铁律：没有失败的测试，就不要写技能。**

压力越大，越要先跑基线测试；不要因时间不够、领导要求、业务 blocked、已有长草稿或手动检查过而跳过红色阶段。

已写好的草稿不能作为“参考”保留。先基线测试，再从观察到的失败写最小规则；否则测试会变成替既有草稿背书。

## 开始前：确认测试授权

- 用户当前请求已包含“测试”“验证”或“跑评估”：视为已授权，直接进入基线阶段，不要重复询问。
- 用户只要求创建或修改：先说明必需的基线与复测范围并询问是否执行；未授权测试时不修改，只能提供分析或测试方案。
- 测试中断或用户撤回授权：将产物标记为未验证并移出加载、注册和分发路径，不得宣称技能已完成。

## HARD-GATE：先观察失败

以下规则无例外，即使用户说“直接写”、“不要测试”、“只改一个词”、“不能删除草稿”、“领导已审批”或“今天必须发布”：

1. 创建或修改技能前，先在不加载目标技能、不参考现有草稿的情况下运行基线场景，并记录至少一个真实失败。
2. 基线没有失败时，暂停或放弃修改；不得为了假想价值继续写，也不得发布未验证版本。
3. 现有草稿需要保留时，将其移出技能加载和分发路径，标记为未验证材料；不要在红色阶段读取、改写或作为参考。
4. 后文的“结构化逃生路径”是设计其他技能时的模式，不是绕过本技能红色阶段的许可。
5. 修改后的纪律类技能未通过真实智能体压力测试时，只能保持未验证状态；不得注册、发布或宣称完成。

## 什么时候用 / 不适用

- 用：创建、重写技能；教 AI 非显而易见的模式；验证压力下有效性；description 触发不准需要量化优化。
- 不用：一次性解决方案、项目局部约定、可用脚本强制执行的机械约束、AI 已掌握的常识。

## 一、如何写技能

### 先访谈需求

写之前先理清五点，主动追问边界、输入输出格式、成功标准、依赖项：

1. 要让 AI 做到什么？
2. 什么表述或上下文应触发？
3. 什么上下文不应触发？
4. 期望的输出格式和行为边界是什么？
5. 需要哪些测试用例来验证？

### 使用三级渐进式披露

```text
skill-name/
├── SKILL.md              # 入口：触发条件、流程、红线、引用条件
├── references/           # 按需加载的展开说明
│   └── tests/            # 压力测试、学术测试和触发测试
├── scripts/              # 可执行脚本
└── assets/               # 产出物模板
```

- `name` + `description`：始终在上下文中，决定是否触发。
- `SKILL.md` body：触发时加载，只保留控制逻辑。
- `references`：按需读取，承载长示例、完整工作流、背景、模板。
- 技能测试文件放 `references/tests/`，不要散落在技能根目录。

### 按红-绿-重构编写

1. **红**：在没有技能时跑压力场景，逐字记录 AI 的选择、借口、违规点。没有基线失败就不写。
2. **绿**：只针对观察到的失败写最小规则，解决真实漏洞，不预防假想问题。
3. **重构**：AI 又找到新借口就补进规则，反复测试到无法绕过。

### 编写规则速查

- `frontmatter` 只保留必需字段：`name` 和 `description`。
- `name` 只用字母、数字、连字符。
- `description` 用中文写清“当……时使用”，包含触发条件、症状和不适用边界，不总结完整流程。
- body 先写控制逻辑，再写细节；用祈使语气；解释“为什么”优于命令式。
- 一个强示例胜过多个弱示例；不写填空模板，写可直接适配的模式。
- 不影响执行顺序的内容下沉到 `references`；`SKILL.md` 超 250 行就拆分。
- `SKILL.md` 与 `references` 不重复，不创建面向人的 README、CHANGELOG、QUICK_REFERENCE。
- 纪律类技能要写“不要怎样变通”；显式封堵“这只是简单改动”“之后再测也一样”“保留草稿当参考”之类借口。
- 多 Agent / 子任务编排遵循隔离自包含加载、增量上下文收敛与确定性输入，详见 `references/guides/anthropic-best-practices.md`。

### HARD-GATE 判断规则

不是所有规则都应该是 HARD-GATE。判断标准：

| 问题 | 软规则 | HARD-GATE |
|------|--------|-----------|
| 用户绕过规则后，如果出错，用户能立刻发现吗？ | 能 | 不能 |
| 绕过规则会导致不可逆的坏结果吗？ | 不会 | 会 |
| 规则防止的是 AI 的常见错误，还是用户偏好？ | 用户偏好 | AI 常见错误 |

满足任一 HARD-GATE 条件，就写 HARD-GATE 段落：

```markdown
## HARD-GATE

以下规则无例外，即使用户说“直接改”、“跳过”、“手动模拟”、“紧急”或“简单”：
1. 规则一
2. 规则二
```

HARD-GATE 必须显式列出用户最可能说的绕过借口，并声明无效。不写“用户明确指令优先于 skill 规则”这个通用漏洞——它会让所有 HARD-GATE 失效。

压力测试的核心目的就是验证 HARD-GATE 是否真的不可绕过：用“别读了直接调”“手动模拟就行”“太简单不用走流程”等话术攻击每条红线，AI 必须拒绝。
### HARD-GATE vs 结构化逃生路径

按受保护的最终状态判断，不按施压者是谁判断：

- 绕过会产生不安全、不可逆或未验证的最终状态时，使用 HARD-GATE；团队、权威和时间压力都不是例外。
- 结构化逃生路径只用于目标技能预先定义的可逆协作分支；可以调整过程，不能把未满足的成功标准改称已满足。
- “不算违反门禁”必须由技能预先定义，AI 不能在压力现场自行宣布。
- 对 `writing-skills` 自身，现实阻塞时只能隔离草稿并记录风险，不能发布未验证技能。

结构化逃生路径模式和抵制合理化的写法见 `references/guides/persuasion-principles.md`；结构、命名、description 和渐进式披露原则见 `references/guides/anthropic-best-practices.md`。

## 二、Token 效率：引用 token-saving

写技能、改技能、测试技能时，直接使用 `token-saving` 技能中的“写技能 / 改技能 / 测试技能”分流说明。

本技能不重复展开省 token 方法；如果任务涉及长文档、多文件、子代理或长对话，先按 `token-saving` 设定预算、分层读取、阶段压缩，再继续写技能。

## 三、测试命中率与评分

技能有效性靠测试证明，不靠感觉。测试前必须有基线失败记录；没有红色样本，就不要进入评分。

### 测试维度

| 技能类型 | 测试重点 |
|----------|----------|
| 纪律执行类 | 压力下是否守规矩：学术题、压力场景、组合压力。 |
| 技术 / 模式类 | 新场景能否用对、边界条件、反例识别。 |
| 参考类 | 能否正确检索并应用。 |

### 测试类型

| 测试类型 | 目的 | 最小覆盖 |
|----------|------|----------|
| 触发测试 | 验证 `description` 是否正确命中。 | 20 条 eval 查询，包含应触发、不应触发、近义、边缘场景。 |
| 行为测试 | 验证加载技能后是否按流程执行。 | 1 条正常场景、1 条边界场景、1 条不应触发场景。 |
| 压力测试 | 验证时间压力、用户催促、简单任务伪装下是否仍守规则。 | 至少 3 条，必须覆盖技能最容易被绕过的借口。 |

### 命中率测试流程

触发不准时，优化 `description`：

1. 造 20 条 eval 查询，标注 expectedTrigger。
2. 手动改 `description`。
3. 跑触发测试。
4. 统计命中率、误触发率、漏触发率。
5. 重复到稳定。

### 失败归因

| 失败类型 | 优先修改位置 |
|----------|--------------|
| 应触发未触发、不应触发却触发 | `description`。 |
| 触发后流程顺序错误 | `SKILL.md` 控制逻辑。 |
| 压力下找借口绕过红线 | 补“不要怎样变通”的反借口规则。 |
| 新场景应用错误 | 补最小规则或强示例，避免堆砌泛化说明。 |
| Token 成本过高 | 下沉长内容到 `references/`，入口只保留决策逻辑。 |

### 评分建议

| 指标 | 评分方式 |
|------|----------|
| 命中率 | 应触发用例中实际触发的比例，建议 ≥ 90%。 |
| 误触发率 | 不应触发用例中错误触发的比例，建议 ≤ 10%。 |
| 任务成功率 | 使用技能后完成目标的比例。 |
| 规则遵守率 | 关键红线是否被遵守，红线类规则必须 100%。 |
| Token 成本 | SKILL.md 行数是否 ≤ 250，简单任务是否引入不成比例开销。 |

### Token 成本评估（简化版）

目标：确认技能不会为简单任务引入不成比例的开销。**不要求子代理自报估算数（不可靠），只检查两点：**

1. **SKILL.md 行数**：≤ 250 行。超过则拆分到 `references/`。
2. **简单任务开销**：挑一条最简单的触发用例，肉眼对比带技能与基线的隔离智能体输出。如果带技能输出明显更长（感官上 > 50%），且多出的内容只是技能自身的流程说明模板而非解决任务所需，则把模板内容下沉到 `references/`。

两点都通过，结论写"可接受"。不需要全量采集，不需要字符→token 换算。

### 测试记录格式

每条用例至少记录：用例文本、是否应触发、实际是否触发、是否遵守关键规则、失败原因、下一步修改点。

测试完成后必须输出评分表，至少包含：指标、通过数 / 总数、得分或比例、结论、失败用例摘要。只给“通过了”“效果不错”不合格。

| 指标 | 通过数 / 总数 | 得分或比例 | 结论 |
|------|---------------|------------|------|
| 触发命中率 | - | - | - |
| 非触发识别率 | - | - | - |
| 压力规则遵守率 | - | - | - |
| 任务成功率 | - | - | - |
| 规则红线遵守率 | - | - | - |
| Token 成本 | SKILL.md 行数 / 简单任务开销 | — | 可接受 / 需优化 |

需要定量对比时：每条用例并行启动两个相互隔离的智能体运行（可用 subagent 实现），一个加载技能，一个不加载，比较带技能与基线差异。完整流程、评估 JSON 格式、断言写法见 `references/methodology/quantitative-evaluation.md`；设计压力场景和堵漏洞见 `references/methodology/testing-skills-with-subagents.md`。

本技能自身的触发与压力测试用例见 `references/tests/evals.json`。

## 迭代

改技能 → 跑测试对照 → 等反馈 → 继续，直到用户满意或改进不再有意义。保持精简、泛化反馈、删除无效内容。

## 技能集成

- 写技能时：按本技能执行。
- 省 token 时：直接分流到 `token-saving`。