Menu
在编写 skill 内容、验证 skill 是否有效、或需要用 TDD 方法测试 skill 能否被正确遵守时使用。
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 目录（运行 init_skill.py）、打包 skill（运行 package_skill.py）、或需要了解 skill 结构规范时使用。
Frontend Master - 大师级前端页面开发。智能分析项目技术栈，生成独特设计美感的 UI，避免'AI审美'。自动持久化设计规范，保持项目一致性。整合 Frontend-Design 设计哲学 + UI-UX Pro Max 设计数据库。触发词: 前端、页面、组件、UI、登录页、落地页、dashboard、表单、卡片、导航栏。
你必须在任何创意工作之前使用：新功能、组件搭建、添加能力或修改行为。先通过对话澄清用户意图、需求与设计，再进入实现。
当你面对 2 个以上彼此独立的任务（无共享状态、无顺序依赖）时使用：为每个独立问题域派发一个 agent 并行推进。
当你已经有一份书面的 implementation plan，需要在独立 session 中按批执行并在批次间做 review checkpoint 时使用。
当实现已完成、测试已通过，需要决定如何集成这次工作时使用：通过结构化选项引导 merge/PR/保留/丢弃，并在选择后完成收尾与清理。
| name | writing-skills |
| description | 在编写 skill 内容、验证 skill 是否有效、或需要用 TDD 方法测试 skill 能否被正确遵守时使用。 |
写 skills = 把 Test-Driven Development（TDD）应用到流程文档。
个人 skills 通常放在 agent 对应目录（Claude Code：~/.claude/skills；Codex：~/.codex/skills）。
你要写“测试用例”（用 subagent 做压力场景），先观察在没有 skill 时它会失败（baseline 行为），再写 skill（文档）让它通过（agent 遵守），最后 refactor（堵漏洞）。
核心原则： 如果你没亲眼见过 agent 在“没有 skill”时会违反规则，你就不知道这个 skill 是否真的教对了。
必备背景： 使用本 skill 前，必须理解 superpowers:test-driven-development。它定义了 RED-GREEN-REFACTOR 周期；本 skill 是把同样周期迁移到文档上。
官方参考： Anthropic 的 skill 编写最佳实践见 anthropic-best-practices.md（补充模式与指南，配合本 skill 的 TDD 思路使用）。
skill 是经过验证的 technique/pattern/tool 的参考指南，帮助未来的 Claude 实例找到并应用有效方法。
Skills 是： 可复用技巧、pattern、工具、reference guide
Skills 不是： “我当时怎么解决某个问题”的一次性故事
| TDD 概念 | Skill 创建中的含义 |
|---|---|
| Test case | 用 subagent 跑压力场景（pressure scenario） |
| Production code | skill 文档（SKILL.md） |
| Test fails（RED） | 没 skill 时 agent 会违反规则（baseline） |
| Test passes（GREEN） | 有 skill 时 agent 能遵守规则 |
| Refactor | 在保持遵守的前提下堵漏洞 |
| Write test first | 写 skill 之前先跑 baseline 场景 |
| Watch it fail | 记录 agent 的原话与自我合理化方式 |
| Minimal code | 只写足以覆盖这些违规点的 skill 内容 |
| Watch it pass | 验证 agent 现在会遵守 |
| Refactor cycle | 发现新借口 → 补规则 → 再验证 |
整个 skill 创建流程都应遵循 RED-GREEN-REFACTOR。
应该写：
不该写：
可执行的方法与步骤（例如 condition-based-waiting、root-cause-tracing）
思考问题的方式（例如 flatten-with-flags、test-invariants）
API 文档、语法指南、工具说明（例如 office docs）
skills/
skill-name/
SKILL.md # 主文档（必需）
supporting-file.* # 仅在确有需要时添加
Flat namespace： 所有 skills 在一个可搜索命名空间中。
拆到独立文件的情况：
适合放在 SKILL.md 内的：
SKILL.md 结构Frontmatter（YAML）：
name 与 description 来做触发与检索name：只用字母、数字、连字符（hyphens）description：第三人称，描述“何时使用”（when to use），而不是“怎么做”（how）
---
name: skill-name-with-hyphens
description: Use when [具体触发条件与症状]
---
# Skill Name
## Overview
这是什么？用 1–2 句话写核心原则。
## When to Use
[如果决策不明显，可给一个小的 inline flowchart]
用 bullet 列出症状与用例
以及何时“不该用”
## Core Pattern（适用于 technique/pattern）
before/after 的代码对比
## Quick Reference
表格或要点，方便快速扫
## Implementation
简单 pattern 可以 inline
重 reference 或可复用工具则链接到独立文件
## Common Mistakes
常见踩坑 + 修正
## Real-World Impact（可选）
具体成效
可发现性至关重要： 未来的 Claude 需要能“搜到”你的 skill。
description目的： Claude 会用 description 来决定某个任务是否要加载这个 skill。它必须回答：“我现在该读这个 skill 吗？”
格式： 用 “Use when …” 开头，聚焦触发条件。
关键：description = When to Use，不是 What/How
description 只能描述触发条件，不要总结 skill 的 workflow。
为什么： 实测发现，如果 description 里总结了 workflow，Claude 可能只按 description 行事而跳过正文。比如 description 写了 “code review between tasks”，Claude 可能只做一次 review；但正文 flowchart 明确要求两次 review（spec compliance → code quality）。当 description 改成只写触发条件（不总结流程）后，Claude 才会去读 flowchart 并正确执行两阶段 review。
陷阱： workflow 摘要会变成 Claude 的捷径，导致正文被跳过。
# ❌ Bad：总结 workflow（Claude 可能不读正文）
description: Use when 执行计划时，按 task 派发 subagent，并在 tasks 之间做 code review
# ❌ Bad：流程细节太多
description: Use for TDD - 先写测试，看它失败，再写最小实现，最后重构
# ✅ Good：只写触发条件，不总结流程
description: Use when 在当前 session 执行包含多个独立 tasks 的 implementation plan
# ✅ Good：只写触发条件
description: Use when 实现任何 feature 或 bugfix，在写实现代码之前
内容建议：
# ❌ Bad：太抽象
description: 用于 async 测试
# ❌ Bad：第一人称
description: 我可以在 async tests flaky 时帮你修
# ❌ Bad：提到技术细节但 skill 并不限定它
description: Use when tests 使用 setTimeout/sleep 且 flaky
# ✅ Good：以问题为中心，不总结流程
description: Use when tests 存在 race conditions、timing dependencies，或 pass/fail 不稳定
# ✅ Good：技术栈限定的 skill
description: Use when 使用 React Router 且需要处理 authentication redirects
写 Claude 会用来搜索的词：
Hook timed out、ENOTEMPTY、race conditionflaky、hanging、zombie、pollutiontimeout/hang/freeze、cleanup/teardown/afterEach用主动语态、动词优先：
creating-skills 而不是 skill-creationcondition-based-waiting 而不是 async-test-helpers问题： getting-started 或高频 skills 会在每次对话都加载。每个 token 都要省。
目标字数：
技巧：
把细节挪到工具帮助里：
# ❌ Bad：在 SKILL.md 里列出所有 flags
search-conversations 支持 --text、--both、--after DATE、--before DATE、--limit N
# ✅ Good：让用户/agent 去看 --help
search-conversations 支持多种模式与筛选；详情请运行 --help。
用 cross-reference：
# ❌ Bad：重复写 workflow 细节
搜索时，用模板派发 subagent……
[重复 20 行]
# ✅ Good：引用其他 skill
永远使用 subagents。**REQUIRED:** 使用 [other-skill-name] 作为 workflow。
压缩示例：
# ❌ Bad：啰嗦示例
伙伴：“我们之前怎么处理 React Router 的鉴权错误？”
你：我会去搜索历史对话……
[再写一堆派发细节]
# ✅ Good：最小示例
伙伴：“我们之前怎么处理 auth errors？”
你：我去搜一下……
[派发 subagent → 汇总]
消除冗余：
验证字数：
wc -w skills/path/SKILL.md
当文档需要引用其他 skills：
只写 skill 名，并标注明确的强制程度：
**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debuggingSee skills/testing/test-driven-development（不清晰是否必须）@skills/testing/test-driven-development/SKILL.md（强制加载，烧 context）为什么不要用 @ 链接： @ 会立刻 force-load 文件，可能在还没需要时就消耗大量 context。
digraph when_flowchart {
"需要展示信息？" [shape=diamond];
"这里是我可能会做错的决策点？" [shape=diamond];
"用 markdown" [shape=box];
"用小的 inline flowchart" [shape=box];
"需要展示信息？" -> "这里是我可能会做错的决策点？" [label="是"];
"这里是我可能会做错的决策点？" -> "用小的 inline flowchart" [label="是"];
"这里是我可能会做错的决策点？" -> "用 markdown" [label="否"];
}
只在这些情况下用 flowchart：
不要用 flowchart：
graphviz 约定见 graphviz-conventions.dot。
为 human partner 渲染 SVG：用本目录的 render-graphs.js：
./render-graphs.js ../some-skill # 每个图单独渲染
./render-graphs.js ../some-skill --combine # 合并成一个 SVG
一个优秀示例胜过一堆一般示例。
选择最相关的语言：
好的示例应当：
不要：
你很擅长迁移——一个高质量示例足够。
defense-in-depth/
SKILL.md # 全部 inline
适用：内容都能装下、不需要重 reference
condition-based-waiting/
SKILL.md # Overview + patterns
example.ts # 可直接复用/改造的 helpers
适用：存在可复用代码工具
pptx/
SKILL.md # Overview + workflows
pptxgenjs.md # 600 行 API reference
ooxml.md # 500 行 XML 结构
scripts/ # 可执行工具
适用：reference 过大，不适合 inline
没有先失败的测试，就不能写/改 skill
适用于新建 skill，也适用于编辑已有 skill。
先写 skill 再测试？删掉，重来。
改 skill 不测试？同样违规。
没有例外：
必备背景： 见 superpowers:test-driven-development，同样原则适用于文档。
不同类型需要不同测试策略：
示例：TDD、verification-before-completion、designing-before-coding
测试方式：
成功标准： 在最大压力下仍能遵守规则
示例：condition-based-waiting、root-cause-tracing、defensive-programming
测试方式：
成功标准： 能在新场景中正确应用该 technique
示例：reducing-complexity、information-hiding
测试方式：
成功标准： 正确识别并正确应用
示例：API 文档、命令参考、库指南
测试方式：
成功标准： 能检索到并正确应用 reference 信息
| 借口 | 现实 |
|---|---|
| “这个 skill 这么清晰” | 你觉得清晰 ≠ 其他 agent 觉得清晰。测试它。 |
| “它只是 reference” | reference 也会缺口/含糊；要测检索与应用。 |
| “测试是 overkill” | 未测试的 skill 总会出问题；15 分钟测试能省数小时。 |
| “问题出现再测” | 出问题=agent 用不了；要在部署前测试。 |
| “太麻烦了” | 比线上 debug 一个烂 skill 更不麻烦。 |
| “我很有信心” | 过度自信必翻车；照样要测。 |
| “读一遍就够了” | 阅读 ≠ 使用；要测应用场景。 |
| “没时间测试” | 部署未测试的 skill 只会让你之后花更多时间补救。 |
看到这些就意味着：部署前必须测试。没有例外。
规则类 skill（如 TDD）必须能抵抗 rationalization。agent 很聪明，在压力下会找漏洞。
心理学提示：理解 WHY 某些说服技巧有效能让你更系统地应用。研究基础见 persuasion-principles.md（Cialdini, 2021；Meincke et al., 2025）。
不要只写规则，也要禁止常见“绕法”：
```markdown 先写代码再写测试？删掉。 ``` ```markdown 先写代码再写测试？删掉，重来。No exceptions:
</Good>
### 预防 “Spirit vs Letter” 辩解
尽早加入基础原则：
```markdown
**只遵守字面、不遵守精神，就是在违反规则。**
这能直接切断一大类“我是在遵守精神”的辩解。
把 baseline 测试里出现的借口收集成表；agent 的每个借口都应该被记录并反制：
| 借口 | 现实 |
|------|------|
| “太简单了不值得测” | 简单代码也会坏；写个测试 30 秒。 |
| “我之后再测” | 立刻通过的测试证明不了任何事。 |
| “事后测试也一样” | 事后：what does this do；事前：what should this do。 |
让 agent 能快速自检是否在 rationalize：
## Red Flags - STOP and Start Over
- 先写代码再写测试
- “我已经手测过了”
- “事后测试也能达到同样目的”
- “重要的是精神不是仪式”
- “这次情况不同，因为……”
**出现这些就意味着：删掉代码，用 TDD 重来。**
在 description 里加入“你快要违规了”的症状提示（仅触发条件，不写 workflow）：
description: use when 实现任何 feature 或 bugfix，在写实现代码之前
遵循同样 TDD 周期：
在没有该 skill的情况下跑压力场景，记录 agent 的真实行为：
这就是 “watch the test fail”：你必须先看到 agent 的自然行为，再写 skill。
只写足以覆盖这些具体违规点的内容，不要为假设场景堆料。
然后在有 skill的情况下跑同样场景，验证 agent 现在能遵守。
agent 找到新借口？加明确反制，再测，直到足够稳。
完整测试方法见 @testing-skills-with-subagents.md：
“在 2025-10-03 的 session 里我们发现空 projectDir …” 问题： 过于具体，不可复用
example-js.js、example-py.py、example-go.go
问题： 平庸质量 + 维护负担
step1 [label="import fs"];
step2 [label="read file"];
问题： 不可复制粘贴，且难读
helper1、helper2、step3
问题： label 应该有语义
写完任何 skill 后，你必须停下并完成部署流程。
不要：
下方的部署 checklist 对每个 skill都强制执行。
部署未测试的 skill = 部署未测试的代码，违反质量标准。
重要：用 TodoWrite 为下列每项创建 todo。
RED Phase：写 failing test
GREEN Phase：写最小 skill
name 只用字母/数字/连字符（无括号/特殊字符）description 以 “Use when …” 开头，包含具体 triggers/symptomsdescription 用第三人称REFACTOR Phase：堵漏洞
质量检查：
Deployment：
未来的 Claude 通常这样找到你的 skill：
按这个流程优化：可搜索的词要早出现、常出现。
写 skills 就是对流程文档做 TDD。
同样 Iron Law：没有 failing test 就不能写 skill。
同样周期：RED（baseline）→ GREEN（写 skill）→ REFACTOR（堵洞）。
同样收益：更高质量、更少意外、更不容易被钻空子。
你对代码遵循 TDD，就也要对 skills 遵循 TDD——纪律是同一套。