Back to Details

writing-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

寫作技巧

Writing Skill

概述

Overview

**寫作技巧是將測試驅動開發應用於流程文件。 **
個人技能位於特定於代理商的目錄中（
~/.claude/skills
對於克勞德·代碼，
~/.agents/skills/
用於食品法典）
您編寫測試案例（子代理程式的壓力場景），觀察它們失敗（基線行為），編寫技能（文件），觀察測試通過（代理遵守），然後重構（關閉漏洞）。
核心原則： 如果你沒有看到代理在沒有技能的情況下失敗，你就不知道該技能是否教導了正確的東西。
所需背景： 在使用此技能之前，您必須瞭解超能力：測試驅動開發。該技能定義了基本的紅-綠-重構循環。該技能使 TDD 適應文檔。
官方指導： Anthropic 的官方技能創作最佳實踐，請參閱anthropic-best-practices.md。本文檔提供了額外的模式和指南，以補充該技能中以 TDD 為中心的方法。
The Writing Skill applies Test-Driven Development (TDD) to process documentation.
Personal skills are stored in agent-specific directories (
~/.claude/skills
for Claude Code, 
~/.agents/skills/
for Codex)
You write test cases (stress scenarios for sub-agents), observe them fail (baseline behavior), write the skill (documentation), observe the tests pass (agent compliance), then refactor (close loopholes).
Core Principle: If you don't see the agent fail without the skill, you don't know if the skill teaches the right thing.
Required Background: Before using this skill, you must understand the superpower: Test-Driven Development. That skill defines the basic red-green-refactor cycle. This skill adapts TDD for documentation.
Official Guidance: For Anthropic's official skill creation best practices, refer to anthropic-best-practices.md. This document provides additional patterns and guidelines to complement the TDD-centered approach in that skill.

什麼是技能？

What is a Skill?

技能是經過驗證的技術、模式或工具的參考指南。技能幫助未來的克勞德實例找到並應用有效的方法。
技能是： 可重複使用的技術、模式、工具、參考指南
技能不是： 關於您如何解決一次問題的敘述
A Skill is a reference guide for validated techniques, patterns, or tools. Skills help future Claude instances find and apply effective methods.
Skills are: Reusable techniques, patterns, tools, reference guides
Skills are NOT: Narratives about how you solved a problem once

TDD 技能映射

TDD to Skill Creation Mapping

TDD 概念技能創造
測試用例帶有子代理的壓力場景
生產代碼技能文檔(SKILL.md)
測試失敗（紅色）代理在沒有技能的情況下違反規則（基線）
測試通過（綠色）代理人遵守現有技能
重構堵住漏洞，同時保持合規性
先寫測試在編寫技能之前運行基線場景
看著它失敗記錄代理人所使用的準確合理化
最少程式碼編寫解決這些特定違規行為的技能
看著它過去驗證代理現在是否符合要求
重構週期尋找新的合理化→阻塞→重新驗證
整個技能創建過程遵循紅-綠-重構。
TDD ConceptSkill Creation
Test CaseStress scenario with sub-agent
Production CodeSkill documentation (SKILL.md)
Test Failure (Red)Agent violates rules without the skill (baseline)
Test Pass (Green)Agent complies with the existing skill
RefactorClose loopholes while maintaining compliance
Write Test FirstRun baseline scenarios before writing the skill
Watch It FailRecord the exact rationalizations the agent uses
Minimal CodeWrite the skill to address these specific violations
Watch It PassVerify the agent now complies
Refactor CycleLook for new rationalizations → block → re-verify
The entire skill creation process follows red-green-refactor.

何時創建技能

When to Create a Skill

創建時間：
  • 技術對你來說並不直觀明顯
  • 您可以在項目中再次引用它
  • 模式適用範圍廣泛（不特定於項目）
  • 其他人會受益
不要為以下目的創建：
  • 免洗解決方案
  • 其他地方有詳細記錄的標準實踐
  • 項目特定約定（放入CLAUDE.md）
  • 機械約束（如果可以透過正規表示式/驗證強制執行，則將其自動化 - 保存判斷呼叫的文件）
Create when:
  • The technique isn't intuitively obvious to you
  • You would reference it again in a project
  • The pattern applies broadly (not project-specific)
  • Others would benefit
Don't create for:
  • One-off solutions
  • Standard practices already well-documented elsewhere
  • Project-specific conventions (put in CLAUDE.md)
  • Mechanical constraints (automate if you can enforce via regex/validation - save documentation for judgment calls)

技能類型

Skill Types

科技

Technique

具體方法和步驟（基於條件的等待、根本原因追蹤）
Specific methods and steps (condition-based waiting, root cause tracing)

圖案

Pattern

