Back to Details

writing-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing Skills

技能编写

Overview

概述

Create effective, well-tested Claude Code skills that trigger reliably, load efficiently, and produce consistent results. This skill enforces a TDD approach to skill creation — define test prompts first, write the minimal skill, then harden against misfire and rationalization.
This is a RIGID skill. Every step must be followed exactly. No shortcuts.
创建有效、经过充分测试的Claude Code技能，确保其触发可靠、加载高效且输出结果一致。本技能要求技能创建遵循TDD方法——先定义测试提示词，编写最简技能，再针对误触发和逻辑自洽问题加固。
这是一个RIGID（严格）技能，必须完全遵循每一步，不得走捷径。

Phase 1: Define Test Prompts (RED)

第一阶段：定义测试提示词（红）

[HARD-GATE] Before writing any skill content, define the prompts that should trigger it.
Write 3-5 test prompts:
#Test TypePurposeExample
1Obvious triggerShould clearly match"Create a new React component with tests"
2Subtle triggerShould also match"I need a reusable button"
3Near-missShould NOT match"Review this component code"
4Edge caseDefine expected behavior"Create a component and write its docs"
5AmbiguousDefine which skill wins"Set up the frontend"
Document expected behavior for each:
Test prompt: "Create a new React component with tests"
Expected: Should trigger component-creation skill
Should NOT trigger: testing-strategy, code-review, writing-skills
STOP — Do NOT proceed to Phase 2 until all test prompts are documented.
[HARD-GATE] 在编写任何技能内容之前，先定义能够触发该技能的提示词。
编写3-5个测试提示词：
#测试类型目的示例
1明显触发应当明确匹配"Create a new React component with tests"
2隐晦触发应当也能匹配"我需要一个可复用的按钮"
3近似触发应当不匹配"Review this component code"
4边界场景定义预期行为"创建一个组件并编写其文档"
5模糊场景定义优先触发的技能"搭建前端项目"
为每个提示词记录预期行为：
测试提示词："Create a new React component with tests"
预期：应当触发组件创建技能
不应触发：testing-strategy, code-review, writing-skills
STOP —— 所有测试提示词记录完成前，不要进入第二阶段。

Phase 2: Write Minimal SKILL.md (GREEN)

第二阶段：编写最简SKILL.md（绿）

Create the minimum skill definition that passes all test prompts from Phase 1.
编写能够通过第一阶段所有测试提示词的最小技能定义。

Required Structure

要求结构

Every SKILL.md MUST contain ALL of these elements:
ElementRequiredPurpose
Frontmatter (
name
, 
description
)		YesIdentification and trigger matching
CSO-optimized descriptionYesStarts with "Use when...", lists trigger conditions
Overview (2-3 sentences)YesPurpose and value
Multi-phase process with STOP markersYesNumbered phases with clear actions
Decision tablesYesTables for choosing between approaches
Anti-patterns / Common mistakes tableYes"What NOT to do" section
Anti-rationalization guardsYesHARD-GATE or "Do NOT skip" markers
Integration points tableYesHow skill connects to other skills
Concrete examplesYesCode/command examples where non-obvious
Skill type declarationYesRIGID or FLEXIBLE at the end
每个SKILL.md必须包含以下所有元素：
元素是否必填目的
头部元数据 (
name
, 
description
)		是识别和触发匹配
CSO优化的描述是以"Use when..."开头，列出触发条件
概述（2-3句话）是说明用途和价值
带STOP标记的多阶段流程是带明确操作的编号阶段
决策表是用于不同方案选择的表格
反模式/常见错误表是"禁止操作"部分
防逻辑自洽守卫是HARD-GATE或"请勿跳过"标记
集成点表是说明该技能与其他技能的关联方式
具体示例是不直观的场景下提供代码/命令示例
技能类型声明是末尾标注RIGID或FLEXIBLE

Frontmatter Rules

头部元数据规则

