一、什么是 Claude Code Skills？

1.1 官方核心定义（基于 Agent Skills 开放标准）

Skills（技能） 是遵循 Agent Skills 开放标准（agentskills.io）、为 Claude Code 设计的可复用能力扩展单元，也是 Claude 可识别、按需加载、自动执行的最小专业能力载体。

它通过标准化文件结构，把特定领域的知识、工作流、编码规范、工具调用规则封装成可移植模块，让 Claude Code 从通用编程助手，升级为具备垂直领域深度能力的专业开发助手。

简单理解：
Skills 就是一份给 Claude 用的专业工作手册，告诉它在特定场景下该做什么、按什么规则做、用什么工具做、输出什么格式。

1.2 Skills 解决的核心痛点：原生提示词的五大缺陷

很多新手会问：直接写提示词不行吗？为什么要用 Skills？
核心原因是：原生提示词只适合临时一次性需求，Skills 才适合长期、复用、团队级、生产级场景。

对比维度	原生提示词	Skills 体系
复用性	单次对话有效，新会话必须重写	一次安装，全局/项目永久生效
管理成本	零散无结构，无法版本管理	目录化存储，支持 Git 协同
触发方式	必须手动粘贴，人工触发	智能上下文自动匹配，无需干预
能力边界	仅文本指令，无法集成脚本/钩子	可封装工作流、脚本、权限、自动化
安全管控	无权限限制，存在风险	支持工具白名单、最小权限原则
团队同步	难以共享、同步成本高	一键安装，规范统一

一句话总结：
提示词是临时指令，Skills 是生产级能力组件。

1.3 Skills 的能力边界：能做什么，不能做什么

通过 Skills，Claude Code 可以扩展出极强的专业能力：

• 研发提效：TDD 开发、代码审查、架构规范、Bug 自动修复
• 上下文增强：跨会话记忆、项目规则沉淀、历史修改回溯
• 垂直领域：Java/Go/Python 最佳实践、数据库优化、DevOps 部署
• 通用生产力：文案生成、图文排版、数据分析、文档处理
• 系统扩展：自定义命令、生命周期钩子、MCP 工具集成

但 Skills 也有明确边界，不能做到：

1. 不能突破 Claude Code 本身的权限与模型能力
2. 不能替代 MCP 服务提供外部工具连接（Skills 教怎么用，MCP 提供工具）
3. 不能在无权限情况下执行高危系统操作
4. 不能修改 Claude 核心推理逻辑，只能引导行为

1.4 为什么 Skills 是生产级使用的核心基石

在真实团队开发中，Skills 必不可少，原因有三点：

1. 强规范约束：强制遵循团队标准，避免“能跑但质量差”的代码
2. 效率指数提升：一次封装，全团队永久复用，大幅减少重复沟通
3. 知识可沉淀：把架构经验、业务规则、最佳实践固化下来，人员流动也不会丢失

---

二、核心概念精准区分（新手 90% 误区都在这里）

Claude Code 扩展体系里，最容易混淆的就是 Skill、Plugin、Marketplace，以及它和斜杠命令、MCP、CLAUDE.md 的关系。本节一次性彻底厘清。

2.1 三大核心：Marketplace、Plugin、Skill

1. Marketplace（插件市场）

插件的集合仓库，是插件分发渠道。

• 本质是带 marketplace.json 索引文件的 Git 仓库
• 分为官方市场、社区市场两类
• 安装插件前，必须先添加对应的市场

2. Plugin（插件）

Claude Code 包管理体系的最小安装单位。

• 必须包含 .claude-plugin/plugin.json 元数据文件
• 一个插件可以封装多个 Skill、命令、钩子、脚本
• 安装/更新/卸载都以插件为单位，不能只装插件里的某一个 Skill

3. Skill（技能）

Claude Code 可调用的最小能力单元。

• 必须包含 SKILL.md 核心文件（文件名全大写）
• 可手动单独部署，也可被打包进插件分发
• Claude 根据 description 判断何时激活

三者层级关系

Marketplace（插件市场）
└── Plugin（插件）← 安装最小单位
    ├── Skill A
    ├── Skill B
    ├── 自定义命令
    └── 生命周期钩子

核心规则：
市场是仓库，插件是安装包，Skill 是真正的能力。

2.2 Skill 与易混概念对比

1. Skill vs 原生提示词 vs 斜杠命令

对比项	Skill	提示词	斜杠命令
本质	结构化能力包	临时文本指令	Skill 的手动触发方式
触发	自动为主	完全手动	必须手动 /命令
复用	全局/项目级	仅当前会话	全局/项目级
管理	目录化、可版本控制	零散不可管理	目录化、可版本控制

2. Skill vs MCP 服务 vs 生命周期钩子

• Skill：专注“任务怎么做、遵循什么规则”
• MCP：专注“能调用哪些外部工具”
• Hook：专注“在什么事件时机自动执行”

