create-skill

创建 Skill 命令

此命令提供创建有效技能的指导。

概述

编写技能就是将测试驱动开发应用于流程文档。

个人技能存放在特定 Agent 的目录中（Claude Code 使用 ~/.claude/skills，Codex 使用 ~/.codex/skills）

编写测试用例（使用子 Agent 设计压力场景），观察测试失败（基准行为），编写技能（文档），观察测试通过（Agent 遵守要求），然后重构（堵住漏洞）。

核心原则： 如果你没有观察过 Agent 在没有技能时失败，就无法确定该技能是否教会了正确做法。

必备背景知识： 使用此技能前，你必须理解测试驱动开发。该技能定义了基本的 RED-GREEN-REFACTOR 循环。此技能将 TDD 应用于文档编写。

官方指南： Anthropic 的官方技能编写最佳实践可通过 /apply-anthropic-skill-best-practices 命令获取，它们会增强 prompt-engineering 技能。请同时使用该技能和这份文档；二者并非重复，而是相辅相成。这些文档提供了额外的模式和指南，与此技能侧重 TDD 的方法相辅相成。

关于技能

技能是模块化、独立的软件包，通过提供专业知识、工作流和工具来扩展 Claude 的能力。可以将它们视为针对特定领域或任务的“入门指南”——它们能将 Claude 从通用 Agent 转变为具备程序性知识的专业 Agent，而这种知识并非任何模型都能完全掌握。

什么是技能？

技能是关于经过验证的技术、模式或工具的参考指南。技能可帮助未来的 Claude 实例找到并应用有效的方法。

技能包括： 可复用的技术、模式、工具和参考指南

技能不包括： 记录你曾经如何解决某个问题的叙述

技能提供什么

1. 专业工作流——针对特定领域的多步骤流程
2. 工具集成——使用特定文件格式或 API 的说明
3. 领域专长——公司特定的知识、架构和业务逻辑
4. 捆绑资源——用于复杂且重复任务的脚本、参考资料和资产

技能的 TDD 映射

TDD 概念	技能创建
测试用例	使用子 Agent 设计的压力场景
生产代码	技能文档（SKILL.md）
测试失败（RED）	Agent 在没有技能时违反规则（基准行为）
测试通过（GREEN）	Agent 在有技能时遵守要求
重构	堵住漏洞，同时保持合规
先编写测试	编写技能前运行基准场景
观察失败	记录 Agent 使用的确切辩解
最少代码	编写针对这些具体违规行为的技能
观察通过	验证 Agent 现在能够遵守要求
重构循环	找出新的辩解 → 堵住漏洞 → 再次验证

整个技能创建过程都遵循 RED-GREEN-REFACTOR。

何时创建技能

适合创建的情况：

• 这项技术对你来说并非直观易懂
• 你会在不同项目中反复参考
• 这种模式适用范围广（并非特定于某个项目）
• 其他人也会从中受益

不适合创建的情况：

• 一次性解决方案
• 其他地方已有充分文档说明的标准实践
• 特定于项目的约定（应写入 CLAUDE.md）

技能类型

技术

包含待遵循步骤的具体方法（condition-based-waiting、root-cause-tracing）

模式

处理问题的思维方式（flatten-with-flags、test-invariants）

参考资料

API 文档、语法指南、工具文档（office docs）

目录结构

skills/
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed

扁平命名空间——所有技能都放在一个可搜索的命名空间中

以下内容应拆分到单独文件：

1. 大量参考资料（100 行以上）——API 文档、完整语法说明
2. 可复用工具——脚本、实用程序、模板

以下内容应保留在主文件中：

• 原则和概念
• 代码模式（少于 50 行）
• 其他所有内容

技能剖析

每项技能都由必需的 SKILL.md 文件和可选的随附资源组成：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必需）

元数据质量： YAML 前置元数据中的 name 和 description 决定 Claude 何时会使用该技能。请具体说明该技能的功能和使用时机。使用第三人称（例如，使用“This skill should be used when...”而非“Use this skill when...”）。

SKILL.md 结构

前置元数据（YAML）：

