writing-skills

编写技能

概述

编写技能就是将测试驱动开发应用于流程文档。

个人技能存放在特定 Agent 的目录中（Claude Code 使用 ~/.claude/skills，Codex 使用 ~/.codex/skills）

你要编写测试用例（与子 Agent 配合设计压力场景），观察测试失败（基线行为），编写技能（文档），观察测试通过（Agent 遵守要求），然后重构（堵住漏洞）。

**核心原则：**如果你没有观察过 Agent 在没有技能时失败，就不知道这项技能是否教会了正确的做法。

**必备背景知识：**使用这项技能前，你必须了解 tdd。该技能定义了基础的 RED-GREEN-REFACTOR 循环。本技能将 TDD 应用于文档编写。

**官方指南：**如需了解 Anthropic 官方的技能编写最佳实践，请参阅 anthropic-best-practices.md。本文档提供了补充模式和指南，与本技能侧重 TDD 的方法相辅相成。

什么是技能？

技能是经过验证的技术、模式或工具的参考指南。技能有助于未来的 Claude 实例找到并采用有效的方法。

**技能包括：**可复用的技术、模式、工具和参考指南

**技能不包括：**讲述你如何一次性解决某个问题的叙述

技能的 TDD 对应关系

TDD 概念	技能创建
测试用例	使用子 Agent 设计压力场景
生产代码	技能文档（SKILL.md）
测试失败（RED）	Agent 在没有技能时违反规则（基线）
测试通过（GREEN）	提供技能后 Agent 遵守要求
重构	在保持遵守要求的同时堵住漏洞
先编写测试	在编写技能前运行基线场景
观察失败	记录 Agent 使用的确切说辞
最少代码	编写针对这些具体违规行为的技能
观察通过	验证 Agent 现在是否遵守要求
重构循环	找出新的说辞 -> 堵住漏洞 -> 再次验证

整个技能创建过程都遵循 RED-GREEN-REFACTOR。

何时创建技能

在以下情况下创建：

• 你觉得这项技术并非直觉上显而易见
• 你会在不同项目中再次参考它
• 该模式适用范围广（而非仅适用于特定项目）
• 其他人也能从中受益

以下情况不要创建：

• 一次性解决方案
• 其他地方已有完善文档的标准做法
• 特定项目的约定（写入 CLAUDE.md）
• 机械性约束（如果可以用正则表达式或验证来强制执行，就将其自动化；把文档留给需要判断的情况）

技能类型

技术

包含具体步骤的方法（condition-based-waiting、root-cause-tracing）

模式

解决问题的思维方式（flatten-with-flags、test-invariants）

参考

API 文档、语法指南、工具文档（办公文档）

目录结构

skills/
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed

扁平命名空间——所有技能都放在一个可搜索的命名空间中

以下内容使用单独的文件：

1. 大型参考资料（100 行以上）——API 文档、完整语法说明
2. 可复用工具——脚本、实用程序、模板

以下内容保留在文档中：

• 原则和概念
• 代码模式（少于 50 行）
• 其他所有内容

SKILL.md 结构

Frontmatter（YAML）：

• 仅支持两个字段：name 和 description
• 总长度最多 1024 个字符
• name：仅使用字母、数字和连字符（不能使用括号或特殊字符）
• description：使用第三人称，仅说明何时使用（而非用途）
  • 以“Use when...”开头，聚焦触发条件
  • 包含具体的症状、情况和上下文
  • 绝不要概述技能的流程或工作流（原因见 CSO 部分）
  • 尽可能控制在 500 个字符以内

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---

# Skill Name

## Overview

What is this? Core principle in 1-2 sentences.

## When to Use

[Small inline flowchart IF decision non-obvious]

Bullet list with SYMPTOMS and use cases
When NOT to use

## Core Pattern (for techniques/patterns)

Before/after code comparison

## Quick Reference

Table or bullets for scanning common operations

## Implementation

Inline code for simple patterns
Link to file for heavy reference or reusable tools

## Common Mistakes

What goes wrong + fixes

## Real-World Impact (optional)

Concrete results

Claude 搜索优化（CSO）

**对发现至关重要：**让未来的 Claude 能找到你的技能

1. 丰富的描述字段

