ClaudeMap

·技能与命令

什么是 Claude Code 技能（Skill）、SKILL.md 约定如何运作，以及如何编写、打包和分享自己的技能——附真实示例与实战最佳实践。

Claude Code Skills 完全指南：构建可组合的 Agent 能力单元

Claude Code 是一个具备 Agent 能力的编码工具：你描述需求，它改文件、跑命令、把功能交付出来。在真实项目里用久了，你会发现同样一些指令反复出现——团队怎么写提交信息、怎么新建一个组件、怎么排查一个偶发失败的测试。技能（Skill） 就是把这些可复用的流程封装起来，让 Claude Code 在需要时按需调入。本指南讲清楚技能是什么、SKILL.md 约定、它和斜杠命令的关系、如何构建和分享一个技能，以及把「玩具技能」和「真正经得起日常使用的技能」区分开来的实践。

技能到底是什么

一个技能，就是一个包含 SKILL.md 文件的目录。这就是全部必需的结构。SKILL.md 文件由描述技能的 YAML frontmatter，加上一段 Markdown 正文（详细指令、脚本、示例）组成。

最关键的设计选择是渐进式披露（progressive disclosure）。Claude Code 开启会话时，只会加载 frontmatter——也就是技能的 name 和 description，各占大约 30 到 100 个 token。完整的指令正文，只有当 Claude 判定某个用户请求匹配这个技能时才会被读取。正因为如此，你可以注册一大堆技能，却不会在每一轮对话里撑爆上下文窗口：廉价的元数据始终在场，昂贵的正文则懒加载。

可以把技能理解成放在你代码旁边、一个具名且按需加载的「流程」。Claude 在相关时调用它，而你永远不必为「此刻用不到」的指令付费。

SKILL.md 约定

一个最小技能长这样：

my-skill/
└── SKILL.md

在 SKILL.md 里，frontmatter 承载两个必填字段和若干可选项：

---
name: commit-message-style
description: 按团队更新日志格式生成 Conventional Commits 提交信息。当用户想要提交，或索要提交信息时使用。
allowed-tools: ["Bash(git log:*)", "Bash(git diff:*)"]
---

# 提交信息风格

当用户要提交信息时：

1. 运行 `git diff --cached` 查看暂存了什么。
2. 运行 `git log -5 --oneline` 对齐最近提交的语气。
3. ……

字段说明：

  • name（必填）——技能标识符，一般用 kebab-case。保持稳定，其他配置可能会引用它。
  • description（必填）——技能做什么、以及何时使用的简短概述。这是 Claude 在决定加载技能前唯一看到的文字，因此它同时承担「触发条件」的职责。控制在 1,024 字符以内，并写清楚适用场景（「当用户想要……时使用」）。
  • allowed-tools（可选）——限制该技能可调用的工具，格式与 Claude Code 其它地方一致（例如 Bash(git log:*)）。省略则继承会话的默认工具集。
  • user-invocable（可选）——设为 true 时，技能也会作为一个用户可直接调用的斜杠命令出现。

除了 SKILL.md，技能目录里可以放任何有助于指令的东西：参考文件、模板、辅助脚本、示例输出。SKILL.md 本身的正文要保持聚焦——常见建议是控制在约 5,000 token 以内，把长篇参考资料挪到独立文件里，由技能按需读取。

技能与斜杠命令

技能和斜杠命令的关系一开始容易让人困惑，因为它们会有重叠。

斜杠命令是一个显式的、由用户发起的动作：你输入 /something，它就运行。历史上它们被定义成简单的提示词文件。

技能是一种当请求匹配其描述时，模型可以自动调入的能力。设了 user-invocable: true，技能同时会作为一个斜杠命令暴露出来。

实用的结论是：如果你发现某个斜杠命令本质上是「Claude 本该掌握的可复用流程」，那就把它写成技能。技能免费提供自动触发，而显式调用只是一个可选开关，而不是唯一入口。对于一次性、不需要发现逻辑的提示，斜杠命令依然有用。

动手做一个真实技能

我们来做一个真正用得上的：为某个仓库定制的、一致性的代码评审清单。把目录建在 .claude/skills/（项目级）或 ~/.claude/skills/（用户级）下：