• 仅支持两个字段：name 和 description
• 总字符数最多为 1024
• name：仅使用字母、数字和连字符（不使用括号或特殊字符）
• description：使用第三人称，同时包含该技能的功能和使用时机
  • 以“Use when...”开头，聚焦触发条件
  • 包含具体症状、情境和上下文
  • 尽可能控制在 500 个字符以内

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms] - [what the skill does and how it helps, written in third person]
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
[Small inline flowchart IF decision non-obvious]

Bullet list with SYMPTOMS and use cases
When NOT to use

## Core Pattern (for techniques/patterns)
Before/after code comparison

## Quick Reference
Table or bullets for scanning common operations

## Implementation
Inline code for simple patterns
Link to file for heavy reference or reusable tools

## Common Mistakes
What goes wrong + fixes

## Real-World Impact (optional)
Concrete results

随附资源（可选）

脚本（scripts/）

用于需要确定性可靠性或会反复重写的任务的可执行代码（Python/Bash 等）。

• 适用情形：相同代码会被反复重写，或需要确定性可靠性时
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.py
• 优点：节省令牌、结果确定，可在不加载到上下文中的情况下执行
• 注意：Claude 可能仍需读取脚本，以进行修补或针对特定环境调整

参考资料（references/）

用于在需要时加载到上下文中，为 Claude 的流程和思考提供依据的文档及参考材料。

• 适用情形：Claude 工作时需要参考的文档
• 示例：财务架构的 references/finance.md、公司 NDA 模板的 references/mnda.md、公司政策的 references/policies.md、API 规范的 references/api_docs.md
• 使用场景：数据库架构、API 文档、领域知识、公司政策、详细的工作流指南
• 优点：让 SKILL.md 保持精简，并仅在 Claude 判断需要时加载
• 最佳实践：如果文件较大（超过 10k 个单词），请在 SKILL.md 中加入 grep 搜索模式
• 避免重复：信息应存放在 SKILL.md 或参考文件中，而不是两者都有。除非详细信息确实是技能的核心内容，否则优先放在参考文件中；这样既能让 SKILL.md 保持精简，也能让信息易于查找，而不会占用过多上下文窗口。SKILL.md 中仅保留必要的操作说明和工作流指导；将详细的参考资料、架构和示例移至参考文件。

资源文件（assets/）

不用于加载到上下文中，而是供 Claude 在生成输出时使用的文件。

• 适用情形：技能需要在最终输出中使用相关文件时
• 示例：品牌资源 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 样板代码 assets/frontend-template/、字体 assets/font.ttf
• 使用场景：模板、图像、图标、样板代码、字体、会被复制或修改的示例文档
• 优点：将输出资源与文档分开，让 Claude 无需加载文件即可使用它们

渐进式披露设计原则

技能采用三级加载系统，以高效管理上下文：

1. 元数据（name + description） - 始终位于上下文中（约 100 个单词）
2. SKILL.md 正文 - 技能触发时加载（少于 5k 个单词）
3. 随附资源 - Claude 按需加载（无限*）

*之所以称为无限，是因为脚本无需读入上下文窗口即可执行。

Claude 搜索优化（CSO）

对内容发现至关重要： 未来的 Claude 需要能够找到你的技能

1. 丰富的描述字段

目的： Claude 会读取描述，以决定针对特定任务加载哪些技能。描述应能回答：“我现在应该阅读这项技能吗？”

格式： 以“适用于……”开头，聚焦触发条件，然后说明它的作用

内容：

• 使用具体的触发条件、症状和情境，表明这项技能适用
• 描述问题（竞态条件、行为不一致），而非特定语言的症状（setTimeout、sleep）
• 除非技能本身具有技术针对性，否则触发条件应与技术无关
• 如果技能具有技术针对性，应在触发条件中明确说明
• 使用第三人称撰写（会注入系统提示词）

# ❌ BAD: Too abstract, vague, doesn't include when to use
description: For async testing

# ❌ BAD: First person
description: I can help you with async tests when they're flaky

# ❌ BAD: Mentions technology but skill isn't specific to it
description: Use when tests use setTimeout/sleep and are flaky

# ✅ GOOD: Starts with "Use when", describes problem, then what it does
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests

# ✅ GOOD: Technology-specific skill with explicit trigger
description: Use when using React Router and handling authentication redirects - provides patterns for protected routes and auth state management

