name: 创建技能 description: 使用场景：创建新的Claude代码技能或改进现有技能 - 通过适当的结构、CSO优化和真实示例确保技能可发现、可扫描且有效
创建技能
概述
技能是经过验证的技术、模式或工具的参考指南。 编写技能以帮助未来的Claude实例快速找到并应用有效方法。
技能必须可发现（Claude能找到它们）、可扫描（快速评估）和可操作（清晰示例）。
核心原则：默认假设Claude已经非常聪明。只添加Claude没有的上下文。
何时使用
创建技能当：
- 技术不是直观明显的
- 模式广泛适用于多个项目
- 你会再次参考这个技能
- 其他人会受益
不要为以下情况创建：
- 特定于单个项目的一次性解决方案
- 其他地方有良好文档的标准实践
- 项目约定（放在
.claude/CLAUDE.md中）
必需结构
前置元数据（YAML）
---
name: 技能名称-使用连字符
description: 使用场景：[触发条件/症状] - [它做什么以及如何帮助]
tags: 相关标签
---
规则：
- 仅支持
name和description字段（总计最多1024字符） - 名称：仅字母、数字、连字符（最多64字符）。使用动名词形式（动词+ing）
- 避免保留词：名称中不要使用"anthropic"、“claude”
- 描述：第三人称，以"使用场景…"开头（最多1024字符）
- 同时包含触发条件和技能作用
- 将特异性与任务复杂性匹配（自由度程度）
文档结构
# 技能名称
## 概述
1-2句话的核心原则。这是什么？
## 何时使用
- 包含症状和使用场景的要点列表
- 何时不使用
## 快速参考
常见操作的表格或要点
## 实现
简单模式的内联代码
对于大量参考（100+行）链接到单独文件
## 常见错误
出错原因 + 如何修复
## 实际影响（可选）
使用此技术的具体结果
自由度程度
将特异性与任务复杂性匹配：
-
高自由度：需要判断的灵活任务
- 使用广泛指导、原则、示例
- 让Claude根据上下文调整方法
- 示例：“使用场景：设计API时 - 提供REST原则和模式”
-
低自由度：脆弱或关键操作
- 明确具体步骤
- 包含验证检查
- 示例：“使用场景：部署到生产环境时 - 遵循包含回滚程序的确切部署清单”
危险信号：如果技能在创造性任务上过度约束Claude，降低特异性。如果技能在关键操作上过于模糊，添加明确步骤。
Claude搜索优化（CSO）
关键：未来的Claude通过描述决定技能是否相关。为可发现性优化。
描述最佳实践
# ❌ 差 - 太模糊，未提及何时使用
description: 用于异步测试
# ❌ 差 - 第一人称（注入系统提示）
description: 我帮你处理不稳定测试
# ✅ 好 - 触发条件 + 作用
description: 使用场景：测试存在竞争条件或通过/失败不一致时 - 用条件轮询替换任意超时以实现可靠的异步测试
# ✅ 好 - 技术特定且明确触发条件
description: 使用场景：使用React Router并处理身份验证重定向时 - 提供受保护路由和身份验证状态管理模式
关键词覆盖
使用Claude会搜索的词语：
- 错误消息：“ENOENT”、“Cannot read property”、“Timeout”
- 症状：“不稳定”、“挂起”、“竞争条件”、“内存泄漏”
- 同义词：“清理/拆卸/afterEach”、“超时/挂起/冻结”
- 工具：实际命令名称、库名称、文件类型
命名约定
使用动名词形式（动词+ing）：
- ✅
创建技能而非技能创建 - ✅
使用子代理测试而非子代理测试 - ✅
调试内存泄漏而非内存泄漏调试 - ✅
处理PDF而非PDF处理器 - ✅
分析电子表格而非电子表格分析
为什么动名词有效：
- 描述你正在采取的行动
- 主动且清晰
- 与Anthropic约定一致
避免：
- ❌ 模糊名称如"助手"或"工具"
- ❌ 被动语态结构
代码示例
一个优秀示例胜过许多平庸示例。
根据使用场景选择语言
- 测试技术 → TypeScript/JavaScript
- 系统调试 → Shell/Python
- 数据处理 → Python
- API调用 → TypeScript/JavaScript
好示例清单
- [ ] 完整且可运行
- [ ] 良好注释解释为什么而不仅仅是做什么
- [ ] 来自真实场景（非虚构）
- [ ] 清晰展示模式
- [ ] 准备好适应（非通用模板）
- [ ] 展示差（❌）和好（✅）两种方法
- [ ] 包含现实上下文/设置代码
示例模板
// ✅ 好 - 清晰、完整、准备好适应
interface RetryOptions {
maxAttempts: number;
delayMs: number;
backoff?: 'linear' | 'exponential';
}
async function retryOperation<T>(
operation: () => Promise<T>,
options: RetryOptions
): Promise<T> {
const { maxAttempts, delayMs, backoff = 'linear' } = options;
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
try {
return await operation();
} catch (error) {
if (attempt === maxAttempts) throw error;
const delay = backoff === 'exponential'
? delayMs * Math.pow(2, attempt - 1)
: delayMs * attempt;
await new Promise(resolve => setTimeout(resolve, delay));
}
}
throw new Error('Unreachable');
}
// 用法
const data = await retryOperation(
() => fetchUserData(userId),
{ maxAttempts: 3, delayMs: 1000, backoff: 'exponential' }
);
不要
- ❌ 用5+种语言实现（你擅长移植）
- ❌ 创建填空模板
- ❌ 编写虚构示例
- ❌ 仅展示代码无注释
文件组织
自包含（首选）
打字稿类型安全/
SKILL.md # 所有内容内联
何时使用： 所有内容适合约500词，无需大量参考
带支持文件
api集成/
SKILL.md # 概述 + 模式
重试助手.ts # 可重用代码
示例/
身份验证示例.ts
分页示例.ts
何时使用： 需要可重用工具或多个完整示例
带大量参考
aws-sdk/
SKILL.md # 概述 + 工作流
s3-api.md # 600行API参考
lambda-api.md # 500行API参考
何时使用： 参考材料 > 100行
令牌效率
技能加载到每个对话中。保持简洁。
目标限制
- SKILL.md：保持在500行以下
- 入门工作流：<150词
- 频繁加载技能：总计<200词
- 其他技能：<500词
- 文件 > 100行：包含目录
挑战每条信息：“Claude真的需要这个解释吗？”
压缩技术
# ❌ 差 - 冗长（42词）
你的合作伙伴问："我们之前如何处理React Router中的身份验证错误？"
你应该回答："我将搜索过去对话中的React Router身份验证模式。"
然后派遣子代理搜索查询："React Router身份验证错误处理 401"
# ✅ 好 - 简洁（20词）
伙伴："我们之前如何处理React Router中的身份验证错误？"
你：搜索中...
[派遣子代理 → 合成]
技术：
- 参考工具
--help而非记录所有标志 - 交叉引用其他技能而非重复内容
- 展示模式的最小示例
- 消除冗余
- 使用渐进式披露（根据需要引用其他文件）
- 按领域组织内容以聚焦上下文
工作流建议
对于多步骤流程，包含：
- 清晰顺序步骤：将复杂任务分解为编号操作
- 反馈循环：构建验证/确认步骤
- 错误处理：出错时检查什么
- 清单：对于多步骤或易遗漏细节的流程
示例结构：
## 工作流
1. **准备**
- 检查先决条件
- 验证环境
2. **执行**
- 步骤1：[操作 + 预期结果]
- 步骤2：[操作 + 预期结果]
3. **验证**
- [ ] 检查1通过
- [ ] 检查2通过
4. **回滚**（如果需要）
- 撤销更改的步骤
常见错误
| 错误 | 失败原因 | 修复 |
|---|---|---|
| 叙事性示例 | “在2025-10-03会话中…” | 专注于可重用模式 |
| 多语言稀释 | 5种语言的相同示例 | 一个优秀示例 |
| 流程图中的代码 | step1 [label="导入fs"] |
使用markdown代码块 |
| 通用标签 | helper1, helper2, step3 | 使用语义名称 |
| 缺少描述触发条件 | “用于测试” | “使用场景：测试不稳定时…” |
| 第一人称描述 | “我帮你…” | “使用场景… - 提供…” |
| 深度嵌套文件引用 | 多个@符号，复杂路径 | 保持引用简单直接 |
| Windows风格文件路径 | C:\path\to\file |
使用正斜杠 |
| 提供太多选项 | 10种不同方法 | 专注于一种经过验证的方法 |
| 推卸错误处理 | “Claude会解决” | 在脚本中包含明确的错误处理 |
| 时间敏感信息 | “截至2025年…” | 保持内容常青 |
| 不一致术语 | 随机混合同义词 | 始终使用一致术语 |
流程图使用
仅用于：
- 非明显决策点
- 可能过早停止的流程循环
- "何时使用A与B"决策
绝不用于：
- 参考材料 → 使用表格/列表
- 代码示例 → 使用markdown块
- 线性指令 → 使用编号列表
交叉引用技能
# ✅ 好 - 仅名称，要求明确
**必需：** 使用超能力：测试驱动开发 然后继续
**推荐：** 参见打字稿类型安全 以获取正确的类型守卫
# ❌ 差 - 不清楚是否必需
参见技能/测试/测试驱动开发
# ❌ 差 - 强制加载文件，浪费上下文
@技能/测试/测试驱动开发/SKILL.md
高级实践
迭代开发
最佳方法：与Claude迭代开发技能
- 从最小可行技能开始
- 用真实用例测试
- 根据有效内容优化
- 移除不增加价值的内容
先构建评估
在广泛文档化之前：
- 创建测试场景
- 确定好的标准
- 记录经过验证的模式
- 跳过理论改进
实用脚本
为了可靠性，提供：
- 具有明确错误处理的脚本（不要将错误推迟给Claude）
- 成功/失败的退出代码
- 清晰的错误消息
- 用法示例
- 明确列出所需依赖项
示例：
#!/bin/bash
set -e # 出错时退出
if [ ! -f "config.json" ]; then
echo "错误：未找到config.json" >&2
exit 1
fi
# 脚本逻辑在此
echo "成功"
exit 0
可验证的中间输出
对于复杂操作，创建验证检查点：
- 让Claude生成结构化计划文件
- 用脚本验证计划
- 仅在验证通过后执行
这能在错误复合前捕获它们。
结构化输出模板
当技能产生一致格式时：
## 输出模板
\`\`\`typescript
interface ExpectedOutput {
status: 'success' | 'error';
data: YourDataType;
errors?: string[];
}
\`\`\`
**用法**：复制并适应你的上下文
技能创建清单
编写前：
- [ ] 技术不明显或别处有良好文档
- [ ] 模式广泛适用（非项目特定）
- [ ] 我会在多个项目中参考这个
前置元数据：
- [ ] 名称仅使用字母、数字、连字符
- [ ] 描述以"使用场景…"开头
- [ ] 描述包含触发条件和技能作用
- [ ] 描述是第三人称
- [ ] 前置元数据总计 < 1024字符
内容：
- [ ] 概述说明核心原则（1-2句话）
- [ ] "何时使用"部分包含症状
- [ ] 常见操作的快速参考表
- [ ] 一个优秀代码示例（如果是技术技能）
- [ ] 常见错误部分
- [ ] 贯穿全文的关键词以便搜索
质量：
- [ ] 词数适合频率（见上述目标）
- [ ] SKILL.md在500行以下
- [ ] 无叙事性故事
- [ ] 流程图仅用于非明显决策
- [ ] 仅在需要时使用支持文件（100+行参考）
- [ ] 交叉引用使用技能名称，而非文件路径
- [ ] 无时间敏感信息
- [ ] 始终使用一致术语
- [ ] 具体示例（非模板）
- [ ] 自由度与任务复杂性匹配
测试：
- [ ] 用Claude Haiku、Sonnet和Opus测试（对Opus有效的指令可能需要更多细节给Haiku）
- [ ] 用子代理场景测试（如果是纪律执行技能）
- [ ] 解决常见合理化问题
- [ ] 包含危险信号列表
目录结构
技能/
技能名称/
SKILL.md # 必需
支持文件.* # 可选
示例/ # 可选
示例1.ts
脚本/ # 可选
助手.py
扁平命名空间 - 所有技能在一个可搜索目录中
实际影响
好技能：
- 未来Claude快速找到它们（CSO优化）
- 几秒钟内可扫描（快速参考）
- 提供清晰可操作的示例
- 防止重复相同研究
- 保持在500行以下（令牌高效）
- 将特异性与任务需求匹配（正确的自由度）
差技能：
- 被忽略（模糊描述）
- 评估时间过长（无快速参考）
- 留下理解空白（无示例）
- 浪费令牌预算（冗长解释明显事物）
- 过度约束创造性任务或对关键操作规范不足
- 包含时间敏感或过时信息
记住： 技能是为未来的Claude，不是为当前的你。为可发现性、扫描性和可操作性优化。
黄金法则： 默认假设Claude已经非常聪明。只添加Claude没有的上下文。