**目的：**Claude 会读取描述，以决定针对给定任务加载哪些技能。确保描述能回答：“我现在应该阅读这项技能吗？”

**格式：**以“Use when...”开头，聚焦触发条件

关键：描述 = 何时使用，而非技能的作用

描述应仅说明触发条件。不要在描述中概述技能的流程或工作流。

**为何重要：**测试发现，如果描述概述了技能的工作流，Claude 可能会照着描述执行，而不阅读完整的技能内容。描述中写着“在任务之间进行代码审查”，会导致 Claude 只进行一次审查，尽管技能的流程图明确显示了两次审查（先检查规范符合性，再检查代码质量）。

当描述改为仅写“在执行包含独立任务的实施计划时使用”（不概述工作流）后，Claude 正确阅读了流程图，并遵循了两阶段审查流程。

**陷阱：**概述工作流的描述会让 Claude 走捷径，跳过技能正文，将其当作文档。

# X BAD: Summarizes workflow - Claude may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks

# X BAD: Too much process detail
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# V GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session

# V GOOD: Triggering conditions only
description: Use when implementing any feature or bugfix, before writing implementation code

内容：

• 使用具体的触发条件、症状和情境，表明适用这项技能
• 描述_问题_（竞争条件、行为不一致），而非_特定语言的症状_（setTimeout、sleep）
• 除非技能本身针对特定技术，否则触发条件应与技术无关
• 如果技能针对特定技术，应在触发条件中明确说明
• 使用第三人称书写（内容会注入系统提示词）
• 绝不要概述技能的流程或工作流

# X BAD: Too abstract, vague, doesn't include when to use
description: For async testing

# X BAD: First person
description: I can help you with async tests when they're flaky

# X BAD: Mentions technology but skill isn't specific to it
description: Use when tests use setTimeout/sleep and are flaky

# V GOOD: Starts with "Use when", describes problem, no workflow
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# V GOOD: Technology-specific skill with explicit trigger
description: Use when using React Router and handling authentication redirects

2. 关键词覆盖

使用 Claude 会搜索的词语：

• 错误消息：“Hook timed out”、“ENOTEMPTY”、“race condition”
• 症状：“flaky”、“hanging”、“zombie”、“pollution”
• 同义词：“timeout/hang/freeze”、“cleanup/teardown/afterEach”
• 工具：实际命令、库名称、文件类型

3. 描述性命名

使用主动语态，以动词开头：

• V creating-skills，而非 skill-creation
• V condition-based-waiting，而非 async-test-helpers

4. 提高令牌效率（关键）

**问题：**入门技能和常被引用的技能会加载到_每一段_对话中。每个令牌都很重要。

目标字数：

• 入门工作流：每项 <150 个单词
• 常加载的技能：总计 <200 个单词
• 其他技能：<500 个单词（仍应简洁）

技巧：

将详细信息移至工具帮助：

# X BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# V GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.

使用交叉引用：

# X BAD: Repeat workflow details

When searching, dispatch subagent with template...
[20 lines of repeated instructions]

# V GOOD: Reference other skill

Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

精简示例：

# X BAD: Verbose example (42 words)

your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

# V GOOD: Minimal example (20 words)

Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent -> synthesis]

消除冗余：

• 不要重复交叉引用的技能中已有的内容
• 不要解释从命令中显而易见的内容
• 不要为同一种模式提供多个示例

验证：

wc -w skills/path/SKILL.md
# getting-started workflows: aim for <150 each
# Other frequently-loaded: aim for <200 total

根据实际操作或核心见解命名：

• V condition-based-waiting > async-test-helpers
• V using-skills，而非 skill-usage
• V flatten-with-flags > data-structure-refactoring
• V root-cause-tracing > debugging-techniques

动名词（-ing）适合描述流程：

• creating-skills、testing-skills、debugging-with-logs
• 采用主动表达，描述你正在采取的行动

4. 交叉引用其他技能

编写引用其他技能的文档时：

仅使用技能名称，并明确标注要求：

• V 正确：**REQUIRED SUB-SKILL:** Use tdd
• V 正确：**REQUIRED BACKGROUND:** You MUST understand debugging
• X 错误：See skills/testing/test-driven-development（不清楚是否为必需）
• X 错误：@skills/testing/test-driven-development/SKILL.md（会强制加载，消耗上下文）