.claude/skills/
└── review-checklist/
    └── SKILL.md

.claude/skills/review-checklist/SKILL.md：

---
name: review-checklist
description: 在开 PR 之前，针对暂存或最近的改动跑一遍一致的代码评审清单。当用户要求评审代码、准备 PR 或自检改动时使用。
allowed-tools: ["Bash(git diff:*)", "Bash(git log:*)", "Read", "Grep"]
---

# 评审清单

对当前改动集（相对基线分支的 `git diff`）应用以下检查：

1. **测试**——行为变更是否伴随新增或更新测试？纯新增代码若无测试，要点出来。
2. **错误路径**——新代码处理了失败情形，还是只覆盖了正常路径？
3. **命名**——新增标识符是否与所在模块约定一致？
4. **对外接口**——是否扩展了 public/exported API？若是，是否补了文档？
5. **密钥与日志**——代码或日志里是否混入了凭证、token 或个人隐私信息？

按文件分组，以简短有序列表汇报。结尾给出三者之一：`LGTM`、`小修`、或 `拦截`。

要用它，只需用自然语言问 Claude Code：「在我 push 之前帮我评审一下暂存的改动。」因为描述里写了「当用户要求评审代码时使用」，Claude 就会加载该技能并应用清单——根本不需要斜杠命令。设了 user-invocable: true，你也能直接 /review-checklist 调用。

技能放在哪里

技能会从多个位置加载，这让你可以混合「团队级」与「个人级」能力：

  • 项目技能——.claude/skills/，提交进仓库，项目里所有人共享。
  • 用户技能——~/.claude/skills/，你希望在所有项目里都拥有的能力（你个人的 git 习惯、编辑器偏好）。
  • 插件提供的技能——安装的插件可以随自身其它功能一并贡献技能。

这种分层很重要：把项目专属的东西（提交风格、部署流程、领域术语表）放进仓库，让全团队受益；把属于你个人的东西（你喜欢 PR 怎么总结）放进用户目录。

打包与分享

要把技能分享到单个仓库之外，常见路径是做成插件。一个插件把一个或多个技能（可选地连同斜杠命令、hook 和 MCP 服务器）打包成一个可分发的单元，别人按名字安装即可。因为每个技能本质上只是一个带 SKILL.md 的目录，把它抽出来做成可分享插件的门槛很低：把目录挪进插件布局、加上 manifest、发布即可。

这种模式一个真实且知名的例子是 Superpowers（可在 ClaudeMap 上收录），一个社区技能包，把几十个经过检验的流程——代码评审、测试生成、迁移助手等——打包成可组合的技能，你可以直接放进自己的环境。研究这类技能包，是领会「如何把技能范围拿捏到位」最快的方式：每一个都很小、描述锐利、把横切关注点交给其它技能处理，而不是膨胀成巨石。

当你自己打包时，要反复问两个问题：「光看描述，陌生人能明白何时用吗？」「能不能拆成两个触发更可靠的技能？」什么都想干的技能，触发往往不可靠；只干一件事的技能，触发稳如时钟。

最佳实践

下面这些模式，在成熟的技能库里都站得住脚：

  • 让描述物超所值。 它是启动时唯一加载的东西，也是决定技能是否触发的唯一依据。重点写清楚何时用，而不只是做什么。
  • 正文要小、多靠引用。 长篇参考资料放进相邻文件，由技能按需读取，而不是一股脑内联。
  • 审慎约束工具。 用 allowed-tools 防止技能越权——一个会改文件的评审技能，就是一个迟早会闯祸的评审技能。
  • 宁可多个窄技能，不要一个大而全。 当每个技能只负责一个意图时，触发更可靠。
  • 既测正文，也测触发。 写完技能后，用三种不同说法提同一个需求，确认它会加载。正文完美但永不触发的技能，毫无价值。

从把你每天重复的一个流程抽到 .claude/skills/ 开始。一旦你体会到「再也不用把这些指令敲一遍」的轻松感，你就会开始到处看到值得打包的流程。

本文基于截至 2026 年 7 月的公开信息，相关 API 可能演进。