思考問題的方式（帶有標誌的扁平化、測試不變量）
Ways of thinking about problems (flatten with flags, test invariants)

參考

Reference

API文檔、語法指南、工具文檔（office文檔）
API docs, syntax guides, tool documentation (office docs)

目錄結構

Directory Structure

skills/
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed
扁平命名空間 - 所有技能都集中在一個可搜尋命名空間中
單獨的文件：
  1. 大量參考（100 多行）- API 文檔，全面的語法
  2. 可重複使用工具 - 腳本、實用程式、模板
保持內聯：
  • 原理和概念
  • 程式碼模式（< 50 行）
  • 其他一切
skills/
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed
Flat Namespace - All skills live in a single searchable namespace
Separate Files:
  1. Heavy Reference (100+ lines) - API docs, comprehensive syntax
  2. Reusable Tools - Scripts, utilities, templates
Keep Inline:
  • Principles and concepts
  • Code patterns (<50 lines)
  • Everything else

SKILL.md結構

SKILL.md Structure

前端問題 (YAML)：
  • 僅支援兩個欄位：
    name
    和
    description
  • 總共最多 1024 個字符
  • name
    ：僅使用字母、數字和連字符（無括號、特殊字符）
  • description
    ：第三人稱，僅描述何時使用（而不是它的作用）
    • 從「Use when...」開始，專注於觸發條件
    • 包括具體症狀、情況和背景
    • 永遠不要總結技能的流程或工作流程（請參閱 CSO 部分以瞭解原因）
    • 盡可能保持在 500 個字元以內
markdown
---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---
Front Matter (YAML):
  • Only two fields supported: 
    name
    and 
    description
  • Maximum 1024 characters total
  • name
    : Use only letters, numbers, and hyphens (no brackets, special characters)
  • description
    : Third person, only describes when to use (not what it does)
    • Start with "Use when...", focus on trigger conditions
    • Include specific symptoms, situations, and context
    • Never summarize the skill's process or workflow (see CSO section for why)
    • Keep under 500 characters when possible
markdown
---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---

Skill Name

Skill Name

Overview

Overview

What is this? Core principle in 1-2 sentences.
What is this? Core principle in 1-2 sentences.

When to Use

When to Use

[Small inline flowchart IF decision non-obvious]
Bullet list with SYMPTOMS and use cases When NOT 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)

Core Pattern (for techniques/patterns)

Before/after code comparison
Before/after code comparison

Quick Reference

Quick Reference

Table or bullets for scanning common operations
Table or bullets for scanning common operations

Implementation

Implementation

Inline code for simple patterns Link to file for heavy reference or reusable tools
Inline code for simple patterns Link to file for heavy reference or reusable tools

Common Mistakes

Common Mistakes

What goes wrong + fixes
What goes wrong + fixes

Real-World Impact (optional)

Real-World Impact (optional)

Concrete results
undefined
Concrete results
undefined

克勞德搜尋優化 (CSO)

Claude Search Optimization (CSO)

**發現的關鍵：**未來的克勞德需要找到你的技能
Key to Discovery: Future Claude instances need to find your skill

1.豐富的描述字段

1. Rich Description Field

目的： 克勞德閱讀描述來決定為給定任務加載哪些技能。讓它回答：“我現在應該讀這個技能嗎？”
格式： 以“Use when...”開頭，重點關注觸發條件
關鍵：描述=何時使用，而不是技能的作用
描述應僅描述觸發條件。不要在描述中總結技能的流程或工作流程。
為什麼這很重要： 測試顯示，當描述總結了技能的工作流程時，克勞德可能會遵循描述而不是閱讀完整的技能內容。儘管該技能的流程圖清楚地顯示了兩次審查（規範合規性然後是代碼質量），但“任務之間的代碼審查”的描述導致克勞德進行了一次審查。
當描述改為“在執行具有獨立任務的實施計劃時使用”（沒有工作流程摘要）時，克勞德正確地閱讀了流程圖並遵循了兩階段審核流程。
陷阱： 總結工作流程的描述創建了克勞德將採取的捷徑。技能主體變成了克勞德跳過的文檔。
yaml
undefined
Purpose: Claude reads descriptions to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"
Format: Start with "Use when...", focus on trigger conditions
Key: Description = When to use, not what the skill does
The description should only describe trigger conditions. Do NOT summarize the skill's process or workflow in the description.
Why This Matters: Testing shows that when descriptions summarize the workflow, Claude may follow the description instead of reading the full skill content. Even though the skill's flowchart clearly showed two reviews (spec compliance then code quality), a description of "code review between tasks" led Claude to perform only one review.
When the description was changed to "Use when executing implementation plans with independent tasks in the current session" (no workflow summary), Claude correctly read the flowchart and followed the two-stage review process.
Pitfalls: Descriptions that summarize workflows create shortcuts Claude will take. The skill body becomes documentation Claude skips.
yaml
undefined

