2026-08-11·技能与命令

2026 年 Claude Code 技能机制实战——SKILL.md frontmatter、渐进式披露、调试触发逻辑、打包为插件，以及一个含 hooks 与子 agent 的真实 PR 评审 walkthrough。

Claude Code Skills 完全指南：SKILL.md、插件与子 agent 协同（2026）

Q: 技能和斜杠命令有什么区别？

斜杠命令是用户显式发起的动作；技能是模型在请求匹配其描述时可以自动调入的能力。把 user-invocable 设为 true 后，技能也能作为斜杠命令出现，但自动触发才是技能的核心特征。

Q: Claude Code 技能放在哪里？

技能从多个位置加载：项目级技能在 .claude/skills/（提交到仓库、团队共享）、用户级技能在 ~/.claude/skills/（个人、跨项目可用），以及已安装插件贡献的技能。三者可以叠加使用。

Q: 怎么知道我的 skill 在什么时候触发了？日志在哪？

开 --debug 跑一次，Claude Code 会打印每个候选 skill 的 description 匹配打分；运行 /doctor 可看到所有可用 skill 的列表、当前 listing 占了多少上下文预算，以及 description 是否被截断。如果你怀疑被加载了但模型没遵循，强化 description 的触发短语、把「Use when…」的同义词写进 when_to_use。注意 top-level skill 目录在会话中创建需要重启才会被识别，mid-session 改名则会被自动重载。

Claude Code Skills 是 Anthropic 在 2025–2026 年推出的渐进式披露（progressive disclosure）能力封装：一个技能就是一个含 SKILL.md 的目录，启动时只加载 frontmatter（约 30–100 token），正文按需懒加载。本文基于 Claude Code 2026 年 8 月版本，覆盖：完整 SKILL.md frontmatter 字段、调试技能触发的三道闸门、技能 / 插件 / 子 agent / 斜杠命令的边界划分，以及一个含 hooks 与子 agent 的真实 PR 评审 walkthrough。

TL;DR

Skill = 一个含 SKILL.md 的目录；启动时只加载 description（约 30–100 token），正文按需懒加载

2026 年 8 月现状：description + when_to_use 合并后截断上限 1,536 字符；skill 可绑 hooks、可被 subagent preload

边界判定：被模型自动调用 → skill；用户显式调用 → command；要隔离上下文 → subagent；要跨项目分发 → plugin

本文覆盖：frontmatter 字段、触发调试、插件打包、含子 agent 的 PR 评审 walkthrough

技能到底是什么

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

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

调试：技能为什么不触发（以及怎么修）

技能偶尔不按预期触发——要么从不调用、要么过度触发、要么加载了但模型不遵循。三道闸门决定一切：

闸门 1：description 截断。 Claude Code 把每个候选技能的 description 与 when_to_use 合并展示，总字符数上限 1,536——超出部分会被无声截断（Claude Code Skills 文档）。被截断的描述不会出现在 listing 里，模型根本看不到。修法：精简描述，把同义词放进 when_to_use。

闸门 2：模型匹配。 启动时 listing 受 skillListingBudgetFraction 限制（默认约占 context window 的 1%），预算不够时低优先级技能被折叠为「name-only」。修法：在 skillOverrides 里把低优先级技能降级；或提高列表预算；或精简其它技能的描述。

闸门 3：上下文加载。 即使触发了，技能正文必须被显式读取才能生效。--debug 标志会让 Claude Code 打印每个候选技能的描述匹配分数；/doctor 列出当前可用技能、当前 listing 占用的预算以及描述是否被截断。修法：跑一次 --debug + /doctor，定位卡在哪道闸门。

症状 → 诊断 → 处方：

| 症状 | 最可能的原因 | 第一处方 | |---|---|---| | 从不触发 | 描述被截断 / 关键词不对 | 精简 description、把同义词放进 when_to_use | | 过度触发 | 描述太宽 | 加负面示例 / 把动词具体化（「用 Conventional Commits 提交」而非「提交代码」） | | 加载了但失效 | 正文没被读取 | 检查是否在「user-invocable」、是否绑了正确的 context: fork | | 改了不生效 | 顶层目录新建 | 重启会话；已有目录的修改会被自动重载 |

描述写得好的反例对比：「处理代码」（太宽，触发不可靠）vs 「当我让 Claude 评审代码改动、检查 Conventional Commits 格式、或自检 PR 前置条件时调用」（具体触发短语，命中率高）。

技能 vs 插件 vs 子 agent vs 斜杠命令：什么时候用哪个

四种能力很容易混用，但判定准则只有一条：

被模型自动调用 → Skill
用户显式调用 → Slash Command
要隔离上下文 / 并行执行 → Subagent
要跨项目 / 对外分发 → Plugin

四点对比：

| 维度 | Skill | Slash Command | Subagent | Plugin | |---|---|---|---|---| | 触发方式 | 模型按 description 匹配 | 用户显式输入 /name | 用户或模型委派 Task | 安装到 Claude Code 后生效 | | 上下文 | 加载到主会话 | 主会话内 | 独立 context window | 由其内容决定 | | 命名空间 | 文件系统目录 | /name | Task agent id | plugin-name:skill-name | | 典型场景 | 团队评审清单、提交信息生成 | 部署、测试运行 | 隔离的深度研究、长跑任务 | 跨团队 / 对外分发的能力包 |

