菜单
Use when creating new skills, editing existing skills, or verifying skills work before deployment
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | writing-skills |
| description | Use when creating new skills, editing existing skills, or verifying skills work before deployment |
Writing skills IS Test-Driven Development applied to process documentation.
Personal skills live in agent-specific directories (~/.claude/skills for Claude Code, ~/.agents/skills/ for Codex)
汝書測例（以 subagent 之壓力情境），觀其敗（baseline 行為），書 skill（文件），觀測過（agent 遵），重構（閉 loophole）。
核心原則： 未觀 agent 無 skill 而敗，則不知其 skill 教真事否。
REQUIRED BACKGROUND： 必先明 superpowers:test-driven-development。彼 skill 定 RED-GREEN-REFACTOR 之基環。此 skill 將 TDD 適於文件。
Official guidance： Anthropic 官之 skill authoring best practices 見 anthropic-best-practices.md。此補以式與指引，配本 skill 之 TDD 法。
skill 乃已證技、式、工具之指南。助未來 Claude 尋且用有效法。
Skills 為： 可重用技、式、工具、指南
Skills 非： 汝某次解題之敘事
| TDD Concept | Skill Creation |
|---|---|
| Test case | 以 subagent 之壓力情境 |
| Production code | Skill document (SKILL.md) |
| Test fails (RED) | Agent 無 skill 時違律（baseline） |
| Test passes (GREEN) | Agent 有 skill 則遵 |
| Refactor | 閉 loophole 而保遵 |
| 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 docs、syntax 指、工具文件（office docs）
skills/
skill-name/
SKILL.md # Main reference (required)
supporting-file.* # Only if needed
Flat namespace - 所有 skill 在一可搜 namespace
獨檔用於：
保 inline：
Frontmatter (YAML)：
name + description（見 agentskills.io/specification 其餘）name：僅字母、數字、連字（無括號、特殊字）description：第三人稱，僅述何時用（非述何為）
---
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 須尋得汝 skill
用意： Claude 讀 description 以決所載 skill。令其答：「吾今當讀此 skill 否？」
形： 以 "Use when..." 起，專注觸發條件
CRITICAL：Description = When to Use，非 What the Skill Does
Description 僅述觸發條件。勿 摘 skill 之 process 或 workflow。
何以重要： 測揭：description 摘 workflow 時，Claude 或依 description 行而不讀 skill 全文。一 description 言 "code review between tasks" 致 Claude 僅作一審，雖 skill flowchart 明示二審。
Description 改為僅 "Use when executing implementation plans with independent tasks"（無 workflow 摘）後，Claude 正確讀 flowchart 並遵二段審。
陷阱： 摘 workflow 之 description 造 Claude 必取之捷徑。Skill body 成 Claude 跳之文件。
# ❌ 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
# ❌ BAD: Too much process detail
description: Use for TDD - write test first, watch it fail, write minimal code, refactor
# ✅ GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session
# ✅ GOOD: Triggering conditions only
description: Use when implementing any feature or bugfix, before writing implementation code
Content：
# ❌ BAD: Too abstract, vague, doesn't include when to use
description: For async testing
# ❌ BAD: First person
description: I can help you with async tests when they're flaky
# ❌ BAD: Mentions technology but skill isn't specific to it
description: Use when tests use setTimeout/sleep and are flaky
# ✅ GOOD: Starts with "Use when", describes problem, no workflow
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
# ✅ GOOD: Technology-specific skill with explicit trigger
description: Use when using React Router and handling authentication redirects
用 Claude 會搜之詞：
用主動語、動詞先：
creating-skills 非 skill-creationcondition-based-waiting 非 async-test-helpers題： getting-started 與常引 skill 載入每 conversation。每 token 皆值。
字數目標：
技：
移細節入 tool help：
# ❌ BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
# ✅ GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.
用 cross-reference：
# ❌ BAD: Repeat workflow details
When searching, dispatch subagent with template...
[20 lines of repeated instructions]
# ✅ GOOD: Reference other skill
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
壓縮例：
# ❌ 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"]
# ✅ 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
按所作或核見名：
condition-based-waiting > async-test-helpersusing-skills 非 skill-usageflatten-with-flags > data-structure-refactoringroot-cause-tracing > debugging-techniques動名（-ing）合 process：
creating-skills、testing-skills、debugging-with-logs書引他 skill 之文件時：
僅用 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）何以無 @ links： @ syntax 立載檔，耗 200k+ context 於未需前。
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"];
}
Flowchart 僅用於：
絕不用於：
見 @graphviz-conventions.dot 以察 graphviz style。
為 your human partner 視覺化： 用本目錄之 render-graphs.js 將 skill flowchart 繪 SVG：
./render-graphs.js ../some-skill # Each diagram separately
./render-graphs.js ../some-skill --combine # All diagrams in one SVG
一佳例勝多庸
擇最適語：
佳例：
勿：
汝善移植——一佳例足。
defense-in-depth/
SKILL.md # Everything inline
當：內容全可 inline，無須重參考
condition-based-waiting/
SKILL.md # Overview + patterns
example.ts # Working helpers to adapt
當：tool 為可重用碼，非僅敘事
pptx/
SKILL.md # Overview + workflows
pptxgenjs.md # 600 lines API reference
ooxml.md # 500 lines XML structure
scripts/ # Executable tools
當：參考料過大不可 inline
NO SKILL WITHOUT A FAILING TEST FIRST
適於新 skill 與既 skill 之 edit。
書 skill 前未測？ 刪之。重起。 改 skill 前未測？ 同違。
無例外：
REQUIRED BACKGROUND： superpowers:test-driven-development 釋何以重要。同原則適於文件。
異 skill 型需異測法：
例： TDD、verification-before-completion、designing-before-coding
測以：
成之準： Agent 於極壓下遵律
例： condition-based-waiting、root-cause-tracing、defensive-programming
測以：
成之準： Agent 於新情境成用技
例： reducing-complexity、information-hiding concepts
測以：
成之準： Agent 正辨何時/如何用式
例： API 文件、令參考、library 指
測以：
成之準： Agent 尋且正用參考訊
| Excuse | Reality |
|---|---|
| 「Skill 明顯清」 | 於汝清 ≠ 於他 agent 清。測之。 |
| 「僅為參考」 | 參考亦有缺、模糊。測取回。 |
| 「測太過」 | 未測 skill 恆有疾。15 分測省數時。 |
| 「疾現則測」 | 疾 = agent 不能用。部署前測。 |
| 「測太煩」 | 測煩於日後 debug 壞 skill。 |
| 「吾信佳」 | 過信必生疾。仍測。 |
| 「學術審足」 | 讀 ≠ 用。測應用情境。 |
| 「無暇測」 | 部署未測省時少於日後修。 |
皆意：部署前測。無例外。
強律之 skill（如 TDD）須抗託辭。Agent 智，壓下必尋 loophole。
心理註： 明說服技何以有效助汝系統化用之。見 persuasion-principles.md 以察研究基（Cialdini, 2021；Meincke et al., 2025）：authority、commitment、scarcity、social proof、unity。
勿僅述律——明禁特解：
```markdown Write code before test? Delete it. ``` ```markdown Write code before test? Delete it. Start over.No exceptions:
</Good>
### Address "Spirit vs Letter" Arguments
早加根原：
```markdown
**Violating the letter of the rules is violating the spirit of the rules.**
此斷「吾遵其意」類託辭。
自 baseline 測捕託辭（見下 Testing 節）。所有託辭入表：
| 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.**
加於 description：將違律之症狀：
description: use when implementing any feature or bugfix, before writing implementation code
遵 TDD 環：
以 subagent 跑壓力情境無 skill。錄確切行為：
此即「觀測敗」——書 skill 前必先見 agent 之自然行為。
書 skill 針對彼等託辭。勿為假設情況加多餘。
同情境加 skill 再跑。Agent 今應遵。
Agent 尋新託辭？ 加明抗。再測至不可破。
Testing methodology： 見 @testing-skills-with-subagents.md 以察完整測法：
"In session 2025-10-03, we found empty projectDir caused..." 何以壞： 過特，不可重用
example-js.js, example-py.py, example-go.go 何以壞： 品庸，維護負
step1 [label="import fs"];
step2 [label="read file"];
何以壞： 不可 copy-paste、難讀
helper1, helper2, step3, pattern4 何以壞： Label 應有語義
書任 skill 後，必止並竟部署程。
勿：
下部署 checklist 每 skill 必行。
部署未測 skill = 部署未測碼。違質準。
IMPORTANT：用 TodoWrite 為下每 checklist 項立 todo。
RED Phase - Write Failing Test:
GREEN Phase - Write Minimal Skill:
name + description（最多 1024；見 spec）REFACTOR Phase - Close Loopholes:
Quality Checks:
Deployment:
未來 Claude 如何尋汝 skill：
為此流優化 - 搜詞早且常。
Creating skills IS TDD for process documentation.
同 Iron Law：未測無 skill。 同環：RED（baseline）→ GREEN（書 skill）→ REFACTOR（閉 loophole）。 同益：品佳、驚少、果堅。
若汝於碼遵 TDD，亦於 skill 遵之。同律適於文件。
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
Use when an HTML UI beats terminal text — collecting structured answers (decision trees, multi-select, code/SQL fields), showing visual comparisons or mockups, running interactive demos, or presenting decisions for approval. A local browser companion renders markdown+YAML screens and streams the user's answers back. Use when: many questions at once, layout/visual choices, mockup or diagram feedback, config wizard, demo review, approve/revise decisions. Skip: a single quick question (use AskUserQuestion or plain text).
Use when you have a spec or requirements for a multi-step task, before touching code
Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
Use when you have a written implementation plan to execute in a separate session with review checkpoints