2. 关键词覆盖

使用 Claude 会搜索的词语：

• 错误消息：“Hook timed out”、“ENOTEMPTY”、“race condition”
• 症状：“flaky”、“hanging”、“zombie”、“pollution”
• 同义词：“timeout/hang/freeze”、“cleanup/teardown/afterEach”
• 工具：实际命令、库名称、文件类型

3. 描述性命名

使用主动语态，以动词开头：

• ✅ creating-skills，而不是 skill-creation
• ✅ testing-skills-with-subagents，而不是 subagent-skill-testing

4. 精简 Token（至关重要）

问题： 入门和经常被引用的技能会加载到每一段对话中。每个 Token 都很重要。

目标字数：

• 入门工作流：每项少于 150 个单词
• 经常加载的技能：总计少于 200 个单词
• 其他技能：少于 500 个单词（仍应保持简洁）

技巧：

将详细内容移至工具帮助：

# ❌ BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# ✅ GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.

使用交叉引用：

# ❌ BAD: Repeat workflow details
When searching, dispatch subagent with template...
[20 lines of repeated instructions]

# ✅ GOOD: Reference other skill
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

精简示例：

# ❌ BAD: Verbose example (42 words)
your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

# ✅ GOOD: Minimal example (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]

消除冗余：

• 不要重复交叉引用的技能中已有的内容
• 不要解释命令中显而易见的内容
• 不要为同一种模式提供多个示例

验证：

wc -w skills/path/SKILL.md
# getting-started workflows: aim for <150 each
# Other frequently-loaded: aim for <200 total

根据实际操作或核心见解命名：

• ✅ condition-based-waiting > async-test-helpers
• ✅ using-skills，而不是 skill-usage
• ✅ flatten-with-flags > data-structure-refactoring
• ✅ root-cause-tracing > debugging-techniques

动名词（-ing）适合描述流程：

• creating-skills、testing-skills、debugging-with-logs
• 主动表达你正在执行的操作

4. 交叉引用其他技能

编写引用其他技能的文档时：

仅使用技能名称，并明确标注要求：

• ✅ 正确：**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development
• ✅ 正确：**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging
• ❌ 错误：See skills/testing/test-driven-development（未说明是否为必需）
• ❌ 错误：@skills/testing/test-driven-development/SKILL.md（会强制加载，消耗上下文）

为何不用 @ 链接： @ 语法会立即强制加载文件，在你需要之前就消耗 200k+ 上下文。

流程图的使用

digraph when_flowchart {
    "Need to show information?" [shape=diamond];
    "Decision where I might go wrong?" [shape=diamond];
    "Use markdown" [shape=box];
    "Small inline flowchart" [shape=box];

    "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
    "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
    "Decision where I might go wrong?" -> "Use markdown" [label="no"];
}

仅在以下情况使用流程图：

• 不明显的决策点
• 可能过早停止的流程循环
• “何时使用 A 而非 B”这类决策

以下情况绝不要使用流程图：

• 参考资料 → 表格、列表
• 代码示例 → Markdown 代码块
• 线性说明 → 编号列表
• 不具备语义含义的标签（step1、helper2）

图形样式规则请参见 graphviz-conventions.dot。

代码示例

一个出色的示例胜过许多平庸的示例

选择最相关的语言：

• 测试技术 → TypeScript/JavaScript
• 系统调试 → Shell/Python
• 数据处理 → Python

优秀示例应：

• 完整且可运行
• 注释清晰，解释原因
• 源自真实场景
• 清晰展示模式
• 可直接改编（而非通用模板）

不要：

• 用 5 种以上语言实现
• 创建需要填空的模板
• 编写牵强的示例

你擅长移植内容——一个出色的示例就够了。

文件组织

自包含技能

defense-in-depth/
  SKILL.md    # Everything inline

适用情况：所有内容都能容纳其中，无需大量参考资料

可复用工具技能

condition-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt

适用场景：工具是可复用的代码，而不只是叙述内容

大量参考资料技能

pptx/
  SKILL.md       # Overview + workflows
  pptxgenjs.md   # 600 lines API reference
  ooxml.md       # 500 lines XML structure
  scripts/       # Executable tools

