推荐语

掌握Claude Code的Skills系统，让你的AI开发效率提升一个维度，团队知识传承从此不再难。

核心内容：
1. Skills系统的核心机制与文件结构解析
2. 团队知识传承、复杂任务决策、重复任务处理三大应用场景
3. 官方源码深度解读与最佳实践案例

杨芳贤

53AI创始人/腾讯云(TVP)最具价值专家

标签： AI Coding / Claude Code / 深度技术

系列定位： Claude Code 实战系列第三篇。前两篇分别是《CLAUDE.md 协作指南》与《真实项目开发流程》，本篇聚焦 Claude Code 的 Skills 扩展体系，深度解析官方源码与设计理念。

Skills 是什么

在 Claude Code 的语境里，Skill 不是一个内置功能，而是一套自定义扩展机制。

它的本质是：把针对特定任务的专业知识打包成文件，让 Claude Code 在遇到相应场景时能够调用这套知识，而不是每次都重新描述。

这和 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 可以给出一个决策树。Claude 遇到不同情况，应该走哪条分支，输出什么，都有明确的规范，而不是每次生成一段看似合理但不一致的内容。

第三，反复重写的确定性任务。

有些任务每次都要重新写差不多的代码，比如每次新建组件都要搭脚手架、每次做代码迁移都要处理同一套模式。把这些任务的"正确做法"写成 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 是整个 Skill 最重要的字段。官方 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 和 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条常见错误规则）