创建技能指南Skill creating-skills

---

name: creating-skills description: 当创建新的Claude Code技能或改进现有技能时使用 - 通过适当的结构、CSO优化和真实示例确保技能可发现、可扫描且有效

创建技能

概述

技能是经过验证的技术、模式或工具的参考指南。 编写它们是为了帮助未来的Claude实例快速找到并应用有效的方法。

技能必须是可发现的（Claude能找到它们）、可扫描的（快速评估）和可操作的（清晰的示例）。

核心原则：默认假设Claude已经非常聪明。只添加Claude没有的上下文。

何时使用

创建技能当：

• 技术不是直观明显的
• 模式广泛适用于多个项目
• 你会再次参考这个
• 其他人会受益

不要为以下情况创建：

• 针对单个项目的临时解决方案
• 其他地方有良好文档的标准实践
• 项目约定（把这些放在.claude/CLAUDE.md中）

必需结构

前言（YAML）

---
name: skill-name-with-hyphens
description: 当[触发条件/症状]时使用 - [它做什么以及如何帮助]
tags: relevant-tags
---

规则：

• 仅支持name和description字段（总计最多1024字符）
• 名称：仅字母、数字、连字符（最多64字符）。使用动名词形式（动词+ing）
• 避免保留词：名称中不要使用"anthropic"、“claude”
• 描述：第三人称，以"当…时使用"开头（最多1024字符）
• 同时包含触发条件AND技能做什么
• 将特异性与任务复杂性匹配（自由度）

文档结构

# 技能名称

## 概述
1-2句话的核心原则。这是什么？

## 何时使用
- 包含症状和使用场景的要点列表
- 何时不使用

## 快速参考
常见操作的表格或要点

## 实现
简单模式的内联代码
对于重型参考（100+行）链接到单独文件

## 常见错误
什么会出错 + 如何修复

## 实际影响（可选）
使用此技术后的具体结果

自由度

将特异性与任务复杂性匹配：

• 高自由度：需要判断的灵活任务

  • 使用广泛的指导、原则、示例
  • 让Claude根据上下文调整方法
  • 示例：“设计API时使用 - 提供REST原则和模式”

• 低自由度：脆弱或关键操作

  • 明确具体步骤
  • 包含验证检查
  • 示例：“部署到生产环境时使用 - 遵循包含回滚程序的确切部署清单”

危险信号：如果技能在创造性任务上过度约束Claude，降低特异性。如果技能在关键操作上过于模糊，添加明确步骤。

Claude搜索优化（CSO）

关键： 未来的Claude读取描述来决定技能是否相关。为发现优化。

描述最佳实践

# ❌ 差 - 太模糊，没提到何时使用
description: 用于异步测试

# ❌ 差 - 第一人称（注入到系统提示中）
description: 我帮你处理不稳定测试

# ✅ 好 - 触发条件 + 做什么
description: 当测试有竞争条件或通过/失败不一致时使用 - 用条件轮询替换任意超时以实现可靠的异步测试

# ✅ 好 - 技术特定且明确触发
description: 使用React Router并处理身份验证重定向时使用 - 提供受保护路由和身份验证状态管理模式

关键词覆盖

使用Claude会搜索的词语：

• 错误消息：“ENOENT”、“Cannot read property”、“Timeout”
• 症状：“不稳定”、“挂起”、“竞争条件”、“内存泄漏”
• 同义词：“清理/拆卸/afterEach”、“超时/挂起/冻结”
• 工具：实际命令名称、库名称、文件类型

命名约定

使用动名词形式（动词+ing）：

• ✅ creating-skills 而不是 skill-creation
• ✅ testing-with-subagents 而不是 subagent-testing
• ✅ debugging-memory-leaks 而不是 memory-leak-debugging
• ✅ processing-pdfs 而不是 pdf-processor
• ✅ analyzing-spreadsheets 而不是 spreadsheet-analysis

为什么动名词有效：

• 描述你正在采取的行动
• 主动且清晰
• 与Anthropic约定一致

避免：

• ❌ 模糊名称如"Helper"或"Utils"
• ❌ 被动语态结构

代码示例

一个优秀示例胜过许多平庸示例。

根据用例选择语言

• 测试技术 → 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+种语言实现（你擅长移植）
• ❌ 创建填空模板
• ❌ 编写虚构示例
• ❌ 只展示代码没有注释

文件组织

自包含（首选）

typescript-type-safety/
  SKILL.md    # 所有内容内联

何时： 所有内容适合约500字，不需要重型参考

带支持文件

api-integration/
  SKILL.md           # 概述 + 模式
  retry-helpers.ts   # 可重用代码
  examples/
    auth-example.ts
    pagination-example.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 authentication error handling 401"

# ✅ 好 - 简洁（20字）
伙伴："我们以前在React Router中如何处理身份验证错误？"
你：搜索中...
[派遣子代理 → 合成]

技术：

• 参考工具--help而不是记录所有标志
• 交叉引用其他技能而不是重复内容
• 展示模式的最小示例
• 消除冗余
• 使用渐进式披露（根据需要引用其他文件）
• 按领域组织内容以聚焦上下文

工作流程建议

对于多步骤流程，包括：

1. 清晰的顺序步骤：将复杂任务分解为编号操作
2. 反馈循环：构建验证/确认步骤
3. 错误处理：出错时检查什么
4. 清单：对于多步骤或容易遗漏细节的流程

示例结构：

## 工作流程

1. **准备**
   - 检查先决条件
   - 验证环境

2. **执行**
   - 步骤1：[动作 + 预期结果]
   - 步骤2：[动作 + 预期结果]