三个易错点：(a) 用斜杠命令写可复用流程是反模式——任何重复 3 次以上的流程都应升级为 skill，享受自动触发收益；(b) 「把所有事都塞进一个 skill」会触发不可靠——复杂任务应让 skill 链式调用其他 skill，或 spawn subagent 委派（Superpowers 的 12+ skills 协同模式是范例）；(c) 「想跨项目分发」必须走 plugin（Claude Code Plugins 文档定义了 manifest、marketplace.json、/plugin install name@marketplace 安装路径），单 skill 抽出来后门槛低但要补 manifest。

子 agent 与技能的嵌套关系：subagent 的 skills 字段在启动时把 SKILL.md 全文注入到子上下文（不止 description），而 context: fork 的 skill 则借用指定 agent 的 system prompt——两类机制都在 Claude Code Subagents 文档里有原文说明。

实操：构建一个团队 PR 评审技能

走一遍真实场景：在 .claude/skills/pr-review/ 下建一个团队共用的 PR 评审 skill，含 hooks、allowed-tools 收紧、委派子 agent 做安全深扫。

目录结构：

.claude/skills/pr-review/
├── SKILL.md                # 主入口
├── references/
│   └── checklist.md        # 评审清单，按需加载
├── scripts/
│   └── diff-summary.sh     # PreToolUse hook 调用
└── agents/
    └── security-reviewer.md  # 委派的安全扫描子 agent

SKILL.md（含 hooks 块）：

---
name: pr-review
description: Use when reviewing staged or committed code changes, checking PR diffs against team conventions, or running a pre-merge checklist. Triggers on phrases like "review my changes", "check this PR", "pre-merge review".
allowed-tools: Read, Grep, Bash(git diff:*), Bash(gh pr diff:*)
disallowed-tools: Edit, Write
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "scripts/diff-summary.sh"
          additionalContext: true
---

# PR Review Checklist

When this skill loads, walk through references/checklist.md systematically.
For security-sensitive patterns (auth, crypto, secrets), spawn a security-reviewer
subagent via Task tool with this prompt: "Scan the diff for OWASP Top 10 patterns."

关键设计：

allowed-tools: Read, Grep, Bash(git diff:*) 把工具集收紧到「只读 + 只跑 git diff」——评审技能不应该能改文件，否则就是「迟早会闯祸的评审技能」（Claude Code Hooks 文档原文：「Hooks can be defined directly in skill frontmatter and are scoped to the skill's lifecycle」）。
disallowed-tools: Edit, Write 显式拒绝改文件。
hooks 块把 diff-summary.sh 的输出作为 additionalContext 注入——这是 Anthropic 在 2026 年加的能力，skill 触发时自动跑前置脚本。
subagent security-reviewer 通过 agents/security-reviewer.md 定义，独立 context，扫描完把结果回主会话。

测试触发：用三种说法提同一个需求：

"review my staged changes" — 应自动触发（description 关键词命中）
"帮我看看这个 PR 安全吗" — 应触发并委派 subagent
"run pr-review on branch feature-x" — user-invocable: true 下的显式调用

任一不命中，先跑 --debug 看匹配分数，再调 description。

打包成 plugin（跨项目分发）：把目录挪进 pr-review-plugin/.claude-plugin/plugin.json，在 marketplace.json 里登记，按 renames 兼容策略处理旧安装——Claude Plugins Official 仓库有完整 manifest 示例。

最佳实践

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

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

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

常见问题

什么是 Claude Code 技能（Skill）？

一个技能就是一个包含 SKILL.md 文件的目录。SKILL.md 由 YAML frontmatter（name 和 description）和一段 Markdown 指令正文组成。Claude Code 启动时只加载 frontmatter，只有当请求匹配技能描述时才读取完整正文，因此你可以注册很多技能而不撑爆上下文窗口。

技能和斜杠命令有什么区别？

斜杠命令是用户显式发起的动作；技能是模型在请求匹配其描述时可以自动调入的能力。把 user-invocable 设为 true 后，技能也能作为斜杠命令出现，但自动触发才是技能的核心特征。

Claude Code 技能放在哪里？

技能从多个位置加载：项目级技能在 .claude/skills/（提交到仓库、团队共享）、用户级技能在 ~/.claude/skills/（个人、跨项目可用），以及已安装插件贡献的技能。三者可以叠加使用。

SKILL.md 文件应该多大？

SKILL.md 正文要保持聚焦，通常不超过约 5000 个 token，把长篇参考资料放到独立文件里按需读取。description 是启动时唯一加载的内容，必须明确写出「何时使用」才能可靠触发。

怎么知道我的 skill 在什么时候触发了？日志在哪？

开 --debug 跑一次，Claude Code 会打印每个候选 skill 的 description 匹配打分；运行 /doctor 可看到所有可用 skill 的列表、当前 listing 占了多少上下文预算，以及 description 是否被截断。如果你怀疑被加载了但模型没遵循，强化 description 的触发短语、把「Use when…」的同义词写进 when_to_use。注意 top-level skill 目录在会话中创建需要重启才会被识别，mid-session 改名则会被自动重载。

skill 和 plugin 到底什么关系，可以单独发布 skill 吗？

skill 是最小可加载单元，plugin 是一组 skill + commands + agents + hooks + MCP 服务器的发行包。单独发布一个 skill 完全可行——把目录放进 ~/.claude/skills/ 就能个人用，提交到项目 .claude/skills/ 就能团队共享。想跨项目/对外分发就必须包成 plugin 并在 marketplace.json 中登记，按名字用 /plugin install name@marketplace 安装。plugin-name 是不可变 slug，重命名要写 renames 映射让旧安装自动迁移。

官方参考资料

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