1. 引言：什么是 Claude Code Skill

Claude Code 是 Anthropic 推出的 AI 编程助手，面向代码理解、修改、调试和项目级协作等开发场景进行了深度优化。而 Skill（技能） 是 Claude Code 中用于扩展模型能力的一种机制，它允许你为 Claude 预置一组指令、示例和上下文，让它在特定任务上表现得更加专业和稳定。

简单来说，Skill 就像给 Claude 装上一个「专业插件」：当任务匹配到某个 Skill 时，Claude 会自动加载对应的提示词和资源，从而按照你期望的方式完成工作。本文将从零开始，手把手带你编写、调试并发布一个属于自己的 Claude Code Skill。

2. 准备工作：环境与目录结构

在开始编写 Skill 之前，需要先确认你的开发环境满足以下条件：

• Claude Code 已安装：确保本机已安装并登录 Claude Code，版本建议为最新稳定版。
• Node.js 环境：部分 Skill 调试工具依赖 Node.js，建议安装 18 及以上版本。
• Git：用于版本管理和后续发布。

一个标准的 Skill 目录结构如下：

my-skill/
├── SKILL.md          # 技能定义文件（核心）
├── assets/           # 可选：辅助资源（示例代码、模板等）
│   ├── example.js
│   └── template.txt
└── scripts/          # 可选：辅助脚本
    └── helper.py

其中 SKILL.md 是 Skill 的核心定义文件，它使用 Markdown 格式描述技能的用途、触发条件和执行步骤。下面我们逐步创建这个文件。

3. 编写 SKILL.md：核心定义文件

首先在项目目录下创建 SKILL.md 文件。这个文件通常包含以下几个关键部分：

• YAML Frontmatter：定义技能的名称、描述和触发关键词。
• 正文说明：详细描述技能的适用场景、执行步骤和注意事项。
• 示例：给出输入输出示例，帮助 Claude 理解任务。

下面是一个完整的 SKILL.md 示例，我们以「生成单元测试」技能为例：

---
name: unit-test-generator
description: 为指定函数或模块生成高质量的单元测试代码，支持 Jest 和 Mocha 两种框架。
triggers:
  - 生成单元测试
  - 写测试用例
  - unit test
---
单元测试生成器
适用场景
当用户要求为某个函数、类或模块编写单元测试时，使用本技能。
执行步骤
阅读目标源码，理解函数输入、输出和边界条件。
根据用户指定的测试框架（默认 Jest）生成测试文件。
覆盖正常路径、异常路径和边界条件。
输出测试代码，并附上简要说明。
注意事项
测试代码必须可独立运行，不依赖未安装的依赖包。
对于异步函数，必须使用 async/await 或 Promise 处理。
测试命名遵循 should_xxx 风格。
示例
输入：
function add(a, b) {
  return a + b;
}
输出：
describe('add', () => {
  it('should return sum of two numbers', () => {
    expect(add(1, 2)).toBe(3);
  });
});

注意：Frontmatter 中的 name 必须是唯一的技能标识，description 用于让 Claude 判断何时调用该技能，triggers 是可选的触发词列表，可以帮助提高匹配准确率。

4. 添加辅助资源：assets 目录

很多 Skill 需要配合模板、示例代码或配置文件使用。这些资源可以放在 assets/ 目录下，并在 SKILL.md 中引用它们。

例如，我们创建一个 assets/test-template.js 作为测试模板：

const { describe, it, expect } = require('@jest/globals');
describe('MODULE_NAME', () => {
it('should EXPECTED_BEHAVIOR', () => {
// TODO: 实现测试逻辑
});
});

然后在 SKILL.md 中引用该模板：

## 模板引用
当生成测试文件时，优先使用 assets/test-template.js 作为基础模板，并替换其中的占位符。

这样，Claude 在执行技能时就会自动读取模板文件，并基于它生成符合规范的测试代码。

5. 编写辅助脚本：scripts 目录

