writing-skills

编写技能

概述

创建有效、经过充分测试的 Claude Code 技能，使其能够可靠触发、高效加载并产生一致的结果。本技能强制采用 TDD 方法创建技能——先定义测试提示词，再编写最精简的技能，然后针对误触发和合理化倾向进行强化。

这是一个 RIGID 技能。 必须严格遵循每个步骤，不得走捷径。

阶段 1：定义测试提示词（RED）

[HARD-GATE] 在编写任何技能内容之前，先定义应该触发该技能的提示词。

编写 3-5 个测试提示词：

#	测试类型	目的	示例
1	明显触发	应明显匹配	“创建一个带测试的新 React 组件”
2	隐晦触发	也应匹配	“我需要一个可复用的按钮”
3	易混淆但不匹配	不应匹配	“评审这段组件代码”
4	边缘情况	明确预期行为	“创建一个组件并编写其文档”
5	模糊情况	明确应优先使用哪个技能	“搭建前端”

记录每个提示词的预期行为：

Test prompt: "Create a new React component with tests"
Expected: Should trigger component-creation skill
Should NOT trigger: testing-strategy, code-review, writing-skills

停止——在记录完所有测试提示词之前，不得进入阶段 2。

阶段 2：编写最精简的 SKILL.md（GREEN）

创建满足阶段 1 所有测试提示词的最精简技能定义。

必需结构

每个 SKILL.md 都必须包含以下所有要素：

要素	必需	目的
Frontmatter（name、description）	是	标识和触发匹配
针对 CSO 优化的描述	是	以 “Use when...” 开头，列出触发条件
概述（2-3 句话）	是	说明目的和价值
多阶段流程及 STOP 标记	是	编号阶段，包含明确操作
决策表	是	用于选择不同方案的表格
反模式／常见错误表	是	“不要做什么”部分
反合理化防护	是	HARD-GATE 或 “Do NOT skip” 标记
集成点表	是	说明技能如何与其他技能连接
具体示例	是	对不明显之处提供代码／命令示例
技能类型声明	是	在末尾声明 RIGID 或 FLEXIBLE

Frontmatter 规则

---
name: skill-name          # lowercase with hyphens, unique identifier
description: "Use when [trigger conditions]"  # Max 1024 chars
---

[HARD-GATE] description 字段必须以 “Use when” 开头。

CSO（Claude 搜索优化）规则

description 字段决定何时选择某项技能。请将其优化得像搜索查询一样。

规则	说明
以 “Use when...” 开头	触发条件格式
列出具体条件，而非能力	说明什么情况会激活该技能，而不是它教什么
最多 1024 个字符	简洁明了
使用动作动词	“creating”（创建）、“debugging”（调试）、“designing”（设计）、“reviewing”（评审）

好的示例：

description: "Use when creating database migrations, designing table schemas, adding indexes, or optimizing SQL queries"

不好的示例：

description: "A comprehensive guide to database design covering normalization, indexing, query optimization, and migration strategies"

触发条件模式

模式	格式	示例
基于操作	“Use when creating...、updating...、deleting...”	CRUD 操作
基于问题	“Use when debugging...、fixing...、resolving...”	修复错误
基于产物	“Use when working with Docker 文件、CI 配置...”	文件类型
基于阶段	“Use when starting a project、finishing a feature...”	工作流阶段

停止——在继续之前，确认 description 能匹配阶段 1 中的测试提示词。

阶段 3：强化技能（REFACTOR）

检查并堵住漏洞：

检查项	问题	未通过时的修正方法
过度触发	它是否匹配了不应匹配的提示词？	缩小 description 的范围
触发不足	它是否漏掉了有效提示词？	添加缺失的触发条件
合理化	Agent 是否会找到跳过步骤的方法？	添加 “Do NOT skip” 约束
歧义	指令是否存在多种解读方式？	通过示例使其具体明确
Token 臃肿	是否超过 500 行？	将参考资料移至单独文件
缺少关卡	各阶段之间是否有检查点？	添加 STOP 标记

Token 效率目标