❌ BAD: Summarizes workflow - Claude may follow this instead of reading skill

❌ 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
description: Use when executing plans - dispatches subagent per task with code review between tasks

❌ BAD: Too much process detail

❌ BAD: Too much process detail

description: Use for TDD - write test first, watch it fail, write minimal code, refactor
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

✅ GOOD: Just triggering conditions, no workflow summary

✅ GOOD: Just triggering conditions, no workflow summary

description: Use when executing implementation plans with independent tasks in the current session
description: Use when executing implementation plans with independent tasks in the current session

✅ GOOD: Triggering conditions only

✅ GOOD: Triggering conditions only

description: Use when implementing any feature or bugfix, before writing implementation code

**內容：**
- 使用顯示該技能適用的具體觸發因素、症狀和情況
- 描述*問題*（競爭條件、不一致的行為）而不是*特定於語言的症狀*（setTimeout、睡眠）
- 保持觸發器與技術無關，除非技能本身是特定於技術的
- 如果技能是特定於技術的，請在觸發器中明確說明
- 以第三人稱書寫（注入系統提示符）
- **永遠不要總結技能的流程或工作流程**

```yaml
description: Use when implementing any feature or bugfix, before writing implementation code

**Content:**
- Use specific triggers, symptoms, and situations that show the skill applies
- Describe the *problem* (race conditions, inconsistent behavior) not *language-specific symptoms* (setTimeout, sleep)
- Keep triggers technology-agnostic unless the skill itself is technology-specific
- If the skill is technology-specific, explicitly state that in the trigger
- Write in third person (for injection into system prompts)
- **Never summarize the skill's process or workflow**

```yaml

❌ BAD: Too abstract, vague, doesn't include when to use

❌ BAD: Too abstract, vague, doesn't include when to use

description: For async testing
description: For async testing

❌ BAD: First person

❌ BAD: First person

description: I can help you with async tests when they're flaky
description: I can help you with async tests when they're flaky

❌ BAD: Mentions technology but skill isn't specific to it

❌ BAD: Mentions technology but skill isn't specific to it

description: Use when tests use setTimeout/sleep and are flaky
description: Use when tests use setTimeout/sleep and are flaky

✅ GOOD: Starts with "Use when", describes problem, no workflow

✅ GOOD: Starts with "Use when", describes problem, no workflow

description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

✅ GOOD: Technology-specific skill with explicit trigger

✅ GOOD: Technology-specific skill with explicit trigger

description: Use when using React Router and handling authentication redirects
undefined
description: Use when using React Router and handling authentication redirects
undefined

2. 關鍵詞覆蓋率

2. Keyword Coverage

使用克勞德會搜尋的字詞：
  • 錯誤消息：“掛鉤超時”、“ENOTEMPTY”、“競爭條件”
  • 症狀：“片狀”、“懸掛”、“殭屍”、“污染”
  • 同義詞：“超時/掛起/凍結”、“清理/拆卸/afterEach”
  • 工具：實際指令、函式庫名稱、檔案類型
Use words Claude will search for:
  • Error messages: "hook timeout", "ENOTEMPTY", "race condition"
  • Symptoms: "flaky", "hanging", "zombie", "pollution"
  • Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
  • Tools: Actual commands, library names, file types

3. 描述性命名

3. Descriptive Naming

使用主動語態，動詞在前：
  • ✅ 
    creating-skills
    不是
    skill-creation
  • ✅ 
    condition-based-waiting
    不是
    async-test-helpers
Use active voice, verb first:
  • ✅ 
    creating-skills
    not 
    skill-creation
  • ✅ 
    condition-based-waiting
    not 
    async-test-helpers

4. 代幣效率（關鍵）

4. Token Efficiency (Critical)

**問題：**每次對話中都會包含入門和經常引用的技能。每個令牌都很重要。
目標字數：
  • 入門工作流程：每個 <150 字
  • 常用技能：總字數<200
  • 其他技能：<500字（仍要簡潔）
技術：
將詳細信息移至工具幫助：
bash
undefined
Problem: Onboarding and frequently referenced skills are included in every conversation. Every token counts.
Target Word Counts:
  • Onboarding workflows: <150 words each
  • Frequently used skills: <200 total words
  • Other skills: <500 words (still be concise)
Techniques:
Move Details to Tool Help:
bash
undefined

❌ BAD: Document all flags in SKILL.md

❌ BAD: Document all flags in SKILL.md

search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

✅ GOOD: Reference --help

✅ GOOD: Reference --help

