1. 前言
在持续使用 Claude Code 的过程中，开发者往往会积累一套属于自己或团队的最佳实践：提交代码时要遵循特定格式、代码审查时要检查哪些维度、部署前要验证哪些步骤。这些经验通常存在于脑海或文档中，每次都需要手动向 Claude 解释一遍，耗时且容易遗漏。
Skills 正是为了解决这一痛点而设计的。它允许将任意知识、规范或工作流封装进一个 SKILL.md 文件， Claude 便能将其纳入自己的工具箱——在合适的时机自动调用，或者由用户以斜杠命令主动触发。
2. 什么是Skills
Skills 是 Claude Code 提供的技能扩展机制，核心是一个包含 SKILL.md 文件的目录。创建 SKILL.md 后， Claude 会将该技能加入工具箱：可以用 /技能名 直接调用，也可以由 Claude 在对话时判断相关性后自动加载。
Claude Code 的 Skills 遵循 Agent Skills 开放标准。该标准由 Anthropic 主导维护，旨在让技能文件可以跨多种 AI 工具使用，实现"编写一次，到处运行"。 Claude Code 在标准基础上扩展了调用控制、子智能体执行、动态上下文注入等高级特性。
2.1 设计目标
Skills 设计的核心目标是将领域知识与工作流程变为 可复用、可分发 的单元，主要解决以下问题：
2.2 设计原理：渐进式披露
Skills 采用 渐进式披露（Progressive Disclosure） 机制管理上下文效率：
Session Start | v[Discovery] ── 仅加载所有技能的 name + description | (轻量级，让 Claude 知道"有什么可用") v[Activation] ── 用户输入或对话内容匹配技能 description | (Claude 决定加载完整 SKILL.md) v[Execution] ── Claude 按照 SKILL.md 指令执行任务 (按需加载支撑文件、执行脚本)
这种设计确保大量技能同时存在时，不会撑满上下文窗口；只有真正需要的技能才会被完整加载。
3. 内置技能（Bundled Skills）
Claude Code 自带一批开箱即用的内置技能，随每次会话提供，通过 /技能名 调用：
4. 技能存储位置
技能的存储位置决定了它的适用范围：
当不同级别存在同名技能时，优先级为： 企业 > 个人 > 项目 。插件技能使用 插件名:技能名 的命名空间，不会与其他级别冲突。
5. 编写技能
5.1 目录结构
每个技能是一个独立目录， SKILL.md 是必需的入口文件：
my-skill/ ├── SKILL.md # 必需：主指令文件 ├── template.md # 可选：供 Claude 填写的模板 ├── examples/ │ └── sample.md # 可选：示例输出，展示期望格式 └── scripts/ └── helper.py # 可选：Claude 可执行的脚本
SKILL.md 以外的文件属于 支撑文件 ，需在 SKILL.md 中显式引用， Claude 才知道它们的存在和用途。这让技能可以将大型参考文档、 API 规范等按需加载，而非每次都占用上下文。
5.2 SKILL.md格式
SKILL.md 由两部分组成：顶部的 YAML frontmatter 和正文 Markdown 指令。
---name: 技能名称description: 技能描述，说明功能和触发时机---## 技能正文指令在此编写 Claude 需要遵循的步骤和规则……
5.3 Frontmatter配置项
Frontmatter 的配置字段均为 可选 内容。
调用控制矩阵 ：
disable-model-invocation 和 user-invocable 两个字段共同决定技能的调用权限：
5.4 参数传递
技能支持通过 $ARGUMENTS 占位符接收参数：
若调用时传入了参数但技能内无 $ARGUMENTS 占位符， Claude Code 会自动将参数以 ARGUMENTS: <内容> 的形式追加到技能内容末尾。
6. 使用示例
6.1 示例一：代码讲解技能
创建一个能用类比和图示讲解代码的个人技能：
第一步：创建技能目录
mkdir -p ~/.claude/skills/explain-code
第二步：编写 SKILL.md
---name: explain-codedescription: 用类比和图示讲解代码。当用户询问代码工作原理、请求介绍代码库、或询问"这是怎么工作的"时使用。---讲解代码时，始终包含以下内容：1. **从类比开始**：将代码比作日常生活中熟悉的事物2. **绘制图示**：用 ASCII 艺术展示流程、结构或关系3. **逐步拆解**：一步一步解释代码执行过程4. **指出常见误区**：指出容易踩的坑或常见误解保持解释口语化。对于复杂概念，使用多个类比。
第三步：测试技能
# 让 Claude 自动识别触发（描述匹配）How does this authentication flow work?# 直接调用技能/explain-code src/auth/login.ts
6.2 示例二：规范化提交技能
创建一个强制代码提交遵循 Conventional Commits 规范的项目技能：
mkdir -p .claude/skills/commit
---name: commitdescription: 将当前改动以规范格式提交到 Gitdisable-model-invocation: true---将当前所有改动提交到 Git，严格遵循 Conventional Commits 规范：1. 运行 `git diff --staged` 查看暂存的改动2. 分析改动类型，选择合适的提交类型前缀： - `feat`: 新功能 - `fix`: Bug 修复 - `docs`: 文档更新 - `refactor`: 代码重构（无功能变更） - `test`: 测试相关 - `chore`: 构建/工具链相关3. 若存在 breaking change，在类型后加 `!`，并在正文中注明 `BREAKING CHANGE:`4. 提交信息格式为：`<类型>(<范围>): <简短描述>`5. 执行 `git commit -m "<提交信息>"`不要直接 push，以便用户检查。
由于设置了 disable-model-invocation: true ， Claude 不会在你没准备好时自动提交，只有你手动输入 /commit 才会触发。
6.3 示例三：PR摘要生成技能
使用动态上下文注入和子智能体的进阶技能：
mkdir -p ~/.claude/skills/pr-summary
---name: pr-summarydescription: 为当前 Pull Request 生成结构化摘要，包括改动说明、影响范围和测试建议context: forkagent: Exploreallowed-tools: Bash(gh *)---## Pull Request 上下文- PR 差异（diff）：!`gh pr diff`- PR 评论：!`gh pr view --comments`- 改动文件清单：!`gh pr diff --name-only`## 你的任务根据以上 PR 数据，生成一份结构化摘要，包含：1. **改动概述**：用两三句话说明本次 PR 做了什么2. **改动文件分析**：按模块分组列出关键改动3. **潜在风险**：指出可能影响稳定性的改动点4. **建议测试方向**：列出验证本次改动所需的关键测试场景
该技能的特点：
6.4 示例四：代码库规范知识库技能
将项目编码规范作为 背景知识 供 Claude 自动参考，而非用户手动调用的命令：
---name: project-conventionsdescription: 本项目的编码规范和架构约定，包括 API 设计、错误处理、数据库操作等规则user-invocable: false---## API 设计规范- 所有`REST`接口使用复数名词，如`/users`而非`/user`- 错误响应格式统一为`{"code": "ERROR_CODE", "message": "..."}`- 分页参数统一使用`page`和`pageSize`，默认`pageSize`为`20`## 数据库操作规范- 禁止在循环中执行数据库查询（N+1 问题）- 所有批量写操作必须在事务中执行- 查询语句必须有索引覆盖，禁止全表扫描## 错误处理规范- 业务错误使用自定义`AppError`类，包含错误码和用户可读信息- 系统级错误需记录堆栈日志，不向用户暴露内部细节
user-invocable: false 让这个技能不出现在 / 菜单中（它不是一个"命令"），但 Claude 在写代码时会自动参考其中的规范。
7. 常见问题排查
7.1 技能没有自动触发
7.2 技能触发频率过高
7.3 Claude看不到全部技能
技能描述会占用上下文配额（默认为上下文窗口的 2% ，最少 16,000 字符）。若技能太多，部分技能可能被排除。运行 /context 可查看是否有技能被忽略的警告。
可通过设置环境变量 SLASH_COMMAND_TOOL_CHAR_BUDGET 来覆盖默认配额限制。
8. 技能分发
根据受众不同，技能可以用多种方式分发：
9. 参考资料
NOTE
tip