有些 Skill 需要执行本地命令或处理文件，这时可以在 scripts/ 目录下编写辅助脚本。Claude Code 允许 Skill 调用这些脚本，但需要遵循安全规范。

例如，我们创建一个 scripts/validate-test.js 用于校验生成的测试文件是否能通过语法检查：

const { execSync } = require('child_process');
const fs = require('fs');
const filePath = process.argv[2];
if (!filePath) {
console.error('Usage: node validate-test.js <file>');
process.exit(1);
}
try {
execSync(node --check ${filePath}, { stdio: 'pipe' });
console.log('✅ 语法检查通过');
} catch (err) {
console.error('❌ 语法错误：', err.stderr.toString());
process.exit(1);
}

在 SKILL.md 中说明脚本的用法：

## 脚本使用
生成测试文件后，运行以下命令校验语法：
```bash
node scripts/validate-test.js <测试文件路径>
```
如果校验失败，请修复语法错误后重新校验。

6. 安装与注册 Skill

编写完成后，需要将 Skill 安装到 Claude Code 的配置目录中。Claude Code 会从以下位置加载 Skill：

• 用户级目录：~/.claude/skills/，对所有项目生效。
• 项目级目录：.claude/skills/，仅对当前项目生效。

以项目级安装为例，在项目根目录执行：

mkdir -p .claude/skills
cp -r my-skill .claude/skills/unit-test-generator

安装完成后，重启 Claude Code 会话，然后输入「生成单元测试」来验证技能是否被正确加载。

7. 调试与验证

Skill 安装后，需要通过实际对话来验证其效果。调试时建议关注以下几点：

• 触发是否准确：检查 Claude 是否在合适的场景下自动加载了技能。
• 输出是否符合预期：验证生成的代码是否遵循了 SKILL.md 中的规范和模板。
• 脚本是否正常执行：如果技能包含辅助脚本，确认脚本能正确运行并返回预期结果。

如果技能没有被触发，可以尝试以下排查方法：

1. 检查 description 是否清晰描述了技能的用途。
2. 在对话中明确提到 triggers 中的关键词。
3. 确认 Skill 目录结构正确，SKILL.md 位于技能目录根目录。

8. 进阶技巧：多步骤工作流

复杂的 Skill 往往需要多步骤协作。你可以在 SKILL.md 中定义清晰的工作流，让 Claude 按顺序执行。

例如，一个「代码审查」技能可以定义如下流程：

## 工作流
1. 读取目标文件，分析代码结构和潜在问题。
2. 检查代码风格、命名规范和注释完整性。
3. 运行静态检查工具（如 ESLint），收集警告和错误。
4. 输出审查报告，按严重程度分类列出问题，并给出修改建议。

通过将复杂任务拆解为多个步骤，可以显著提升 Claude 的执行稳定性和输出质量。

9. 发布与分享

当你完成 Skill 的开发和调试后，可以将其发布到 GitHub 等平台与社区分享。发布时建议包含以下内容：

• README.md：说明技能的用途、安装方法和使用示例。
• 完整的目录结构：确保 SKILL.md、assets/ 和 scripts/ 都包含在仓库中。
• 示例输出：展示技能的实际效果，方便其他用户评估。

一个规范的发布仓库结构如下：

claude-skill-unit-test-generator/
├── README.md
├── SKILL.md
├── assets/
│   └── test-template.js
└── scripts/
    └── validate-test.js

10. 总结

本文从零开始，完整演示了如何编写一个 Claude Code Skill，包括目录结构设计、SKILL.md 编写、辅助资源与脚本的添加、安装调试以及发布分享。核心要点如下：

• SKILL.md 是核心：通过 Frontmatter 定义元信息，通过正文描述执行逻辑。
• 资源与脚本增强能力：assets/ 提供模板，scripts/ 提供可执行逻辑。
• 调试是关键：安装后务必通过实际对话验证触发和输出效果。

掌握了这些方法，你就可以根据自己的开发场景，打造专属的 Claude Code Skill，大幅提升 AI 编程助手的实战效率。