search-conversations supports multiple modes and filters. Run --help for details.

**使用交叉引用：**
```markdown
search-conversations supports multiple modes and filters. Run --help for details.

**Use Cross-References:**
```markdown

❌ BAD: Repeat workflow details

❌ BAD: Repeat workflow details

When searching, dispatch subagent with template... [20 lines of repeated instructions]
When searching, dispatch subagent with template... [20 lines of repeated instructions]

✅ GOOD: Reference other skill

✅ GOOD: Reference other skill

Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

**壓縮範例：**
```markdown
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

**Compress Examples:**
```markdown

❌ BAD: Verbose example (42 words)

❌ 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"]
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)

✅ GOOD: Minimal example (20 words)

Partner: "How did we handle auth errors in React Router?" You: Searching... [Dispatch subagent → synthesis]

**消除冗餘：**
- 不要重複交叉引用技能中的內容
- 不要解釋從命令中顯而易見的內容
- 請勿包含同一模式的多個範例

**確認：**
```bash
wc -w skills/path/SKILL.md
Partner: "How did we handle auth errors in React Router?" You: Searching... [Dispatch subagent → synthesis]

**Eliminate Redundancy:**
- Don't repeat content from cross-referenced skills
- Don't explain what's obvious from the command
- Don't include multiple examples of the same pattern

**Verification:**
```bash
wc -w skills/path/SKILL.md

getting-started workflows: aim for <150 each

getting-started workflows: aim for <150 each

Other frequently-loaded: aim for <200 total

Other frequently-loaded: aim for <200 total


**根據您所做的事情或核心見解來命名：**
- ✅ `condition-based-waiting` > `async-test-helpers`
- ✅ `using-skills`不是`skill-usage`
- ✅ `flatten-with-flags` > `data-structure-refactoring`
- ✅ `root-cause-tracing` > `debugging-techniques`

**動名詞 (-ing) 適用於流程：**
- `creating-skills`, `testing-skills`, `debugging-with-logs`
- 活躍，描述您正在採取的行動

**Name by what you do or core insight:**
- ✅ `condition-based-waiting` > `async-test-helpers`
- ✅ `using-skills` not `skill-usage`
- ✅ `flatten-with-flags` > `data-structure-refactoring`
- ✅ `root-cause-tracing` > `debugging-techniques`

**Gerunds (-ing) work for processes:**
- `creating-skills`, `testing-skills`, `debugging-with-logs`
- Active, describes the action you're taking

4. 交叉參考其他技能

4. Cross-Reference Other Skills

在撰寫引用其他技能的文件時：
僅使用技能名稱，並帶有明確的要求標記：
  • ✅ 好：
    **REQUIRED SUB-SKILL:** Use superpowers:test-driven-development
  • ✅ 好：
    **REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging
  • ❌ 壞：
    See skills/testing/test-driven-development
    （不清楚是否需要）
  • ❌ 壞：
    @skills/testing/test-driven-development/SKILL.md
    （力負荷，燒傷情況）
為什麼沒有@連結：
@
語法立即強制加載文件，在需要它們之前消耗 200k+ 上下文。
When writing docs that reference other skills:
Only use the skill name with explicit requirement markers:
  • ✅ GOOD: 
    **REQUIRED SUB-SKILL:** Use superpowers:test-driven-development
  • ✅ GOOD: 
    **REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging
  • ❌ BAD: 
    See skills/testing/test-driven-development
    (unclear if required)
  • ❌ BAD: 
    @skills/testing/test-driven-development/SKILL.md
    (heavy cognitive load, burns context)
Why no @ links: The 
@
syntax forces immediate loading of the document, consuming 200k+ context before it's needed.

流程圖使用

Flowchart Usage

dot
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"];
}
流程圖僅用於：
  • 不明顯的決策點
  • 您可能會過早停止的處理循環
  • 「何時使用 A 與 B」決策
切勿將流程圖用於：
  • 參考資料 → 表格、列表
  • 程式碼範例 → Markdown 區塊
  • 線性指令 → 編號列表
  • 無語義的標籤（step1、helper2）
有關 graphviz 樣式規則，請參閱@graphviz-conventions.dot。
為您的人類伴侶視覺化： 使用
render-graphs.js
在此目錄中將技能流程圖渲染為 SVG：
bash
./render-graphs.js ../some-skill           # Each diagram separately
./render-graphs.js ../some-skill --combine # All diagrams in one SVG
dot
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"];
}
Flowcharts are only for:
  • Non-obvious decision points
  • Process loops where you might stop early
  • "When to use A vs B" decisions
Never use flowcharts for:
  • Reference material → tables, lists
  • Code examples → Markdown blocks
  • Linear instructions → numbered lists
  • Non-semantic labels (step1, helper2)
