Menü
在编写 skill 内容、验证 skill 是否有效、或需要用 TDD 方法测试 skill 能否被正确遵守时使用。
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Basierend auf der SOC-Berufsklassifikation
初始化新 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——纪律是同一套。