为何不使用 @ 链接：@ 语法会立即强制加载文件，在需要之前就消耗 200k+ 上下文。

流程图用法

digraph when_flowchart {
    "Need to show information?" [shape=diamond];
    "Decision where I might go wrong?" [shape=diamond];
    "Use markdown" [shape=box];
    "Small inline flowchart" [shape=box];

    "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
    "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
    "Decision where I might go wrong?" -> "Use markdown" [label="no"];
}

仅在以下情况下使用流程图：

• 不明显的决策点
• 可能会过早停止的流程循环
• “何时使用 A，何时使用 B”的决策

以下情况绝不要使用流程图：

• 参考资料 -> 表格、列表
• 代码示例 -> Markdown 代码块
• 线性说明 -> 编号列表
• 没有语义意义的标签（step1、helper2）

请参阅 @graphviz-conventions.dot，了解 Graphviz 样式规则。

为你的伙伴呈现可视化内容： 使用此目录中的 render-graphs.js 将技能的流程图渲染为 SVG：

./render-graphs.js ../some-skill           # Each diagram separately
./render-graphs.js ../some-skill --combine # All diagrams in one SVG

代码示例

一个出色的示例胜过许多平庸的示例

选择最相关的语言：

• 测试技术 -> TypeScript/JavaScript
• 系统调试 -> Shell/Python
• 数据处理 -> Python

好的示例：

• 完整且可运行
• 注释完善，说明 WHY
• 来源于真实场景
• 清晰展示模式
• 可直接改编（而非通用模板）

不要：

• 用 5 种以上语言实现
• 创建填空模板
• 编写牵强的示例

你很擅长移植；一个出色的示例就足够了。

文件组织

自包含技能

defense-in-depth/
  SKILL.md    # Everything inline

适用情况：所有内容都能放得下，不需要大量参考资料

配有可复用工具的技能

condition-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt

适用情况：工具是可复用代码，而不只是叙述性内容

配有大量参考资料的技能

pptx/
  SKILL.md       # Overview + workflows
  pptxgenjs.md   # 600 lines API reference
  ooxml.md       # 500 lines XML structure
  scripts/       # Executable tools

适用情况：参考资料过多，不适合内联

铁律（与 TDD 相同）

NO SKILL WITHOUT A FAILING TEST FIRST

这适用于新技能和对现有技能的修改。

先写技能再测试？删除它，从头开始。 修改技能却不测试？同样违规。

没有例外：

• “简单的补充”也不例外
• “只是添加一个章节”也不例外
• “文档更新”也不例外
• 不要把未经测试的改动作为“参考”保留
• 不要在运行测试时“顺便改编”
• 删除就是删除

必读背景： tdd 技能解释了这为何重要。相同原则也适用于文档。

测试所有技能类型

不同类型的技能需要不同的测试方法：

规范执行类技能（规则／要求）

示例： TDD、完成前验证、编码前设计

测试方式：

• 理论问题：他们理解这些规则吗？
• 压力场景：他们在压力下会遵守规则吗？
• 多重压力叠加：时间 + 沉没成本 + 精疲力竭
• 识别合理化借口，并添加明确的反驳

成功标准： Agent 在最大压力下仍遵守规则

技术类技能（操作指南）

示例： condition-based-waiting、root-cause-tracing、defensive-programming

测试方式：

• 应用场景：他们能正确运用该技术吗？
• 变化场景：他们能处理边缘情况吗？
• 信息缺失测试：说明中是否存在缺漏？

成功标准： Agent 能在新场景中成功运用该技术

模式类技能（思维模型）

示例： reducing-complexity、information-hiding 概念

测试方式：

• 识别场景：他们能识别何时适用该模式吗？
• 应用场景：他们能使用该思维模型吗？
• 反例：他们知道何时不应使用吗？

成功标准： Agent 能正确判断何时以及如何应用该模式

参考类技能（文档／API）

示例： API 文档、命令参考、库指南

测试方式：

• 检索场景：他们能找到正确的信息吗？
• 应用场景：他们能正确使用找到的信息吗？
• 缺漏测试：是否涵盖常见用例？

成功标准： Agent 能找到并正确应用参考信息