For Graphviz style rules, see @graphviz-conventions.dot.
Visualize for your human partner: Use 
render-graphs.js
in this directory to render skill flowcharts as SVG:
bash
./render-graphs.js ../some-skill           # Each diagram separately
./render-graphs.js ../some-skill --combine # All diagrams in one SVG

程式碼範例

Code Examples

一個優秀的例子勝過許多平庸的例子
選擇最相關的語言：
  • 測試技術 → TypeScript/JavaScript
  • 系統調試 → Shell/Python
  • 數據處理 → Python
好例子：
  • 完整且可運行
  • 評論很好，解釋了為什麼
  • 來自真實場景
  • 清晰顯示圖案
  • 準備好適應（不是通用模板）
不：
  • 以 5 種以上語言實施
  • 創建填空模板
  • 編寫人為的例子
你很擅長移植——一個很好的例子就夠了。
One excellent example beats many mediocre examples
Choose the most relevant language:
  • Testing techniques → TypeScript/JavaScript
  • System debugging → Shell/Python
  • Data processing → Python
Good Examples:
  • Complete and runnable
  • Well-commented, explains why
  • From real scenarios
  • Clearly shows the pattern
  • Ready to adapt (not generic templates)
Don't:
  • Implement in 5+ languages
  • Create fill-in-the-blank templates
  • Write contrived examples
You're good at porting - one great example is enough.

文件組織

Document Organization

自成一體的技能

Self-Contained Skill

defense-in-depth/
  SKILL.md    # Everything inline
時間：所有內容都合適，不需要大量參考
defense-in-depth/
  SKILL.md    # Everything inline
When: Everything fits, no heavy reference needed

使用可重複使用工具的技能

Skill with Reusable Tools

condition-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt
何時：工具是可重用的代碼，而不僅僅是敘述性的
condition-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt
When: Tools are reusable code, not just narrative

具有大量參考的技能

Skill with Heavy Reference

pptx/
  SKILL.md       # Overview + workflows
  pptxgenjs.md   # 600 lines API reference
  ooxml.md       # 500 lines XML structure
  scripts/       # Executable tools
何時：參考資料對內聯來說太大
pptx/
  SKILL.md       # Overview + workflows
  pptxgenjs.md   # 600 lines API reference
  ooxml.md       # 500 lines XML structure
  scripts/       # Executable tools
When: Reference material is too large for inline

鐵律（與 TDD 相同）

Iron Rule (Same as TDD)

NO SKILL WITHOUT A FAILING TEST FIRST
這適用於新技能和對現有技能的編輯。
在測試之前先寫技能？刪除它。重新開始。 不測試就編輯技能？同樣違規。
沒有例外：
  • 不適合“簡單添加”
  • 不是為了“只是添加一個部分”
  • 不適用於“文件更新”
  • 不要將未經測試的更改保留為“參考”
  • 運行測試時不要“適應”
  • 刪除就是刪除
所需背景： 超級能力：測試驅動開發技能解釋了為什麼這很重要。同樣的原則也適用於文檔。
NO SKILL WITHOUT A FAILING TEST FIRST
This applies to new skills and edits to existing skills.
Wrote the skill before testing? Delete it. Start over. Edited a skill without testing? Same violation.
No exceptions:
  • Not for "simple additions"
  • Not for "just adding a section"
  • Not for "documentation updates"
  • Don't keep untested changes as "reference"
  • Don't "adapt" while running tests
  • Delete means delete
Required Background: The Superpowers: Test-Driven Development skill explains why this matters. The same principles apply to documentation.

測試所有技能類型

Testing All Skill Types

不同的技能類型需要不同的測試方法：
Different skill types require different testing approaches:

紀律執行技能（規則/要求）

Discipline Enforcement Skills (Rules/Requirements)

示例： TDD、完成前驗證、編碼前設計
測試用：
  • 學術問題：他們理解規則嗎？
  • 壓力場景：他們在壓力下服從嗎？
  • 多重壓力疊加：時間+沉沒成本+疲憊
  • 識別合理化並添加顯式計數器
成功標準： 特工在最大壓力下遵循規則
Examples: TDD, validate before finish, design before coding
Test with:
  • Academic questions: Do they understand the rules?
  • Stress scenarios: Do they comply under pressure?
  • Multiple stress叠加: Time + sunk cost + fatigue
  • Identify rationalizations and add explicit counters
Success Criteria: Agent follows rules under maximum pressure

技術技能（操作指南）

Technique Skills (How-To Guides)

範例： 基於條件的等待、根本原因追蹤、防禦性編程
測試用：
  • 應用場景：他們能正確應用該技術嗎？
  • 變化場景：它們是否處理邊緣情況？
  • 缺失信息測試：說明是否存在空白？
