القائمة
当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف 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。
同样的铁律：没有失败的测试就不写技能。 同样的循环：红（基线）→ 绿（写技能）→ 重构（堵漏洞）。 同样的好处：更高的质量、更少的意外、无懈可击的结果。