Menu
当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
在开始任何对话时使用——确立如何查找和使用技能，要求在任何响应（包括澄清性问题）之前调用 Skill 工具
在任何创造性工作之前必须使用此技能——创建功能、构建组件、添加功能或修改行为。在实现之前先探索用户意图、需求和设计。
中文 review 沟通参考——话术模板、分级标注（必须修复/建议修改/仅供参考）、国内团队常见反模式应对。
中文 commit 与 changelog 配置参考——Conventional Commits 中文适配、commitlint/husky/commitizen 中文模板、conventional-changelog 中文配置。仅在用户显式 /chinese-commit-conventions 时调用，不要根据上下文自动触发。
中文文档排版参考——中英文空格、全半角标点、术语保留、链接格式、中文文案排版指北约定。仅在用户显式 /chinese-documentation 时调用，不要根据上下文自动触发。
国内 Git 平台配置参考——Gitee、Coding.net、极狐 GitLab、CNB 的 SSH/HTTPS/凭据/CI 接入差异与镜像同步配置。仅在用户显式 /chinese-git-workflow 时调用，不要根据上下文自动触发。
| name | writing-skills |
| description | 当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用 |
编写技能就是将测试驱动开发应用于流程文档。
你编写测试用例（带子代理的压力场景），观察它们失败（基线行为），编写技能（文档），观察测试通过（智能体遵守规则），然后重构（堵住漏洞）。
核心原则： 如果你没有观察到智能体在没有该技能时失败，你就不知道这个技能是否教了正确的东西。
必需背景： test-driven-development。该技能定义了基本的红-绿-重构循环，本技能将其适配到文档编写中。
技能是经过验证的技术、模式或工具的参考指南。技能帮助未来的 AI 实例找到并应用有效的方法。
创建条件：
不要创建：
| 类型 | 说明 | 示例 |
|---|---|---|
| 技术类 | 有具体步骤的方法 | condition-based-waiting、root-cause-tracing |
| 模式类 | 思考问题的方式 | flatten-with-flags、test-invariants |
| 参考类 | API 文档、语法指南 | office docs、命令参考 |
skills/
skill-name/
SKILL.md # 主参考文档（必需）
supporting-file.* # 仅在需要时
分离文件的情况：
保持内联： 原则、概念、代码模式（< 50 行）
Frontmatter（YAML）：
name、description（最多 1024 字符）name：只使用字母、数字和连字符description：第三人称，仅描述何时使用（不是做什么）
---
name: Skill-Name-With-Hyphens
description: Use when [具体的触发条件和症状]
---
# 技能名称
## 概述
1-2 句话说明核心原则。
## 何时使用
症状和用例的要点列表；不适用的场景
## 核心模式
前后代码对比
## 快速参考
常见操作的表格或要点
## 实现
简单模式内联；大量参考链接到文件
## 常见错误
常见问题 + 修复方法
关键：描述 = 何时使用，不是技能做什么。 当描述总结工作流时，AI 可能跟随描述而非阅读完整内容。
# 错误：总结了工作流
description: Use for TDD - write test first, watch it fail...
# 正确：只有触发条件
description: Use when implementing any feature or bugfix, before writing implementation code
使用 AI 会搜索的词语：错误信息（"Hook timed out"）、症状（"flaky"、"hanging"）、同义词、工具名称。
动词优先，主动语态：
creating-skills、condition-based-waitingskill-creation、async-test-helpers目标字数：
技巧：
--help仅使用技能名称，带明确必需标记：
**必需：** 使用 test-driven-development@skills/testing/test-driven-development/SKILL.md（强制加载，浪费上下文）仅在以下情况使用流程图：
绝不使用流程图用于： 参考资料、代码示例、线性指令、无语义意义的标签
一个优秀的示例胜过多个平庸的。
选择最相关的语言：测试技术 → TypeScript/JavaScript；系统调试 → Shell/Python；数据处理 → Python。
好的示例： 完整可运行、注释良好、来自真实场景、清晰展示模式。
不要： 用 5 种以上语言实现、创建填空模板、写人为构造的示例。
| 类型 | 结构 | 适用场景 |
|---|---|---|
| 自包含 | defense-in-depth/SKILL.md | 所有内容都能放下 |
| 带工具 | skill/SKILL.md + example.ts | 可复用的代码 |
| 带参考 | skill/SKILL.md + api.md + scripts/ | 参考资料太多 |
没有失败的测试就不写技能
这适用于新技能和对现有技能的编辑。先写技能再测试？删掉它。重新开始。编辑技能不测试？同样违规。
无例外： 不适用于"简单的添加"、"只是加一个章节"、"文档更新"。不要保留未测试的更改作为"参考"。删除就是删除。
必需背景： test-driven-development 技能解释了为什么这很重要。
| 类型 | 示例 | 测试方式 | 成功标准 |
|---|---|---|---|
| 纪律执行类 | TDD、完成前验证 | 学术性问题、压力场景、多重压力组合 | 最大压力下遵循规则 |
| 技术类 | condition-based-waiting | 应用场景、变体场景、缺失信息测试 | 成功应用于新场景 |
| 模式类 | reducing-complexity | 识别场景、应用场景、反例 | 正确识别何时/如何应用 |
| 参考类 | API 文档 | 检索场景、应用场景、覆盖测试 | 找到并正确应用参考信息 |
执行纪律的技能需要抵抗合理化。智能体在压力下会找到漏洞。
不要只是陈述规则——禁止具体的变通方法：
# 差
先写代码再写测试？删掉它。
# 好
先写代码再写测试？删掉它。重新开始。
**无例外：**
- 不要保留作为"参考"
- 不要在写测试时"调整"它
- 删除就是删除
在前面加入基础原则：
**违反规则的字面意思就是违反规则的精神。**
从基线测试中捕获智能体使用的每个借口：
| 借口 | 现实 |
|------|------|
| "太简单不值得测试" | 简单的代码也会出错。测试只需 30 秒。 |
| "我后面再测试" | 测试立即通过什么也证明不了。 |
## 红线 - 停下来重新开始
- 先写代码再写测试
- "我已经手动测试过了"
- "后写测试效果一样"
- "重要的是精神不是仪式"
- "这个情况不同，因为……"
**以上所有都意味着：删除代码。用 TDD 重新开始。**
在没有技能的情况下运行压力场景。逐字记录行为：它们做了什么选择？使用了什么合理化借口？哪些压力触发了违规？
这就是"观察测试失败"——在编写技能之前你必须看到智能体自然会怎么做。
编写针对那些具体合理化借口的技能。不要为假设情况添加额外内容。用技能运行相同的场景，智能体应该现在遵守。
智能体找到了新的合理化借口？添加明确的反驳。重新测试直到无懈可击。
测试方法论： 参见 testing-skills-with-subagents.md 了解完整的测试方法。
| 反模式 | 说明 | 为什么不好 |
|---|---|---|
| 叙事式示例 | "在 2025-10-03 的会话中，我们发现……" | 太具体，不可复用 |
| 多语言稀释 | example-js.js、example-py.py、example-go.go | 质量平庸，维护负担重 |
| 流程图中的代码 | step1 [label="import fs"] | 无法复制粘贴 |
| 通用标签 | helper1、helper2、step3 | 标签应有语义意义 |
编写任何技能后，你必须停下来完成部署流程。
不要批量创建多个技能而不逐个测试。不要因"批量处理更高效"就跳过测试。部署未测试的技能 = 部署未测试的代码。
红色阶段 - 编写失败的测试：
绿色阶段 - 编写最小技能：
name 和 description（最多 1024 字符）重构阶段 - 堵住漏洞：
质量检查：
部署：
未来的 AI 找到技能的流程：遇到问题 → 找到技能（描述匹配）→ 浏览概述 → 阅读模式（快速参考表）→ 加载示例（仅在实现时）。
为此流程优化 - 把可搜索的术语放在前面和各处。
创建技能就是流程文档的 TDD。
同样的铁律：没有失败的测试就不写技能。 同样的循环：红（基线）→ 绿（写技能）→ 重构（堵漏洞）。 同样的好处：更高的质量、更少的意外、无懈可击的结果。