成功標準： 代理成功地將技術應用於新場景
Examples: Condition-based waiting, root cause tracing, defensive programming
Test with:
  • Application scenarios: Can they apply the technique correctly?
  • Variation scenarios: Do they handle edge cases?
  • Missing information tests: Do they indicate gaps?
Success Criteria: Agent successfully applies the technique to new scenarios

模式技能（心智模型）

Pattern Skills (Mental Models)

示例： 降低複雜性、信息隱藏概念
測試用：
  • 辨識場景：他們能辨識模式何時應用嗎？
  • 應用場景：他們能使用心智模型嗎？
  • 反例：他們知道什麼時候不應該申請嗎？
成功標準： 代理正確識別何時/如何應用模式
Examples: Reduce complexity, information hiding concepts
Test with:
  • Recognition scenarios: Can they identify when the pattern applies?
  • Application scenarios: Can they use the mental model?
  • Counterexamples: Do they know when not to apply it?
Success Criteria: Agent correctly identifies when/how to apply the pattern

參考技能（文檔/API）

Reference Skills (Documentation/API)

範例： API 文件、命令參考、庫指南
測試用：
  • 檢索場景：他們能找到正確的資訊嗎？
  • 應用場景：他們能正確使用他們發現的東西嗎？
  • 差距測試：是否涵蓋常見用例？
成功標準： 代理找到並正確應用參考信息
Examples: API docs, command references, library guides
Test with:
  • Retrieval scenarios: Can they find the correct information?
  • Application scenarios: Can they correctly use what they found?
  • Gap testing: Are common use cases covered?
Success Criteria: Agent finds and correctly applies reference information

跳過測試的常見理由

Common Excuses for Skipping Tests

對不起現實
「功力明顯清晰」您清楚≠其他代理人清楚。測試一下。
“這只是一個參考”參考文獻可能有空白、不清楚的部分。測試檢索。
“測試是矯枉過正”未經測試的技能存在問題。總是。 15 分鐘測試可節省數小時。
「我會測試是否有問題」問題=特工無法使用技能。部署之前進行測試。
“測試太繁瑣”測試比調試生產中的不良技能要簡單得多。
「我相信這很好」過度自信會帶來問題。無論如何都要測試一下。
“學術評審就夠了”閱讀≠使用。測試應用場景。
“沒有時間測試”部署未經測試的技能會浪費更多時間來修復它。
**所有這些意味著：在部署之前進行測試。無一例外。 **
ExcuseReality
"The skill is obviously clear"Clear to you ≠ clear to other agents. Test it.
"It's just a reference"References can have gaps, unclear sections. Test retrieval.
"Testing is overkill"Untested skills have problems. Always. A 15-minute test saves hours.
"I'll test if there's a problem"Problems = agents can't use the skill. Test before deployment.
"Testing is too tedious"Testing is simpler than debugging bad skills in production.
"I'm confident it's good"Overconfidence causes problems. Test anyway.
"Academic review is enough"Reading ≠ using. Test application scenarios.
"No time to test"Deploying untested skills wastes more time fixing it later.
All of this means: Test before deployment. No exceptions.

反對合理化的防彈技巧

Bulletproofing Skills Against Rationalization

執行紀律的技能（如 TDD）需要抵制合理化。代理人很聰明，在壓力下會發現漏洞。
心理學註： 瞭解說服技巧為何有效可以幫助您有系統地應用它們。有關權威、承諾、稀缺性、社會證明和統一原則的研究基金會（Cialdini，2021；Meincke et al.，2025）請參閱persuasion-principles.md。
Discipline-enforcing skills like TDD need to resist rationalization. Agents are smart and will find loopholes under pressure.
Psychology Note: Understanding why persuasion techniques work helps apply them systematically. For research on authority, commitment, scarcity, social proof, and unity principles (Cialdini, 2021; Meincke et al., 2025), see persuasion-principles.md.

明確堵住每一個漏洞

Explicitly Block Every Loophole

不要只是陳述規則 - 禁止特定的解決方法：
<壞>
markdown
Write code before test? Delete it.
</壞>
<好>
markdown
Write code before test? Delete it. Start over.