适用场景：参考资料太多，无法内嵌

铁律（与 TDD 相同）

测试所有技能类型

不同技能类型需要采用不同的测试方法：

强化纪律的技能（规则／要求）

示例： TDD、完成前验证、先设计再编码

测试方法：

• 理论问题：他们是否理解规则？
• 压力场景：他们在压力下是否遵守规则？
• 多重压力叠加：时间 + 沉没成本 + 疲惫
• 找出合理化借口并加入明确的反驳

成功标准： Agent 在最大压力下仍遵守规则

技术技能（操作指南）

示例： 基于条件的等待、根因追踪、防御式编程

测试方法：

• 应用场景：他们能否正确应用该技术？
• 变化场景：他们能否处理边缘情况？
• 信息缺失测试：说明中是否存在漏洞？

成功标准： Agent 能成功将该技术应用于新场景

模式技能（思维模型）

示例： 降低复杂度、信息隐藏概念

测试方法：

• 识别场景：他们能否识别何时适用该模式？
• 应用场景：他们能否运用该思维模型？
• 反例：他们是否知道何时不该应用？

成功标准： Agent 能正确判断何时以及如何应用该模式

参考技能（文档／API）

示例： API 文档、命令参考、库指南

测试方法：

• 检索场景：他们能否找到正确的信息？
• 应用场景：他们能否正确使用找到的信息？
• 覆盖缺口测试：常见用例是否都已涵盖？

成功标准： Agent 能找到参考信息并正确应用

防止技能被合理化借口钻空子

强化纪律的技能（如 TDD）需要抵御合理化借口。Agent 很聪明，在压力之下会寻找漏洞。

心理学说明： 了解说服技巧为何有效，有助于你系统地运用这些技巧。有关权威、承诺、稀缺性、社会认同和统一性原则的研究基础，请参阅 persuasion-principles.md（Cialdini，2021；Meincke 等人，2025）。

明确堵住每一个漏洞

不要只陈述规则——还要禁止具体的规避方式：

```markdown Write code before test? Delete it. ``` ```markdown Write code before test? Delete it. Start over.

No exceptions:

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

</Good>

### 回应“重精神而非重字面”的论点

尽早加入基础原则：

```markdown
**Violating the letter of the rules is violating the spirit of the rules.**

这能堵住一整类“我是在遵循精神”的合理化借口。

制作合理化借口表

记录基准测试中的合理化借口（见下文“测试”部分）。Agent 提出的每一个借口都要放进表中：

| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |

创建警示信号列表

让 Agent 能轻松自查是否正在找借口：

## Red Flags - STOP and Start Over

- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."

**All of these mean: Delete code. Start over with TDD.**

在 CSO 中加入违规征兆

在描述中添加你即将违反规则时的征兆：

description: use when implementing any feature or bugfix, before writing implementation code

技能的 RED-GREEN-REFACTOR 流程

遵循 TDD 循环：

RED：编写失败的测试（基准测试）

在不使用该技能的情况下，让子 Agent 执行压力场景。记录具体表现：

• 他们做出了哪些选择？
• 他们用了哪些合理化借口（逐字记录）？
• 哪些压力导致了违规？

这就是“观察测试失败”——编写技能之前，必须先观察 Agent 自然会怎么做。

GREEN：编写最精简的技能

编写能够解决这些具体合理化借口的技能。不要为假设情形添加额外内容。

使用该技能重新运行相同场景。Agent 此时应当遵守规则。

REFACTOR：堵住漏洞

Agent 找到了新的合理化借口？加入明确的反驳。重复测试，直到技能无懈可击。

必需的子技能： 使用 superpowers:testing-skills-with-subagents 获取完整的测试方法：

• 如何编写压力场景
• 压力类型（时间、沉没成本、权威、疲惫）
• 系统性地堵住漏洞
• 元测试技巧

反模式

❌ 叙事性示例

“在 2025-10-03 的会话中，我们发现空的 projectDir 导致了……” **为什么不好：**过于具体，无法复用

❌ 多语言稀释

example-js.js、example-py.py、example-go.go **为什么不好：**质量平平，维护负担重

❌ 流程图中的代码

step1 [label="import fs"];
step2 [label="read file"];