yaml
---
name: skill-name          # lowercase with hyphens, unique identifier
description: "Use when [trigger conditions]"  # Max 1024 chars
---
[HARD-GATE] The 
description
field MUST start with "Use when".
yaml
---
name: skill-name          # 小写连字符格式，唯一标识符
description: "Use when [trigger conditions]"  # 最长1024字符
---
[HARD-GATE] 
description
字段必须以"Use when"开头。

CSO (Claude Search Optimization) Rules

CSO（Claude搜索优化）规则

The 
description
field determines when a skill is selected. Optimize it like a search query.
RuleExplanation
Start with "Use when..."Trigger condition format
List specific conditions, not capabilitiesWhat activates the skill, not what it teaches
Maximum 1024 charactersBe concise
Use action verbs"creating", "debugging", "designing", "reviewing"
Good:
yaml
description: "Use when creating database migrations, designing table schemas, adding indexes, or optimizing SQL queries"
Bad:
yaml
description: "A comprehensive guide to database design covering normalization, indexing, query optimization, and migration strategies"
description
字段决定了技能何时被选中，要像优化搜索查询一样优化该字段。
规则说明
以"Use when..."开头触发条件格式要求
列出具体条件而非能力说明什么场景触发技能，而非技能能做什么
最多1024字符保持简洁
使用动作动词"creating", "debugging", "designing", "reviewing"
正确示例：
yaml
description: "Use when creating database migrations, designing table schemas, adding indexes, or optimizing SQL queries"
错误示例：
yaml
description: "A comprehensive guide to database design covering normalization, indexing, query optimization, and migration strategies"

Trigger Condition Patterns

触发条件模式

PatternFormatExample
Action-based"Use when creating..., updating..., deleting..."CRUD operations
Problem-based"Use when debugging..., fixing..., resolving..."Bug fixes
Artifact-based"Use when working with Docker files, CI configs..."File types
Phase-based"Use when starting a project, finishing a feature..."Workflow stage
STOP — Verify the description would match test prompts from Phase 1 before proceeding.
模式格式示例
基于动作"Use when creating..., updating..., deleting..."CRUD操作
基于问题"Use when debugging..., fixing..., resolving..."Bug修复
基于产物"Use when working with Docker files, CI configs..."文件类型
基于阶段"Use when starting a project, finishing a feature..."工作流阶段
STOP —— 继续之前请确认描述能够匹配第一阶段的测试提示词。

Phase 3: Harden the Skill (REFACTOR)

第三阶段：技能加固（重构）

Review and close loopholes:
CheckQuestionFix If Failing
Over-triggeringDoes it match prompts it should NOT?Narrow the description
Under-triggeringDoes it miss valid prompts?Add missing trigger conditions
RationalizationWould an agent find a way to skip steps?Add "Do NOT skip" constraints
AmbiguityAre instructions interpretable multiple ways?Make them concrete with examples
Token bloatIs it over 500 lines?Move reference material to separate files
Missing gatesAre there checkpoints between phases?Add STOP markers
检查并填补漏洞：
检查项问题不通过时的修复方案
过度触发是否匹配了不该匹配的提示词？收窄描述范围
触发不足是否漏掉了合法的触发提示词？补充缺失的触发条件
逻辑自洽漏洞Agent会不会找到跳过步骤的方法？添加"请勿跳过"约束
表述模糊指令是否存在多种解读方式？用示例让指令更具体
Token冗余内容是否超过500行？将参考材料移到独立文件
缺少检查点阶段之间是否没有检查点？添加STOP标记

Token Efficiency Targets

Token效率目标

Skill TypeTarget LinesStrategy
Getting-started workflows< 100 linesMinimal steps
Frequently-loaded skills< 200 linesTables over prose
Comprehensive reference skills< 400 linesSplit into phases
Maximum allowed500 linesMove extras to separate files
技能类型目标行数优化策略
入门工作流< 100行步骤最少化
高频加载技能< 200行用表格替代大段文字
综合参考技能< 400行拆分到多个阶段
最大允许行数500行额外内容移到独立文件

Token Reduction Strategies

Token减少策略

  • Use tables instead of prose for structured information
  • Use terse imperative sentences, not explanatory paragraphs
  • Move reference material to separate files (loaded only when needed)
  • Eliminate redundancy — say it once
  • Use code examples only when the pattern is non-obvious
