القائمة
Use when creating new skills, editing existing skills, or verifying skills work before deployment
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
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
| 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 遵之。同律適於文件。