跳过测试的常见借口

借口	现实
“技能显然很清楚”	对你来说清楚 ≠ 对其他 Agent 来说清楚。测试一下。
“这只是参考资料”	参考资料可能存在遗漏或表述不清的部分。测试检索效果。
“测试太小题大做了”	未经测试的技能总会有问题。务必测试。花 15 分钟测试，可以节省数小时。
“出现问题我再测试”	问题 = Agent 无法使用技能。部署前就要测试。
“测试太麻烦了”	测试比在生产环境中调试有问题的技能省事。
“我确信它没问题”	过度自信必然会带来问题。还是要测试。
“学术评审已经足够”	阅读 ≠ 使用。测试实际应用场景。
“没时间测试”	部署未经测试的技能，之后再修复会浪费更多时间。

这些借口都意味着：部署前要测试。没有例外。

让技能坚决抵制合理化借口

要求严守纪律的技能（如 TDD）需要抵制合理化借口。Agent 很聪明，在压力下会寻找漏洞。

心理学说明： 了解说服技巧为何有效，有助于你系统地运用这些技巧。请参阅 persuasion-principles.md，了解关于权威、承诺、稀缺性、社会认同和群体认同原则的研究基础（Cialdini，2021；Meincke 等，2025）。

明确堵住每一个漏洞

不要只陈述规则，还要明确禁止特定的变通做法：

```markdown Write code before test? Delete it. ``` ```markdown Write code before test? Delete it. Start over.

No exceptions:

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

</Good>

### 回应“精神重于字面”的说法

尽早加入一条基本原则：

```markdown
**Violating the letter of the rules is violating the spirit of the rules.**

这可以杜绝一整类“我是在遵循精神”的合理化借口。

创建合理化借口表

记录基线测试中出现的合理化借口（见下文“测试”部分）。Agent 提出的每个借口都要列入表中：

| Excuse                           | Reality                                                                 |
| -------------------------------- | ----------------------------------------------------------------------- |
| "Too simple to test"             | Simple code breaks. Test takes 30 seconds.                              |
| "I'll test after"                | Tests passing immediately prove nothing.                                |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |

创建危险信号清单

让 Agent 在进行合理化时能轻松自查：

## Red Flags - STOP and Start Over

- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."

**All of these mean: Delete code. Start over with TDD.**

在 CSO 中加入违规症状

在描述中加入即将违反规则时会出现的症状：

description: use when implementing any feature or bugfix, before writing implementation code

技能的 RED-GREEN-REFACTOR 流程

遵循 TDD 循环：

RED：编写失败的测试（基线）

在不提供技能的情况下，使用子 Agent 执行压力场景。记录其确切行为：

• 它们做出了哪些选择？
• 它们使用了哪些合理化借口（逐字记录）？
• 哪些压力引发了违规？

这就是“观察测试失败”——编写技能前，你必须先了解 Agent 在自然情况下会怎么做。

GREEN：编写最精简的技能

编写技能，针对这些特定的合理化借口逐一处理。不要为假设的情况添加额外内容。

在提供技能的情况下运行相同的场景。Agent 此时应该遵守要求。

REFACTOR：堵住漏洞

Agent 找到了新的合理化借口？添加明确的应对措施。重新测试，直到无懈可击。

测试方法： 完整测试方法请参阅 @testing-skills-with-subagents.md：

• 如何编写压力场景
• 压力类型（时间、沉没成本、权威、疲惫）
• 如何系统地堵住漏洞
• 元测试技巧

反模式

X 叙事式示例

“在 2025-10-03 的会话中，我们发现空的 projectDir 导致……” 为什么不好： 过于具体，无法复用

X 多语言稀释

example-js.js、example-py.py、example-go.go 为什么不好： 质量平平，维护负担沉重

X 流程图中嵌入代码

step1 [label="import fs"];
step2 [label="read file"];

为什么不好： 无法复制粘贴，难以阅读

X 泛化标签

helper1、helper2、step3、pattern4 为什么不好： 标签应具有语义

停止：继续下一个技能前

编写任何技能后，都必须停止并完成部署流程。

不要：

• 未逐个测试，就批量创建多个技能
• 当前技能尚未验证，就继续编写下一个技能
• 因为“批量处理效率更高”而跳过测试