3. Skill vs CLAUDE.md vs Subagents

• CLAUDE.md：项目全局默认规则，每次对话都加载
• Skill：场景化能力，按需加载
• Subagents：独立上下文子代理，用于复杂任务拆解

2.3 执行优先级规则（重要）

当多类规则同时存在时，Claude 遵循固定优先级：

1. 手动斜杠命令 ＞ 自动触发 Skill ＞ 普通提示词 ＞ CLAUDE.md
2. 同名 Skill 优先级：企业级 ＞ 用户级 ＞ 项目级 ＞ 插件内 Skill

高优先级会直接覆盖低优先级内容。

---

三、Skills 标准文件体系与规范

3.1 最简可运行 Skill 结构（唯一必填）

一个能正常生效的 Skill，只需要一个文件夹 + 一个文件，无任何额外依赖：

# 用户级全局路径（所有项目生效）
# Windows: C:\Users\<用户名>\.claude\skills\
# macOS/Linux: ~/.claude/skills/
└── your-skill-folder/
    └── SKILL.md        # 必须全大写，缺一不可

• 文件夹名 = Skill 唯一标识（小写字母、数字、连字符）
• SKILL.md 是 Claude 识别 Skill 的唯一依据

3.2 生产级完整 Skill 结构

复杂场景下可扩展为完整工程结构：

your-skill/
├── SKILL.md            # 必选：核心规则与元数据
├── skill.json          # 可选：版本、作者、分类
├── commands/           # 可选：斜杠命令定义
├── scripts/            # 可选：Python/Shell 执行脚本
├── hooks/              # 可选：生命周期钩子
├── references/         # 可选：参考文档、规范
└── assets/             # 可选：模板、资源文件

设计原则：渐进式披露，核心逻辑放 SKILL.md，详细内容放外部文件，降低上下文负担。

3.3 SKILL.md 基础规范

SKILL.md 分为两部分：YAML 元数据头 + Markdown 执行规则。

标准示例：

---
name: springboot-best-practice
description: 在 Spring Boot 项目中自动提供分层架构、安全规范、TDD 流程与代码审查
version: 1.0.0
author: 社区
---

# 执行规则
1. 严格遵循 Controller→Service→Repository 分层架构
2. 默认开启 SQL 注入、XSS 风险检查
3. 开发流程遵循红黄绿 TDD 模式
4. 审查结果按严重等级分级展示

必填且关键：

• name：必须与文件夹名完全一致
• description：Skill 能否自动触发，90% 取决于它

3.4 生效范围与路径

Skill 按生效范围分为两类：

范围	Windows 路径	特点
用户级（全局）	C:\Users\<用户名>\.claude\skills\	所有项目生效
项目级	项目目录\.claude\skills\	仅当前项目，可 Git 共享

优先级：企业级 > 用户级 > 项目级 > 插件内 Skill。

---

四、Skills 触发机制底层逻辑

4.1 自动触发 vs 手动触发

1. 自动触发（主流，90% 场景）

Claude 会实时分析上下文，自动判断是否激活 Skill：

• 用户输入内容与意图
• 项目技术栈、配置文件、文件类型
• 当前打开文件与会话历史

优势：无感知、零学习成本、强制规范。

2. 手动触发（补充，10% 场景）

适用于工作流类、指令型能力，例如：

• 斜杠命令：/plan、/tdd、/security-scan
• 显式调用：“使用 code-explainer 解释这段代码”

4.2 自动触发的底层匹配逻辑

Claude 依靠语义匹配决定是否启用 Skill：

1. 解析用户对话、项目结构、文件类型
2. 提取关键词、技术栈、任务类型
3. 与所有 Skill 的 description 做语义匹配
4. 按匹配度与优先级排序
5. 自动加载最合适的 Skill

触发稳定的关键：
description 必须写清具体功能 + 明确触发词，不能模糊。

反面例子：

description: 处理代码

正面例子：

description: 审查 Java Spring Boot 代码，检查分层规范、SQL 风险、异常处理，用户写代码、改代码、审查时触发

4.3 触发失效的常见底层原因

从认知层面总结，Skill 不生效通常因为：

1. description 太模糊，无法匹配场景
2. 路径错误或 SKILL.md 文件名大小写不对
3. 高优先级同名 Skill 覆盖
4. 当前上下文与 Skill 场景不匹配
5. Skill 使用了高版本不兼容特性

---

五、全篇总结

1. Skills 是 Claude Code 生产化的核心，解决了提示词不可复用、难管理、无规范、难协同的问题。
2. 三大概念必须牢记：Marketplace 是仓库、Plugin 是安装包、Skill 是最小能力单元，层级不可混淆。
3. SKILL.md 是 Skill 的灵魂，尤其是 description，直接决定触发成功率。
4. 触发以自动为主、手动为辅，大部分场景下你只需要自然说话，Claude 会自动调用专业能力。

---