技能类型	目标行数	策略
入门工作流	< 100 行	步骤精简
频繁加载的技能	< 200 行	多用表格，少用 prose
全面的参考类技能	< 400 行	拆分为多个阶段
允许的最大值	500 行	将额外内容移至单独文件

Token 缩减策略

• 用表格代替 prose 来呈现结构化信息
• 使用简洁的祈使句，不写解释性段落
• 将参考资料移至单独文件（仅在需要时加载）
• 消除冗余——同一件事只说一次
• 仅在模式不明显时使用代码示例

停止——在脑海中重新运行测试提示词。该技能对全部 5 个提示词都能正确触发吗？对相似但不匹配的提示词会不会不触发？

阶段 4：验证并保存

1. 确认阶段 2 中的 10 项必需元素均已包含
2. 确认 Token 用量在目标范围内
3. 确认各阶段之间均有 STOP 标记
4. 保存 SKILL.md 文件
5. 使用每个测试提示词调用该技能进行测试

验证清单

#	检查项	状态
1	Frontmatter 中包含 name 和 description	[ ]
2	Description 以 "Use when" 开头	[ ]
3	概述为 2–3 句话	[ ]
4	阶段已编号，且带有 STOP 标记	[ ]
5	存在决策表（而非 prose）	[ ]
6	存在反模式表	[ ]
7	存在反合理化防护规则	[ ]
8	存在集成点表	[ ]
9	存在具体示例	[ ]
10	已声明技能类型（RIGID/FLEXIBLE）	[ ]
11	总行数少于 500 行	[ ]

技能类型与测试

按技能类型测试

技能类型	测试方法	验证内容
Technique（TDD、调试）	将其应用于问题 X 和不寻常的问题 Y	能否给出正确步骤，并正确调整
Pattern（设计模式）	展示匹配的代码 X 和相似但不匹配的代码 Y	能否正确识别并正确拒绝
Reference（API 文档、清单）	提问“X 的规则是什么？”以及“边缘情况 Z 呢？”	能否找到正确答案并处理信息缺失的情况
Discipline（安全审查）	审查正确的代码，再在时间压力下审查代码	能否通过审查无误的代码，并在压力下仍执行所有规则

反模式 / 常见错误

错误	错误原因	应采取的做法
Description 描述内容，而非触发条件	技能永远不会被选中	以 "Use when..." 开头，并列出触发条件
范围太宽——什么情况都会触发	派不上用场	缩小范围，聚焦于具体操作和对象
太长——1000 行以上	每次调用都会浪费上下文 Token	控制在 500 行以内；拆分参考资料
缺少约束	Agent 会找理由跳过步骤	添加“Do NOT”规则和 HARD-GATE 标记
未使用真实提示词测试	在生产环境中容易误触发或漏触发	编写技能之前先编写测试提示词
依赖外部文件	不可靠——文件可能不存在	保持自包含，或先检查文件是否存在
能用表格的地方却使用 prose	更难浏览，且更耗 Token	用表格呈现结构化对比
阶段之间没有 STOP 标记	Agent 会一口气执行到底，不设检查点	在每个阶段后添加 STOP

反合理化防护规则

• [HARD-GATE] 在先定义测试提示词（阶段 1）之前，绝对不要编写技能
• [HARD-GATE] 绝对不要省略 description 字段，也不要使用非 "Use when" 格式
• 绝对不要跳过强化阶段——每项技能都需要进行合理化审查
• 绝对不要跳过验证清单——必须通过全部 11 项检查
• 绝对不要创建超过 500 行的技能——将其拆分为技能文件和参考文件
• 绝对不要在表格更清晰的地方使用 prose

集成点

技能	关系
self-learning	通过技能系统发现并加载技能
auto-improvement	跟踪技能的有效性并提出改进建议
spec-writing	可以使用 JTBD 方法论编写技能规范
code-review	部署前应对技能进行质量审查
testing-strategy	测试提示词遵循测试方法论

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

---
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 |

## Skill Type
**Flexible**

技能类型

严格 — 必须严格遵循 TDD 方法（先编写测试提示词）、必需的结构元素和验证清单。不得跳过任何元素。