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 Type	Purpose	Example
1	Obvious trigger	Should clearly match	"Create a new React component with tests"
2	Subtle trigger	Should also match	"I need a reusable button"
3	Near-miss	Should NOT match	"Review this component code"
4	Edge case	Define expected behavior	"Create a component and write its docs"
5	Ambiguous	Define 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:

Element	Required	Purpose
Frontmatter ( `name` , `description` )	Yes	Identification and trigger matching
CSO-optimized description	Yes	Starts with "Use when...", lists trigger conditions
Overview (2-3 sentences)	Yes	Purpose and value
Multi-phase process with STOP markers	Yes	Numbered phases with clear actions
Decision tables	Yes	Tables for choosing between approaches
Anti-patterns / Common mistakes table	Yes	"What NOT to do" section
Anti-rationalization guards	Yes	HARD-GATE or "Do NOT skip" markers
Integration points table	Yes	How skill connects to other skills
Concrete examples	Yes	Code/command examples where non-obvious
Skill type declaration	Yes	RIGID 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.

Rule	Explanation
Start with "Use when..."	Trigger condition format
List specific conditions, not capabilities	What activates the skill, not what it teaches
Maximum 1024 characters	Be 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

触发条件模式

Pattern	Format	Example
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:

Check	Question	Fix If Failing
Over-triggering	Does it match prompts it should NOT?	Narrow the description
Under-triggering	Does it miss valid prompts?	Add missing trigger conditions
Rationalization	Would an agent find a way to skip steps?	Add "Do NOT skip" constraints
Ambiguity	Are instructions interpretable multiple ways?	Make them concrete with examples
Token bloat	Is it over 500 lines?	Move reference material to separate files
Missing gates	Are there checkpoints between phases?	Add STOP markers

检查并填补漏洞：

检查项	问题	不通过时的修复方案
过度触发	是否匹配了不该匹配的提示词？	收窄描述范围
触发不足	是否漏掉了合法的触发提示词？	补充缺失的触发条件
逻辑自洽漏洞	Agent会不会找到跳过步骤的方法？	添加"请勿跳过"约束
表述模糊	指令是否存在多种解读方式？	用示例让指令更具体
Token冗余	内容是否超过500行？	将参考材料移到独立文件
缺少检查点	阶段之间是否没有检查点？	添加STOP标记

Token Efficiency Targets

Token效率目标

Skill Type	Target Lines	Strategy
Getting-started workflows	< 100 lines	Minimal steps
Frequently-loaded skills	< 200 lines	Tables over prose
Comprehensive reference skills	< 400 lines	Split into phases
Maximum allowed	500 lines	Move 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

第四阶段：验证与保存

Verify all 10 required elements from Phase 2 are present
Verify token budget is within target
Verify STOP markers exist between phases
Save the SKILL.md file
Test by invoking the skill with each test prompt

确认第二阶段要求的10个必填元素都已包含
确认Token用量在目标范围内
确认阶段之间存在STOP标记
保存SKILL.md文件
用每个测试提示词调用技能进行测试

Validation Checklist

验证检查清单

#	Check	Status
1	Frontmatter has `name` and `description`	[ ]
2	Description starts with "Use when"	[ ]
3	Overview is 2-3 sentences	[ ]
4	Phases are numbered with STOP markers	[ ]
5	Decision tables present (not prose)	[ ]
6	Anti-patterns table present	[ ]
7	Anti-rationalization guards present	[ ]
8	Integration points table present	[ ]
9	Concrete examples present	[ ]
10	Skill type declared (RIGID/FLEXIBLE)	[ ]
11	Under 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 Type	Test Method	What to Verify
Technique (TDD, debugging)	Apply to problem X and unusual problem Y	Produces 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 pressure	Passes clean code; enforces all rules even under pressure

技能类型	测试方法	验证内容
技术方法（TDD、调试）	应用到问题X和特殊问题Y	输出正确步骤，适配性正常
模式类（设计模式）	展示匹配的代码X和近似的代码Y	识别正确，拒绝正确
参考类（API文档、检查清单）	询问"X的规则是什么？"和"边界场景Z怎么处理？"	能找到正确答案，处理空白场景
规范类（安全审查）	先审查正确代码，再在时间压力下审查	正常代码通过审核，压力下也能执行所有规则

Anti-Patterns / Common Mistakes

反模式/常见错误

Mistake	Why It Is Wrong	What To Do Instead
Description describes content, not triggers	Skill never gets selected	Start with "Use when..." and list trigger conditions
Too broad — triggers on everything	Useful for nothing	Narrow to specific actions and artifacts
Too long — 1000+ lines	Wastes context tokens every invocation	Stay under 500 lines; split reference material
Missing constraints	Agents rationalize skipping steps	Add "Do NOT" rules and HARD-GATE markers
Untested against real prompts	Will misfire in production	Write test prompts BEFORE writing the skill
External file dependencies	Fragile — files may not exist	Self-contained or check file existence first
Prose where tables work	Harder to scan, more tokens	Use tables for structured comparisons
No STOP markers between phases	Agent blasts through without checkpoints	Add 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

集成点

Skill	Relationship
`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

Overview

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

Phase 1: Discovery

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

Phase 2: Generate Configuration

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

Phase 3: Verify

[Build image, run container, verify health check]

Anti-Patterns

Mistake	Fix
Running as root	Use non-root USER
No .dockerignore	Always create one

Mistake	Fix
Running as root	Use non-root USER
No .dockerignore	Always create one

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方法（先写测试提示词）、必填结构元素和验证检查清单，不得跳过任何内容。