以下部署清单适用于每个技能，必须完成。

部署未经测试的技能，就等于部署未经测试的代码。这违反质量标准。

技能创建清单（适配 TDD）

重要：使用 TaskCreate 为以下清单中的每一项创建任务。

RED 阶段——编写失败测试：

• 创建压力场景（针对规范类技能，至少包含 3 种叠加压力）
• 在不使用技能的情况下运行场景——逐字记录基线行为
• 找出合理化说辞和失败模式

GREEN 阶段——编写最精简的技能：

• 名称仅使用字母、数字和连字符（不使用括号或特殊字符）
• YAML frontmatter 仅包含 name 和 description（最多 1024 个字符）
• 描述以 "Use when..." 开头，并包含具体触发条件和症状
• 描述使用第三人称撰写
• 在全文中加入可供搜索的关键词（错误、症状、工具）
• 提供包含核心原则的清晰概述
• 针对 RED 阶段发现的具体基线失败进行处理
• 代码直接内嵌，或链接到单独的文件
• 提供一个出色的示例（不使用多种语言）
• 使用技能运行场景——验证 Agent 现在能遵守要求

REFACTOR 阶段——堵住漏洞：

• 找出测试中出现的新合理化说辞
• 加入明确的反制措施（针对规范类技能）
• 根据所有测试轮次建立合理化说辞对照表
• 创建危险信号清单
• 反复测试，直到无懈可击

质量检查：

• 仅在决策不明显时添加简明流程图
• 提供速查表
• 介绍常见错误
• 不写叙事性故事
• 仅在涉及工具或大量参考资料时添加辅助文件

部署：

• 将技能提交到 git 并推送到你的 fork（如果已配置）
• 考虑通过 PR 贡献回去（如果适用范围广）

发现工作流

Claude 之后会这样找到你的技能：

1. 遇到问题（“测试不稳定”）
2. 找到 SKILL（描述与问题匹配）
3. 浏览概述（这是否相关？）
4. 阅读模式（速查表）
5. 查看示例（仅在实施时）

针对这个流程进行优化——尽早且反复加入可搜索的术语。

核心要点

创建技能就是对流程文档进行 TDD。

同一条铁律：没有先通过失败测试，就不编写技能。 同一套循环：RED（基线）-> GREEN（编写技能）-> REFACTOR（堵住漏洞）。 同样的好处：质量更高、意外更少、结果无懈可击。

如果你对代码使用 TDD，也要对技能使用 TDD。这是将同一套规范应用于文档。

写作风格指南

编写技能内容时，请遵循以下文案指南，确保表达清晰直接：

语气与风格

• 像日常说话一样写作。避免企业行话和营销套话。
• 自信、直接地表达。避免使用“我觉得”“也许”或“可能”等弱化语气的措辞。
• 使用主动语态，而非被动语态。
• 使用正向措辞——说清楚某事是什么，而不是它不是什么。
• 面向外部受众时，多用“你”，少用“我们”。
• 使用“I'll”“won't”和“can't”等缩略形式，让语气更亲切。

具体性与证据

• 用具体事实和数据代替含糊的溢美之词。
• 用具体示例或指标支持论断。
• 多强调客户和社区成员，少强调公司成就。
• 使用贴近实际产品的示例，而不是在代码中使用 foo/bar/baz。
• 让内容具体、直观且可验证。

标题创作

• 在标题中作出承诺，让读者点击前就清楚能获得什么。
• 关注受众持有的争议观点，并用数据支撑（谨慎使用，避免标题党）。
• 分享独特且有帮助的内容，让读者在生活中真正重要的方面有所提升。
• 避免使用“My Thoughts On XYZ”这类模糊的标题。标题应表达观点，或陈述值得分享的事实。
• 先写占位标题，完成内容后，再花时间反复打磨标题。

禁用词（替换为）