STOP — Re-run test prompts mentally. Does the skill trigger correctly for all 5? Does it NOT trigger for near-misses?
  • 结构化信息用表格替代大段文字
  • 使用简洁的祈使句，而非解释性段落
  • 参考材料移到独立文件（仅在需要时加载）
  • 消除冗余内容，只说一遍
  • 仅在模式不直观时提供代码示例
STOP —— 在脑海中重新运行所有测试提示词，技能对5个测试用例的触发是否正确？对近似触发的用例是否不会触发？

Phase 4: Validate and Save

第四阶段：验证与保存

  1. Verify all 10 required elements from Phase 2 are present
  2. Verify token budget is within target
  3. Verify STOP markers exist between phases
  4. Save the SKILL.md file
  5. Test by invoking the skill with each test prompt
  1. 确认第二阶段要求的10个必填元素都已包含
  2. 确认Token用量在目标范围内
  3. 确认阶段之间存在STOP标记
  4. 保存SKILL.md文件
  5. 用每个测试提示词调用技能进行测试

Validation Checklist

验证检查清单

#CheckStatus
1Frontmatter has 
name
and 
description
[ ]
2Description starts with "Use when"[ ]
3Overview is 2-3 sentences[ ]
4Phases are numbered with STOP markers[ ]
5Decision tables present (not prose)[ ]
6Anti-patterns table present[ ]
7Anti-rationalization guards present[ ]
8Integration points table present[ ]
9Concrete examples present[ ]
10Skill type declared (RIGID/FLEXIBLE)[ ]
11Under 500 lines total[ ]
#检查项状态
1头部元数据包含
name
和
description
[ ]
2描述以"Use when"开头[ ]
3概述为2-3句话[ ]
4阶段带编号且有STOP标记[ ]
5包含决策表（而非大段文字）[ ]
6包含反模式表[ ]
7包含防逻辑自洽守卫[ ]
8包含集成点表[ ]
9包含具体示例[ ]
10已声明技能类型（RIGID/FLEXIBLE）[ ]
11总行数少于500行[ ]

Skill Types and Testing

技能类型与测试

Testing by Skill Type

按技能类型测试

Skill TypeTest MethodWhat to Verify
Technique (TDD, debugging)Apply to problem X and unusual problem YProduces right steps; adapts correctly
Pattern (design patterns)Show code X (matches) and code Y (near-miss)Identifies correctly; rejects correctly
Reference (API docs, checklists)Ask "what is the rule for X?" and "what about edge case Z?"Finds right answer; handles gaps
Discipline (security review)Review correct code, then review under time pressurePasses clean code; enforces all rules even under pressure
技能类型测试方法验证内容
技术方法（TDD、调试）应用到问题X和特殊问题Y输出正确步骤，适配性正常
模式类（设计模式）展示匹配的代码X和近似的代码Y识别正确，拒绝正确
参考类（API文档、检查清单）询问"X的规则是什么？"和"边界场景Z怎么处理？"能找到正确答案，处理空白场景
规范类（安全审查）先审查正确代码，再在时间压力下审查正常代码通过审核，压力下也能执行所有规则

Anti-Patterns / Common Mistakes

反模式/常见错误

MistakeWhy It Is WrongWhat To Do Instead
Description describes content, not triggersSkill never gets selectedStart with "Use when..." and list trigger conditions
Too broad — triggers on everythingUseful for nothingNarrow to specific actions and artifacts
Too long — 1000+ linesWastes context tokens every invocationStay under 500 lines; split reference material
Missing constraintsAgents rationalize skipping stepsAdd "Do NOT" rules and HARD-GATE markers
Untested against real promptsWill misfire in productionWrite test prompts BEFORE writing the skill
External file dependenciesFragile — files may not existSelf-contained or check file existence first
Prose where tables workHarder to scan, more tokensUse tables for structured comparisons
No STOP markers between phasesAgent blasts through without checkpointsAdd STOP after each phase
错误错误原因替代方案
描述说明的是内容而非触发条件技能永远不会被选中以"Use when..."开头，列出触发条件
范围太宽，什么场景都触发没有实际用途收窄到具体动作和产物
内容太长，超过1000行每次调用都浪费上下文Token保持在500行以内，拆分参考材料
缺少约束Agent会找理由跳过步骤添加"请勿"规则和HARD-GATE标记
未用真实提示词测试生产环境会误触发编写技能前先写测试提示词
依赖外部文件脆弱，文件可能不存在内容自包含，或先检查文件是否存在
能用表格的地方用大段文字难扫描，占用更多Token结构化对比用表格
阶段之间没有STOP标记Agent会跳过检查点直接走完流程每个阶段结束后添加STOP