**为什么不好：**无法复制粘贴，难以阅读

❌ 通用标签

helper1、helper2、step3、pattern4 **为什么不好：**标签应具有语义

停下：进入下一个技能前

编写任何技能后，都必须停下来并完成部署流程。

不要：

• 不经测试就批量创建多个技能
• 当前技能尚未验证就进入下一个技能
• 因为“批量处理更高效”而跳过测试

以下部署检查清单对每个技能都属强制要求。

部署未经测试的技能，就等于部署未经测试的代码。这违反了质量标准。

技能创建检查清单（经 TDD 调整）

重要：使用 TodoWrite 为以下每个检查清单项目创建待办事项。

RED 阶段——编写失败测试：

• 创建压力场景（对于纪律类技能，至少结合 3 种压力）
• 在不使用技能的情况下运行场景——逐字记录基线行为
• 找出合理化借口／失败中的模式

GREEN 阶段——编写最小化技能：

• 名称仅使用字母、数字和连字符（不含括号／特殊字符）
• YAML frontmatter 仅包含 name 和 description（最多 1024 个字符）
• 描述以“Use when...”开头，并包含具体的触发条件／症状
• 使用第三人称撰写描述
• 在全文中使用便于搜索的关键词（错误、症状、工具）
• 提供清晰的概述和核心原则
• 针对 RED 阶段发现的具体基线失败
• 代码内嵌，或链接到单独的文件
• 提供一个出色的示例（而非多语言示例）
• 使用技能运行场景——验证 Agent 现在会遵守要求

REFACTOR 阶段——堵住漏洞：

• 找出测试中出现的新合理化借口
• 添加明确的反制措施（如果是纪律类技能）
• 根据所有测试迭代创建合理化借口表
• 创建警示信号列表
• 反复重新测试，直到无懈可击

质量检查：

• 仅在决策不明显时使用小型流程图
• 提供快速参考表
• 包含常见错误部分
• 不讲述叙事性故事
• 仅在工具或参考资料内容庞大时提供辅助文件

部署：

• 将技能提交到 git，并推送到你的 fork（如果已配置）
• 如果具有广泛用途，可考虑通过 PR 回馈社区

发现工作流

未来的 Claude 会这样找到你的技能：

1. 遇到问题（“测试不稳定”）
2. 找到 SKILL（描述与问题匹配）
3. 浏览概述（是否相关？）
4. 查看模式（快速参考表）
5. 加载示例（仅在实际实施时）

针对这一工作流进行优化——尽早并反复加入便于搜索的术语。

核心要点

创建技能就是对流程文档实施 TDD。

同一条铁律：没有先失败的测试，就不创建技能。 同一套循环：RED（基线）→ GREEN（编写技能）→ REFACTOR（堵住漏洞）。 同样的好处：质量更高、意外更少、结果无懈可击。

如果你对代码采用 TDD，也应对技能采用 TDD。这是将同一套纪律应用于文档。

技能创建流程

创建技能时，请按顺序遵循“技能创建流程”，只有在明确不适用时才跳过相应步骤。

步骤 1：通过具体示例理解技能

仅当你已清楚了解技能的使用模式时，才可跳过此步骤。即使使用现有技能，此步骤仍然很有价值。

要创建有效的技能，需要清楚了解技能的具体使用方式。这种了解可以来自用户直接提供的示例，也可以来自经过用户反馈验证后生成的示例。

例如，在构建图像编辑器技能时，相关问题包括：

• “图像编辑器技能应支持哪些功能？编辑、旋转，还有其他功能吗？”
• “你能举一些使用此技能的例子吗？”
• “我能想到用户可能会提出诸如‘去掉这张图片中的红眼’或‘旋转这张图片’之类的要求。你觉得还有哪些使用方式？”
• “用户说什么时应该触发此技能？”

为避免让用户应接不暇，不要在一条消息中提出太多问题。先提出最重要的问题，再根据需要继续追问，以提高效果。

当你清楚了解此技能应支持哪些功能时，即可结束此步骤。

步骤 2：规划可复用的技能内容

要将具体示例转化为有效的技能，请逐一分析每个示例：

1. 考虑如何从头开始完成该示例
2. 确定反复执行这些工作流时，哪些脚本、参考资料和资源会有所帮助

