Claude Code Skills 入门指南：让你的 AI 助手更强大
你是否曾经想过，如果 Claude 能记住你的项目规范、自动执行特定任务，或者在你需要时自动提供帮助，那该多好？好消息是，Claude Code 的技能（Skills）功能就能帮你实现这些想法！
想象一下，你正在和 Claude 一起工作，突然想到："如果 Claude 能按照我们团队的代码风格来写代码就好了。"或者"如果 Claude 能自动帮我部署应用就好了。"这些都不是梦想，通过创建技能，你可以让 Claude 变得更智能、更懂你。
今天，我想和你分享如何创建你的第一个技能。别担心，这比你想象的要简单得多。我们从一个最简单的例子开始，一步步带你走进技能的世界。
什么是技能？
简单来说，技能就是告诉 Claude "怎么做"的说明书。就像你教一个新同事如何按照公司规范写代码一样，技能就是教 Claude 如何按照你的需求工作。
技能的核心是一个叫做 SKILL.md 的文件。这个文件包含两部分：
- 前置元数据：告诉 Claude 什么时候使用这个技能
- 说明内容：告诉 Claude 具体怎么做
听起来是不是很简单？确实如此！让我用一个真实的例子来展示给你看。
最小示例：创建一个代码解释技能
假设你经常需要 Claude 帮你解释代码，但每次都要重复说"用图表和类比来解释"，是不是很麻烦？让我们创建一个技能，让 Claude 自动知道如何解释代码。
第一步：创建技能目录
首先，我们需要在合适的位置创建技能目录。个人技能存放在 ~/.claude/skills/ 目录下，这样你所有的项目都能使用它。
打开终端，运行：
mkdir -p ~/.claude/skills/explain-code
这一步就像在你的工具箱里新建一个抽屉，专门用来存放"代码解释"这个工具。
第二步：编写 SKILL.md 文件
现在，让我们创建技能的核心文件。在刚才创建的目录下，新建一个 SKILL.md 文件：
touch ~/.claude/skills/explain-code/SKILL.md
然后，用你喜欢的编辑器打开这个文件，写入以下内容：
英文版本：
---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---
When explaining code, always include:
1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?
Keep explanations conversational. For complex concepts, use multiple analogies.
中文版本：
---
name: explain-code
description: 使用视觉图表和类比来解释代码。当解释代码工作原理、教授代码库知识，或用户询问"这是如何工作的？"时使用。
---
解释代码时，始终包含以下内容：
1. **从类比开始**：将代码与日常生活中的事物进行比较
2. **绘制图表**：使用 ASCII 艺术展示流程、结构或关系
3. **逐步讲解代码**：逐步解释发生了什么
4. **指出常见陷阱**：什么是常见的错误或误解？
保持解释对话式。对于复杂概念，使用多个类比。
让我解释一下这个文件的结构：
前置元数据部分（在 --- 之间）：
name: explain-code：这是技能的名称，Claude 会把它变成/explain-code命令description：这是技能的描述，Claude 用它来判断什么时候自动使用这个技能
说明内容部分（--- 之后）：
- 这里写的是具体的指令，告诉 Claude 解释代码时要做什么
第三步：测试你的技能
现在，最激动人心的时刻到了——测试你的技能！
有两种方式可以使用这个技能：
方式一：让 Claude 自动调用
当你问 Claude "这段代码是怎么工作的？"时，Claude 会自动识别到这与 explain-code 技能的描述匹配，然后自动使用这个技能。
方式二：直接调用
你也可以直接使用斜杠命令：
无论哪种方式，Claude 都会按照技能中的说明，用类比、图表和逐步解释的方式来回答你。
技能存放位置：选择合适的地方
就像文件可以放在不同的文件夹一样，技能也可以存放在不同的位置，每个位置有不同的作用范围：
| 位置 | 路径 | 谁可以使用 |
|---|---|---|
| 个人技能 | ~/.claude/skills/<skill-name>/SKILL.md |
你的所有项目 |
| 项目技能 | .claude/skills/<skill-name>/SKILL.md |
仅当前项目 |
| 插件技能 | <plugin>/skills/<skill-name>/SKILL.md |
使用该插件的地方 |
| 企业技能 | 通过托管设置配置 | 组织内所有用户 |
个人技能 vs 项目技能：个人技能就像你的个人工具箱，所有项目都能用；项目技能就像项目专用的工具，只有这个项目能用。如果项目技能和个人技能同名，项目技能会优先使用。
技能的结构：不只是单个文件
一个技能可以包含多个文件，就像一个完整的工具箱：
my-skill/
├── SKILL.md # 主要说明（必需）
├── template.md # Claude 要填写的模板
├── examples/
│ └── sample.md # 示例输出
└── scripts/
└── validate.sh # 可执行的脚本
SKILL.md 是必需的，其他文件都是可选的。你可以在 SKILL.md 中引用这些文件，告诉 Claude 什么时候加载它们：
## 额外资源
- 完整的 API 文档，请查看 [reference.md](reference.md)
- 使用示例，请查看 [examples.md](examples.md)
这样可以让 SKILL.md 保持简洁（建议不超过 500 行），同时又能提供详细的参考材料。
配置技能：让技能更智能
技能通过 YAML 前置元数据来配置行为。让我们看看有哪些常用的配置选项：
基本配置
英文版本：
---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read, Grep
---
中文版本：
---
name: my-skill
description: 此技能的作用
disable-model-invocation: true
allowed-tools: Read, Grep
---
常用字段说明：
name：技能名称（可选，默认使用目录名）description：技能描述（推荐，帮助 Claude 判断何时使用）disable-model-invocation：设为true时，只有你能手动调用，Claude 不会自动使用allowed-tools：限制技能运行时 Claude 可以使用的工具
控制谁可以调用技能
有时候，你希望某些技能只能手动调用，比如部署技能。你肯定不希望 Claude 在你还没准备好的时候就自动部署，对吧？
英文版本：
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---
Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded
中文版本：
---
name: deploy
description: 将应用程序部署到生产环境
disable-model-invocation: true
---
将 $ARGUMENTS 部署到生产环境：
1. 运行测试套件
2. 构建应用程序
3. 推送到部署目标
4. 验证部署是否成功
通过设置 disable-model-invocation: true，这个技能只有在你手动输入 /deploy 时才会执行。
传递参数给技能
技能可以接收参数，就像函数可以接收参数一样。使用 $ARGUMENTS 占位符：
英文版本：
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS following our coding standards.
1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit
中文版本：
---
name: fix-issue
description: 修复 GitHub 问题
disable-model-invocation: true
---
按照我们的编码标准修复 GitHub 问题 $ARGUMENTS。
1. 阅读问题描述
2. 理解需求
3. 实现修复
4. 编写测试
5. 创建提交
当你运行 /fix-issue 123 时，Claude 会收到"按照我们的编码标准修复 GitHub 问题 123..."的指令。
两种技能类型：参考 vs 任务
根据用途，技能可以分为两种类型：
参考型技能：提供知识
这类技能提供背景知识、规范、约定等，Claude 会在相关时自动应用：
英文版本：
---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation
中文版本：
---
name: api-conventions
description: 此代码库的 API 设计模式
---
编写 API 端点时：
- 使用 RESTful 命名约定
- 返回一致的错误格式
- 包含请求验证
任务型技能：执行操作
这类技能提供具体的操作步骤，通常需要手动调用：
英文版本：
---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---
Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target
中文版本：
---
name: deploy
description: 将应用程序部署到生产环境
context: fork
disable-model-invocation: true
---
部署应用程序：
1. 运行测试套件
2. 构建应用程序
3. 推送到部署目标
常见问题解答
技能没有被触发怎么办？
如果 Claude 没有自动使用你的技能，可以尝试：
- 检查
description字段是否包含用户会自然说的关键词 - 询问 Claude "有哪些技能可用？"来验证技能是否被识别
- 尝试重新表述你的请求，使其更接近技能描述
- 如果技能支持手动调用，直接使用
/skill-name命令
技能触发太频繁怎么办？
如果技能在不该触发的时候触发了：
- 让
description更具体，缩小匹配范围 - 如果只想手动调用，添加
disable-model-invocation: true
Claude 看不到我的所有技能？
技能描述会被加载到上下文中，但如果你有很多技能，可能会超过字符限制（默认 15,000 字符）。运行 /context 命令可以查看是否有技能被排除。
如果需要，可以设置 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量来增加限制。
总结：开始你的技能之旅
现在，你已经了解了技能的基本概念和创建方法。记住：
- 技能很简单：就是一个
SKILL.md文件 - 从简单开始：先创建一个简单的技能，熟悉后再扩展
- 位置很重要：选择合适的存放位置（个人 vs 项目）
- 描述要清晰：好的
description能让 Claude 更准确地判断何时使用技能
技能就像给 Claude 安装插件，让它变得更懂你、更高效。从今天开始，试着创建你的第一个技能吧！相信我，一旦你体验过技能的便利，你就会爱上它。
如果你在创建技能的过程中遇到问题，不要担心，这是学习的过程。多尝试、多实践，你会发现技能系统比你想象的更强大、更灵活。
祝你技能创建愉快！