Skills 是什么

在 Claude Code 的语境中，Skill 并非一项内置功能，而是一套可自定义的扩展机制。你可以把它理解为：将处理某类任务的专业知识打包成文件，当 Claude Code 遇到相应场景时能自动调用这些知识，无需你每次都手把手教学。

其本质是：针对特定任务的知识封装，让 AI 不必每次都从零开始推理。

它与 CLAUDE.md 有着本质区别。CLAUDE.md 回答的是"这个项目是什么"——相当于为项目建立一份身份档案；而 Skill 回答的是"这类任务该怎么做"——它是一本工作手册。

从官方实现来看，Skills 的文件结构相当清晰：

skill-name/
├── SKILL.md              ← 必需文件，包含 YAML frontmatter 和核心指令
├── references/           ← 可选，参考文档，按需加载
├── examples/             ← 可选，工作示例
└── scripts/             ← 可选，可执行脚本

Claude Code 启动时，会扫描 skills/ 目录，将每个子目录中 SKILL.md 的 name 和 description 加载到上下文。当用户的描述触发了某个 description，Claude 就会将对应的 SKILL.md 全文读入，并按照里面的指令执行。

为什么需要 Skills

三个典型场景即可说明：

第一，团队知识传承。

团队里最出色的工程师，那些代码审查的独到眼光、安全扫描的严谨逻辑、部署规范的严格流程，都是长期积累的成果。如果仅靠口口相传，每次新成员加入都要重新教导。借助 Skill，这些经验能够固化为文件，新人加上项目 CLAUDE.md，AI 就能按团队的标准来工作。

第二，复杂任务的决策框架。

一段 prompt 只能给出一个答案，但一个 Skill 能提供一套决策树。面对不同情况该走哪条分支、输出什么内容，都清晰明确。而不是每次都生成一段看起来合理但风格不一致、质量不稳定的内容。

第三，反复执行的确定性任务。

有些任务每次都要编写类似的代码——比如每次新建组件都要搭建脚手架、每次进行代码迁移都要处理相同的模式。将这些任务的"最佳实践"写成 Skill，Claude 每次都能以最成熟的方式执行，不会每次都从零推理、靠运气。

Skills 的真实结构：从官方源码看设计

SKILL.md 的 frontmatter

官方 frontend-design 插件的 Skill 文件如下所示：

---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications.
---
# Frontend Design Guidance
## Design Thinking
Before coding, understand the context and commit to a BOLD aesthetic direction...
## Technical Requirements
Implement production-grade code that is...

frontmatter 中真正起作用的只有三个字段：

其中 description 是最关键的字段。官方 plugin-dev 插件的方法论明确强调：description 的质量直接决定了 Skill 能否被正确触发。

官方推荐的 description 写法是第三人称 + 具体触发短语：

# 正确示范
description: This skill should be used when the user asks to "create a hook",
"add a PreToolUse hook", "validate tool use"...
# 错误示范
description: Provides guidance for working with hooks.   # 模糊，没有触发短语
description: Load this skill when user asks...            # 第二人称

正文：不是步骤清单，而是决策框架

官方 frontend-design Skill 的正文结构如下：

## Design Thinking
- Purpose: 这个界面解决什么问题？
- Tone: 选择一个设计方向（极简、复古、奢华……）
- Constraints: 技术约束是什么？
- Differentiation: 什么让它令人印象深刻？
## Frontend Aesthetics Guidelines
- Typography: 字体选择
- Color & Theme: 配色体系
- Motion: 动效
- Spatial Composition: 空间布局

这为 Claude 提供了一套思考框架，而非一串执行步骤。Claude 需要在这个框架内自主判断每一步该怎么做，而不是机械地执行指令。

官方 Skill Development 方法论也特别指出：正文应使用祈使句/不定式（verb-first），而非第二人称。

# 正确
To create a hook, define the event type.
Configure the MCP server with authentication.
Validate settings before use.
# 错误
You should create a hook by defining the event type.
You need to configure the MCP server.

渐进披露：三层加载机制

这是 Skills 系统最核心的设计理念，来自官方 Skill Development 方法论。

Claude Code 对 Skill 的加载分为三个层级：

层级一：元数据（name + description）
  → 始终加载，约 100 词，占用最少上下文
层级二：SKILL.md 正文
  → Skill 被触发时加载，目标 1500-2000 词，上限 5000 词
层级三：references/ + examples/ + scripts/
  → 按需加载，加载时机由 Claude 判断，无上限

这套机制解决了一个核心矛盾：大模型上下文有限，但专业任务需要大量细节。渐进披露让 Claude 只在真正需要时才加载详细内容，保持上下文高效运转。

具体分工如下：

• SKILL.md 放什么：核心概念、关键流程、快速参考、常用模式
• references/ 放什么：详细文档、API 参考、模式大全
• scripts/ 放什么：验证工具、测试脚本、自动化脚本（可执行，不占上下文）
• examples/ 放什么：完整的可运行示例，用户可直接复制使用

官方插件体系：14 个真实参考案例

anthropics/claude-code 仓库的 plugins/ 目录包含了 14 个官方插件，每个都是 Skills 的实战案例。

plugin-dev：系统级的 Skill 创建方法论

plugin-dev 插件下的 skill-development 子目录，完整展示了创建一个 Skill 的六步流程：