示例：构建一个用于处理“帮我旋转这个 PDF”等请求的 pdf-editor 技能时，分析结果表明：

1. 每次旋转 PDF 都需要重新编写相同的代码
2. 将 scripts/rotate_pdf.py 脚本存放在技能中会很有帮助

示例：设计一个用于处理“帮我做一个待办事项应用”或“帮我做一个追踪步数的仪表盘”等请求的 frontend-webapp-builder 技能时，分析结果表明：

1. 编写前端 Web 应用时，每次都需要相同的 HTML/React 样板代码
2. 将包含样板 HTML/React 项目文件的 assets/hello-world/ 模板存放在技能中会很有帮助

示例：构建一个用于处理“今天有多少用户登录过？”等请求的 big-query 技能时，分析结果表明：

1. 每次查询 BigQuery 都需要重新查找表架构及其关系
2. 将记录表架构的 references/schema.md 文件存放在技能中会很有帮助

要确定技能包含的内容，请分析每个具体示例，并列出要纳入的可复用资源：脚本、参考资料和资源文件。

步骤 3：创建技能目录

如果技能已存在且只需迭代，则跳过此步骤。

创建技能目录和必需文件：

1. 创建技能文件夹：mkdir -p skills/<skill-name>
2. 使用 YAML frontmatter 创建 SKILL.md：

---
name: skill-name
description: Use when [triggering conditions] - [what the skill does]
---

# Skill Name

## Critical Guidlines
[Core principle in 1-2 sentences. Each start wit "You MUST ..."]

## How to Use
[Think in steps, use problem decomposition, etc.]

## Guide
[Procedures, patterns]

## Examples
[Examples of how to use the skill, include agent input and output]

## Troubleshooting
[Common mistakes and how to avoid them]

## Resources
[Scripts, references, assets]

3. 仅在需要时添加资源子目录：
   • scripts/ — 可复用的可执行代码
   • references/ — 按需加载的文档
   • assets/ — 用于输出的文件（模板、图片）

步骤 4：编辑技能

编辑（新生成或现有的）技能时，请记住，该技能是为另一个 Claude 实例使用而创建的。重点添加对 Claude 有帮助且不显而易见的信息。考虑哪些流程知识、领域特定细节或可复用资源能帮助另一个 Claude 实例更有效地完成这些任务。

从可复用的技能内容开始

开始实施时，先处理上面确定的可复用资源：scripts/、references/ 和 assets/ 文件。请注意，此步骤可能需要用户提供输入。例如，在实施 brand-guidelines 技能时，用户可能需要提供要存放在 assets/ 中的品牌资源或模板，或要存放在 references/ 中的文档。

移除技能不需要的资源子目录。大多数技能只需要 SKILL.md。

更新 SKILL.md

写作风格： 整个技能说明使用祈使式／不定式（动词开头的指令）撰写，不使用第二人称。使用客观、指导性语言（例如，使用“要完成 X，请执行 Y”，而不是“你应该执行 X”或“如果你需要执行 X”）。这样可以让内容对 AI 更一致、更清晰。

完成 SKILL.md 时，回答以下问题：

1. 用几句话说明该技能的用途。
2. 说明何时应使用该技能。
3. 说明 Claude 在实践中应如何使用该技能。引用以上编写的所有可复用技能内容，让 Claude 知道如何使用它们。

第 5 步：验证技能

部署前，确认技能符合以下要求：

1. Frontmatter — YAML 仅包含 name 和 description（总长度不超过 1024 个字符）
2. 名称 — 仅使用字母、数字和连字符
3. 描述 — 以“Use when...”开头，使用第三人称撰写，并包含具体触发条件
4. 结构 — SKILL.md 位于 skills/<skill-name>/SKILL.md
5. 资源 — 确认所有引用的脚本、参考资料或资源文件均存在于声明的路径下

第 6 步：迭代

测试技能后，用户可能会要求改进。通常，这会在使用技能后立即发生，此时用户对技能的表现仍有清晰印象。

迭代工作流：

1. 在实际任务中使用该技能
2. 留意遇到的困难或效率低下之处
3. 找出需要更新的 SKILL.md 或捆绑资源
4. 实施更改并再次测试