• a bit -> 删除
• a little -> 删除
• actually/actual -> 删除
• agile -> 删除
• arguably -> 删除
• assistance -> “help”
• attempt -> “try”
• battle tested -> 删除
• best practices -> “proven approaches”
• blazing fast/lightning fast -> “build XX% faster”
• business logic -> 删除
• cognitive load -> 删除
• commence -> “start”
• delve -> “go into”
• disrupt/disruptive -> 删除
• facilitate -> “help” 或 “ease”
• game-changing -> 具体说明好处
• great -> 删除或具体说明
• implement -> “do”
• individual -> “man” 或 “woman”
• initial -> “first”
• innovative -> 删除
• just -> 删除
• leverage -> “use”
• mission-critical -> “important”
• modern/modernized -> 删除
• numerous -> “many”
• out of the box -> 删除
• performant -> “fast and reliable”
• pretty/quite/rather/really/very -> 删除
• referred to as -> “called”
• remainder -> “rest”
• robust -> “strong”
• seamless/seamlessly -> “automatic”
• sufficient -> “enough”
• that -> 视语境酌情删除
• thing -> 换成具体表述
• utilize -> “use”
• webinar -> “online event”

禁用短语

• I think/I believe/we believe -> 直接陈述
• it seems -> 删除
• sort of/kind of -> 删除
• pretty much -> 删除
• a lot/a little -> 换成具体表述
• By developers, for developers -> 删除
• We can't wait to see what you'll build -> 删除
• We obsess over ___ -> 删除
• The future of ___ -> 删除
• We're excited -> “We look forward”
• Today, we're excited to -> 删除

避免大模型写作模式

• 将破折号（—）替换为分号、逗号或句号。
• 避免以“Great question!”、“You're right!”或“Let me help you.”开头。
• 不要使用“Let's dive into...”这类表达。
• 避免使用“In today's fast-paced digital world”或“In the ever-evolving landscape of.”这类陈词滥调式开场。
• 避免使用“it's not just [x], it's [y].”这类表达。
• 避免使用“As an AI”或“I'm here to help you with.”这类自我指涉的免责声明。
• 不要使用“In conclusion,”、“Overall,”或“To summarize.”这类高中作文式结尾。
• 能用项目符号时，避免使用编号列表。
• 不要以“Hope this helps!”或类似表达结尾。
• 避免过度使用“Furthermore,”、“Additionally,”或“Moreover.”等过渡词。
• 用直接陈述替代“In conclusion”。
• 避免使用表示不确定的词语：“might”、“perhaps”、“potentially”，除非确实存在不确定性。
• 不要叠加表示不确定的短语，例如：“may potentially”、“it's important to note that.”
• 不要让段落或列表过于工整对称，也不要让各项都以“Firstly... Secondly...”开头。
• 避免标题式大写；标题优先使用句式大小写。
• 复制粘贴时清除 Unicode 格式字符：智能引号（"）、破折号、不换行空格。
• 使用 `` 代替 ''。
• 删除没有实际来源的空引文占位符，例如“[1]”。

标点和格式

• 始终统一使用牛津逗号。
• 少用感叹号。
• 句子可以用“But”和“And”开头，但不要过度使用。
• 尽量使用句号而非逗号，让表达更清晰。

铁律

1. 始终遵循 TDD：先建立 RED 基线（记录不使用该技能时的当前行为），再编写任何技能
2. 绝不在技能描述中包含实现细节或“如何做”的说明——描述只能包含触发条件
3. 始终在 REFACTOR 阶段堵住新出现的合理化说辞留下的漏洞，然后再将技能标记为完成
4. 绝不在未通过验证器检查（最低要求为 8/0/3）前发布技能
5. 始终使用简洁、主动的表达；在技能内容中消除被动句式和含糊措辞

反模式

反模式	失败原因	正确做法
跳过 RED 基线	没有基线就无法衡量改进	先在不使用技能的情况下运行测试，并记录失败情况
在描述中包含实现细节	会在错误的条件下触发，并混淆路由	描述仅限触发条件
在技能内容中使用委婉、含糊的措辞	含糊的规则无法改变 Agent 的行为	使用带有具体标准的命令式 始终/绝不
没有堵住漏洞的 REFACTOR 阶段	Agent 会发现边缘情况，并为其找借口	观察失败模式后迭代技能
未经验证器检查便发布	集成缺口无法被发现	运行 validate-integration.cjs，目标为 8/0/3

记忆协议（必须遵守）

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 作出决策 -> .claude/context/memory/decisions.md

假设工作会中断：如果没有记录在记忆中，就等于没有发生。