3. **验证**
   - [ ] 检查1通过
   - [ ] 检查2通过

4. **回滚**（如果需要）
   - 撤销更改的步骤

常见错误

错误	为什么失败	修复
叙述性示例	“在2025-10-03的会话中…”	专注于可重用模式
多语言稀释	5种语言的相同示例	一个优秀示例
流程图中的代码	step1 [label="import fs"]	使用markdown代码块
通用标签	helper1, helper2, step3	使用语义名称
缺少描述触发条件	“用于测试”	“当测试不稳定时使用…”
第一人称描述	“我帮你…”	“当…时使用 - 提供…”
深层嵌套文件引用	多个@符号，复杂路径	保持引用简单直接
Windows风格文件路径	C:\path\to\file	使用正斜杠
提供太多选项	10种不同方法	专注于一种经过验证的方法
推卸错误处理	“Claude会解决”	在脚本中包含明确的错误处理
时间敏感信息	“截至2025年…”	保持内容常青
不一致的术语	随机混合同义词	始终使用一致的术语

流程图使用

仅用于：

• 非明显的决策点
• 你可能过早停止的流程循环
• "何时使用A vs B"决策

绝不用于：

• 参考材料 → 使用表格/列表
• 代码示例 → 使用markdown块
• 线性说明 → 使用编号列表

交叉引用技能

# ✅ 好 - 仅名称，有明确要求
**必需：** 在继续之前使用superpowers:test-driven-development

**推荐：** 查看typescript-type-safety以获取适当的类型守卫

# ❌ 差 - 不清楚是否必需
参见skills/testing/test-driven-development

# ❌ 差 - 强制加载文件，浪费上下文
@skills/testing/test-driven-development/SKILL.md

高级实践

迭代开发

最佳方法：与Claude一起迭代开发技能

1. 从最小可行技能开始
2. 用真实用例测试
3. 根据有效内容优化
4. 移除没有增加价值的内容

先构建评估

在广泛文档化之前：

1. 创建测试场景
2. 确定好的样子
3. 记录经过验证的模式
4. 跳过理论改进

实用脚本

为了可靠性，提供：

• 具有明确错误处理的脚本（不要将错误推迟给Claude）
• 成功/失败的退出代码
• 清晰的错误消息
• 用法示例
• 明确列出所需依赖项

示例：

#!/bin/bash
set -e  # 出错时退出

if [ ! -f "config.json" ]; then
  echo "错误：未找到config.json" >&2
  exit 1
fi

# 脚本逻辑在此处
echo "成功"
exit 0

可验证的中间输出

对于复杂操作，创建验证检查点：

1. 让Claude生成结构化计划文件
2. 用脚本验证计划
3. 仅在验证通过后执行

这可以在错误复合之前捕获它们。

结构化输出模板

当技能产生一致格式时：

## 输出模板

\`\`\`typescript
interface ExpectedOutput {
  status: 'success' | 'error';
  data: YourDataType;
  errors?: string[];
}
\`\`\`

**用法**：复制并适应你的上下文

技能创建清单

编写前：

• [ ] 技术不明显或没有在其他地方良好文档化
• [ ] 模式广泛适用（非项目特定）
• [ ] 我会在多个项目中参考这个

前言：

• [ ] 名称仅使用字母、数字、连字符
• [ ] 描述以"当…时使用"开头
• [ ] 描述包含触发条件AND技能做什么
• [ ] 描述是第三人称
• [ ] 总前言 < 1024字符

内容：

• [ ] 概述陈述核心原则（1-2句话）
• [ ] "何时使用"部分包含症状
• [ ] 常见操作的快速参考表
• [ ] 一个优秀代码示例（如果是技术技能）
• [ ] 常见错误部分
• [ ] 整个文档包含搜索关键词

质量：

• [ ] 字数适合频率（见上面目标）
• [ ] SKILL.md在500行以下
• [ ] 没有叙述性故事
• [ ] 流程图仅用于非明显决策
• [ ] 仅在需要时使用支持文件（100+行参考）
• [ ] 交叉引用使用技能名称，而不是文件路径
• [ ] 没有时间敏感信息
• [ ] 整个文档术语一致
• [ ] 具体示例（非模板）
• [ ] 自由度与任务复杂性匹配

测试：

• [ ] 用Claude Haiku、Sonnet和Opus测试（对Opus有效的指令可能需要更多细节给Haiku）
• [ ] 用子代理场景测试（如果是纪律执行技能）
• [ ] 解决常见合理化
• [ ] 包含危险信号列表

目录结构

skills/
  skill-name/
    SKILL.md              # 必需
    supporting-file.*     # 可选
    examples/             # 可选
      example1.ts
    scripts/              # 可选
      helper.py

扁平命名空间 - 所有技能在一个可搜索目录中

实际影响

好技能：

• 未来的Claude快速找到它们（CSO优化）
• 几秒钟内可扫描（快速参考）
• 提供清晰的可操作示例
• 防止重复相同的研究
• 保持在500行以下（令牌高效）
• 匹配任务需求的特异性（正确的自由度）

差技能：

• 被忽略（模糊描述）
• 评估时间太长（没有快速参考）
• 留下理解空白（没有示例）
• 浪费令牌预算（冗长的明显事物解释）
• 过度约束创造性任务或对关键操作规定不足
• 包含时间敏感或过时信息

---

记住： 技能是为未来的Claude准备的，不是当前的你。为发现、扫描和行动优化。

黄金法则： 默认假设Claude已经非常聪明。只添加Claude没有的上下文。