Step 1：理解 Skill 的具体使用场景。 从真实案例出发，找到 3-5 个该 Skill 会被用到的具体场景，然后围绕这些场景设计指令。

Step 2：规划 Skill 的资源结构。 scripts/ 处理重复性脚本任务，references/ 处理需要按需查阅的文档，assets/ 处理模板和输出文件。

Step 3：创建目录结构。 标准结构确保 Claude 能正确发现并加载 Skill。

Step 4：编写 SKILL.md。 核心原则：description 使用第三人称 + 触发短语，正文使用祈使句，控制在 1500-2000 词，详细内容移至 references/。

Step 5：验证与测试。 使用 skill-reviewer agent 进行自动检查，对照验证清单逐项审查。

Step 6：迭代改进。 在实际使用中发现 SKILL.md 哪里不够精准，哪里容易触发但输出质量不稳定，持续优化。

hookify：专业领域的深度 Skill

hookify 插件演示了专业领域 Skill 的典型写法，它的 description 包含了 9 个具体触发短语：

description: This skill should be used when the user asks to "create a hook",
"add a PreToolUse hook", "validate tool use", "implement prompt-based hooks",
"${CLAUDE_PLUGIN_ROOT}", "block dangerous commands", or mentions hook events.

触发短语越具体，Claude 越能准确判断何时该调用该 Skill。

agent-development：多组件协同的 Skill

agent-development Skill 展示了 Skill 如何与其他组件（agents、commands）协同工作。SKILL.md 和 scripts/ 的分工非常清晰：

• SKILL.md：何时创建 agent、创建后如何使用
• validate-agent.sh：如何验证 agent 配置是否正确

前者是知识，后者是确定性操作。

写好 Skill 的 8 条实践规则

规则 1：description 是整个 Skill 的命门

description 决定触发准确性。要写触发条件，而不是功能说明。

# 差：功能说明
description: "This skill helps with code reviews."
# 好：具体触发条件
description: "This skill should be used when the user asks to review a pull request,
audit code changes, or analyze commit history for potential issues."

触发短语越多、越具体，Claude 越能准确判断。

规则 2：正文提供决策框架，而非步骤清单

步骤清单是给机器执行的，决策框架是给 Claude 思考的。Claude 不是复读机，它需要知道在什么情况下做什么判断，而不是一步步执行什么操作。

规则 3：规定下限，不限上限

明确告诉 Claude"至少要包含什么"，但不限制 Claude 在此基础上额外做什么。好的 Skill 让 Claude 了解最低质量标准，剩下的空间留给它发挥。

规则 4：一个 Skill 只做一个领域

不要把代码审查、安全扫描、风格检查三个完全不同的事务塞进一个 Skill。拆分后每个 Skill 更专注、更稳定，出问题也更容易定位。

规则 5：禁忌要说清楚

很多 Skill 花大量篇幅描述"应该做什么"，但对"不应该做什么"只字不提。在 Skill 末尾添加一个"边界情况"或"禁忌"小节，告诉 Claude 什么红线不能踩，往往比正向说明更有效。

规则 6：SKILL.md 要精简，详细内容移至 references/

如果一个 Skill 的正文超过 3000 词还没说完，说明内容放错了位置。将详细的模式文档、API 参考、迁移指南移到 references/ 目录，SKILL.md 只保留核心流程和快速参考。

规则 7：与 CLAUDE.md 划清职责边界

CLAUDE.md 回答"这个项目是什么"，Skill 回答"这类任务怎么做"。不要将项目规范复制进 Skill——规范放在 CLAUDE.md，Skill 专注于具体任务执行逻辑。

规则 8：给 Skill 留退出条件

Claude 在 Skill 执行过程中可能遇到权限不足、外部依赖失败、用户中断等情况。Skill 里要明确什么情况下应该停止并报告，而不是让 Claude 无限制地继续尝试，直到输出糟糕的结果。

Skill vs Commands：怎么选

实战建议：先用 Command 原型验证一个需求，确认它确实高频且流程稳定后，再将其抽取为 Skill。

官方 14 个插件一览

总结

Skills 系统是 Claude Code 最为强大的扩展机制。其核心价值在于：将团队的专业知识封装成可自动执行的格式，让 AI 在每个相关场景中都能采用团队最佳标准来工作。

三个核心要点值得牢记：

触发靠 description。 description 写得好坏，直接决定 Skill 能否被正确调用。触发短语要具体、要使用第三人称、要覆盖真实的用户表达方式。

正文靠决策框架，而非步骤清单。 官方源码的设计思想高度一致：为 Claude 提供思考框架，让它在该框架内自主判断，而不是机械地执行步骤。

渐进披露是核心架构思想。 三层加载机制让 Claude Code 能够在保持上下文高效的同时，掌握大量专业知识。这才是 Skills 系统区别于简单 prompt 模板的根本所在。

本文参考资料：

• [1] GitHub: anthropics/claude-code - plugin-dev/skills/skill-development（官方 Skill 创建方法论）
• [2] GitHub: anthropics/claude-code - plugins/frontend-design/skills（官方 Skill 真实实现案例）
• [3] GitHub: anthropics/claude-code - plugins/plugin-dev/skills（7个官方 Skills 完整源码）
• [4] DEV.to: "I Built a Diagnostic CLI for Claude Code Skills" by thestack_ai（8条常见错误规则）