**No exceptions:**
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Don't look at it
- Delete means delete
</好>
Don't just state the rule - prohibit specific workarounds:
<bad> ```markdown Write code before test? Delete it. ``` </bad> <good> ```markdown Write code before test? Delete it. Start over.
No exceptions:
  • Don't keep it as "reference"
  • Don't "adapt" it while writing tests
  • Don't look at it
  • Delete means delete
</good>

解決「精神與文字」的爭論

Address "Spirit vs Letter" Arguments

儘早添加基本原則：
markdown
**Violating the letter of the rules is violating the spirit of the rules.**
這切斷了整個階級的「我追隨精神」的合理化。
Add a core principle early:
markdown
**Violating the letter of the rules is violating the spirit of the rules.**
This cuts off an entire class of "I followed the spirit" rationalizations.

建立合理化表

Build a Rationalization Table

從基線測試中獲取合理性（請參閱下面的測試部分）。代理人提出的每一個藉口都在表中：
markdown
| 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?" |
Capture rationalizations from baseline tests (see Testing section below). Every excuse the agent makes goes in the table:
markdown
| 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?" |

建立危險訊號列表

Build a Red Flags List

讓代理商在合理化時可以輕鬆自檢：
markdown
undefined
Give agents an easy self-check for rationalization:
markdown
undefined

Red Flags - STOP and Start Over

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.
undefined
  • 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.
undefined

更新 CSO 的違規症狀

Update CSO with Violation Symptoms

加入描述：當您即將違反規則時的症狀：
yaml
description: use when implementing any feature or bugfix, before writing implementation code
Add to description: Symptoms that you're about to violate the rule:
yaml
description: use when implementing any feature or bugfix, before writing implementation code

技能紅綠重構

Skill Red-Green-Refactor

遵循 TDD 週期：
Follow the TDD cycle:

紅色：寫入失敗測試（基線）

Red: Write Failing Test (Baseline)

在沒有技能的情況下使用子代理運行壓力場景。記錄確切的行為：
  • 他們做出了什麼選擇？
  • 他們使用了什麼合理化理由（逐字）？
  • 哪些壓力引發了違規行為？
這就是“觀察測試失敗”——在編寫技能之前，您必須瞭解代理自然會做什麼。
Run stress scenarios with sub-agents without the skill. Record exact behavior:
  • What choices did they make?
  • What rationalizations did they use (verbatim)?
  • Which pressures triggered violations?
This is "watch the test fail" - you must understand what the agent would naturally do before writing the skill.

綠色：寫出最低限度的技能

Green: Write Minimal Skill

寫出解決這些具體合理化的技巧。不要為假設案例添加額外的內容。
運用技巧運行相同的場景。代理現在應該遵守。
Write the skill to address these specific rationalizations. Don't add extra content for hypothetical cases.
Run the same scenarios with the skill. The agent should now comply.

重構：堵住漏洞

Refactor: Close Loopholes

代理找到新的合理化？添加顯式計數器。重新測試直到防彈。
測試方法： 請參閱@testing-skills-with-subagents.md以瞭解完整的測試方法：
  • 如何寫壓力場景
  • 壓力類型（時間、沉沒成本、權威、疲憊）
  • 系統地堵塞漏洞
  • 元測試技術
Agent found new rationalizations? Add explicit counters. Retest until bulletproof.
Testing Methods: See @testing-skills-with-subagents.md for complete testing methodology:
  • How to write stress scenarios
  • Types of pressure (time, sunk cost, authority, fatigue)
  • Systematically closing loopholes
  • Meta-testing techniques

反模式

Anti-Patterns

❌ 敘述例子

❌ Narrative Examples

“在 2025 年 10 月 3 日會話中，我們發現空的 projectDir 導致......” 為什麼不好： 太具體，不可重用
"In the October 3, 2025 session, we discovered empty projectDir caused..." Why bad: Too specific, not reusable

❌ 多語淡化

❌ Multi-Language Dilution

example-js.js、example-py.py、example-go.go 為什麼不好： 品質平庸，維持負擔重
example-js.js, example-py.py, example-go.go Why bad: Mediocre quality, high maintenance burden

❌ 流程圖中的代碼

❌ Code in Flowcharts

dot
step1 [label="import fs"];
step2 [label="read file"];
為什麼不好： 無法複製貼上，難以閱讀
dot
step1 [label="import fs"];
step2 [label="read file"];
Why bad: Can't copy-paste, hard to read

❌ 通用標籤

❌ Generic Labels

助手 1、助手 2、步驟 3、模式 4 為什麼不好： 標籤應該具有語義意義
Helper 1, Helper 2, Step 3, Pattern 4 Why bad: Labels should be semantically meaningful

停止：在轉向下一個技能之前

STOP: Before Moving to Next Skill

**寫完任何技能後，您必須停止並完成部署程序。 **
不要：
  • 批量創建多個技能，無需測試每個技能
  • 在驗證目前技能之前移至下一個技能
  • 跳過測試，因為“批處理更高效”
**下面的部署清單對於每項技能都是強制性的。 **
部署未經測試的技能=部署未經測試的程式碼。這是違反品質標準的。
After writing any skill, you must stop and complete the deployment process.
Don't:
  • Batch-create multiple skills without testing each one
  • Move to the next skill before validating the current one
  • Skip testing because "batching is more efficient"
The deployment checklist below is mandatory for every skill.
Deploying untested skills = deploying untested code. It's a violation of quality standards.

技能創建清單（TDD 改編）

Skill Creation Checklist (TDD Adapted)

**重要提示：使用 TodoWrite 為下面的每個清單項目建立待辦事項。 **
紅色階段 - 寫入失敗測試：
  • 創建壓力場景（紀律技能的 3+ 組合壓力）
  • 無需技能即可運行場景 - 逐字記錄基線行為
  • 識別合理化/失敗的模式
綠色階段 - 寫出最低技能：
  • 名稱僅使用字母、數字、連字符（無括號/特殊字符）
  • YAML frontmatter 僅包含名稱和描述（最多 1024 個字符）
  • 描述以「何時使用」開頭，並包含特定的觸發因素/症狀
  • 以第三人稱書寫的描述
  • 搜索關鍵詞（錯誤、症狀、工具）
  • 清晰概述與核心原則
  • 解決 RED 中確定的特定基線故障
  • 程式碼內聯或連結到單獨的文件
  • 一個很好的例子（非多語言）
  • 使用技能運行場景 - 驗證代理現在是否遵守
重構階段 - 堵住漏洞：
  • 從測試中找出新的合理性
  • 增加明確的指示物（如果是紀律技能）
  • 根據所有測試迭代構建合理化表
  • 建立危險訊號列表
  • 重新測試至防彈
質量檢查：
  • 僅當決策不明顯時才使用小流程圖
  • 快速參考表
  • 常見錯誤部分
  • 不講故事
  • 支援文件僅供工具或大量參考
部署：
  • 將技能提交至 git 並推送到您的 fork（如果已配置）
  • 考慮通過公關做出貢獻（如果廣泛有用）
Important: Use TodoWrite to create todos for each checklist item below.
Red Phase - Write Failing Test:
  • Create stress scenarios (3+ combined pressures for discipline skills)
  • Run scenarios without the skill - record baseline behavior verbatim
  • Identify rationalization/failure patterns
Green Phase - Write Minimal Skill:
  • Name uses only letters, numbers, hyphens (no brackets/special characters)
  • YAML frontmatter only includes name and description (max 1024 characters)
  • Description starts with "Use when" and includes specific triggers/symptoms
  • Description written in third person
  • Search keywords included (errors, symptoms, tools)
  • Clear overview with core principle
  • Addresses specific baseline failures identified in RED phase
  • Code is inline or linked to separate files
  • One excellent example (not multi-language)
  • Run scenarios with the skill - verify agent now complies
Refactor Phase - Close Loopholes:
  • Identify new rationalizations from testing
  • Add explicit counters (if discipline skill)
  • Build rationalization table from all test iterations
  • Create red flags list
  • Retest until bulletproof
Quality Check:
  • Only use small flowcharts when decisions are non-obvious
  • Quick reference table included
  • Common mistakes section included
  • No narrative stories
  • Supporting files only for tools or heavy reference
Deployment:
  • Commit skill to git and push to your fork (if configured)
  • Consider contributing via PR if broadly useful

發現工作流程

Discovery Workflow

未來的克勞德如何找到你的技能：
  1. 遇到問題（“測試不穩定”）
  2. 找到技能（描述匹配）
  3. 掃描概述（這相關嗎？）
  4. 讀取模式（快速參考表）
  5. 載入範例（僅在實作時）
針對此流程進行優化 - 儘早且經常放置可搜索術語。
How future Claude instances find your skill:
  1. Encounter problem ("tests are flaky")
  2. Find skill (description matches)
  3. Scan overview (is this relevant?)
  4. Read pattern (quick reference table)
  5. Load example (only when implementing)
Optimize for this workflow - place searchable terms early and often.
Bottom Line
Skill creation is TDD for process documentation.
Same iron rule: No skill without a failing test first. Same cycle: Red (baseline) → Green (write skill) → Refactor (close loopholes). Same benefits: Better quality, fewer surprises, bulletproof results.
If you follow TDD for code, follow TDD for skills. It's the same rules applied to documentation.

底線

—
**建立技能是流程文件的 TDD。 **
同樣的鐵律：沒有經過考驗就沒有技能。 相同的循環：紅色（基線）→綠色（編寫技巧）→REFACTOR（關閉漏洞）。 相同的好處：更好的品質、更少的驚喜、萬無一失的結果。
如果您在程式碼方面遵循 TDD，那麼在技能方面也遵循 TDD。這與套用於文件的規則相同。
—