Anti-Rationalization Guards

防逻辑自洽守卫

  • [HARD-GATE] Do NOT write a skill without defining test prompts first (Phase 1)
  • [HARD-GATE] Do NOT omit the description field or use a non-"Use when" format
  • Do NOT skip the hardening phase — every skill needs rationalization review
  • Do NOT skip the validation checklist — all 11 items must pass
  • Do NOT create skills over 500 lines — split into skill + reference file
  • Do NOT use prose where a table would be clearer
  • [HARD-GATE] 编写技能前必须先定义测试提示词（第一阶段）
  • [HARD-GATE] 不得省略description字段，也不得使用非"Use when"格式
  • 请勿跳过 加固阶段——每个技能都需要做逻辑自洽审查
  • 请勿跳过 验证检查清单——所有11项必须全部通过
  • 不得 创建超过500行的技能——拆分为技能+参考文件
  • 不得 能用表格的地方用大段文字

Integration Points

集成点

SkillRelationship
self-learning
Skills are discovered and loaded via the skill system
auto-improvement
Tracks skill effectiveness and suggests improvements
spec-writing
Skills can be specified using JTBD methodology
code-review
Skills should be reviewed for quality before deployment
testing-strategy
Test prompts follow testing methodology
技能关联关系
self-learning
技能通过技能系统被发现和加载
auto-improvement
跟踪技能有效性并提出改进建议
spec-writing
可使用JTBD方法论定义技能需求
code-review
技能上线前需要做质量审查
testing-strategy
测试提示词遵循测试方法论

Concrete Example: Complete Minimal Skill

具体示例：完整的最简技能

markdown
---
name: docker-setup
description: "Use when creating Dockerfiles, docker-compose configurations, or containerizing an application for development or production"
---
markdown
---
name: docker-setup
description: "Use when creating Dockerfiles, docker-compose configurations, or containerizing an application for development or production"
---

Docker Setup

Docker Setup

Overview

Overview

Guide the creation of Docker configurations for development and production environments. Produces Dockerfiles, docker-compose files, and .dockerignore with best practices.
Guide the creation of Docker configurations for development and production environments. Produces Dockerfiles, docker-compose files, and .dockerignore with best practices.

Phase 1: Discovery

Phase 1: Discovery

[Ask about: runtime, ports, volumes, env vars, multi-stage needs] STOP — confirm requirements.
[Ask about: runtime, ports, volumes, env vars, multi-stage needs] STOP — confirm requirements.

Phase 2: Generate Configuration

Phase 2: Generate Configuration

[Create Dockerfile, docker-compose.yml, .dockerignore] STOP — present for review.
[Create Dockerfile, docker-compose.yml, .dockerignore] STOP — present for review.

Phase 3: Verify

Phase 3: Verify

[Build image, run container, verify health check]
[Build image, run container, verify health check]

Anti-Patterns

Anti-Patterns

MistakeFix
Running as rootUse non-root USER
No .dockerignoreAlways create one
MistakeFix
Running as rootUse non-root USER
No .dockerignoreAlways create one

Skill Type

Skill Type

Flexible
undefined
Flexible
undefined

Skill Type

技能类型

Rigid — The TDD approach (test prompts first), required structure elements, and validation checklist must be followed exactly. No elements may be skipped.
Rigid —— 必须严格遵循TDD方法（先写测试提示词）、必填结构元素和验证检查清单，不得跳过任何内容。