09｜触类旁通：SKILL.md 结构与触发机制

Skills 并不是简单的“能力扩展机制”，它本质上是一种按需加载的认知结构。与其把所有知识常驻在上下文中，不如把它们封装成可独立触发的能力单元。当模型判断当前任务涉及某个特定领域时，再加载对应的知识与操作流程。因此，我们可以给 Skills 一个更精确的定义：Skills 是一种可被语义触发的能力包，它包含领域知识、执行步骤、输出规范与约束条件，并在需要时渐进式加载到主 Agent 的认知空间中。

Agent 生态中有四大支柱，每个都解决了一个根本性问题。

img

• Tools 是行动原语。它回答的是能做什么。读文件、改代码、执行 Bash 命令……这些是操作层面的能力，类似人的双手。

• SubAgents 是执行分工。它回答的是谁来做。当任务复杂到需要独立上下文时，子代理承担专职职责，类似团队中的同事。

• Hooks 是流程规则。它回答的是什么时候检查。它们在关键节点自动触发质量校验或合规约束，类似企业中的质检流程。

• 而 Skills 回答的，是另外一个非常关键的问题：“怎么做，以及何时做”，它不是工具，也不是分工机制。它是一种可操作知识结构。

Skills 的真正突破点，在于它把能力的“语义定义权”交给模型。人不再编排具体执行路径，而是定义能力的边界与含义。模型根据 description 理解能力语义，并在运行时决定是否加载、何时加载。这看似只是增加了一个字段，却完成了一次范式跃迁。我们从“人调度模型”，走向“模型调度能力”。

企业本体论视角：Skills 是组织的 SOP 体系

如果把 Claude Code 的技术栈映射到企业组织结构，我们会发现一种高度对称的关系。Tools 对应员工的操作工具；SubAgents 对应岗位分工；Hooks 对应质量与合规流程；CLAUDE.md 类似企业文化与通用规章；MCP Servers 像外部合作伙伴；Plugins 是对外打包的解决方案。

而 Skills，正是企业的 SOP 体系。

img

Skill 触发机制

和 Sub-Agents 类似，Skills 的触发机制靠 LLM 语义推理，而非精确匹配。Claude 读取所有 Skills 的 description，通过语义理解判断当前对话是否匹配某个 Skill。

img

Skill 模板

1、YAML frontmatter，是通过---包裹的元数据

2、正文，是技能的具体说明

3、辅助文件：.claude/skills//SKILL.md——每个 Skill 在自己的目录中，可以包含辅助文件（此处只有主文件，下一讲中的示例我们将看到辅助文件）。

因此，我给你总结了一个 description 写作公式：description = [做什么] + [怎么做] + [什么时候用]

Skills Frontmatter 字段详解

Claude Code 官方支持的完整 frontmatter 字段如下。

---
name: my-skill-name # 可选：Skill 标识符（省略则用目录名）
description: What this does # 推荐：触发器（最重要！）
argument-hint: "[issue-number]" # 可选：自动补全时的参数提示
disable-model-invocation: true # 可选：禁止 Claude 自动触发
user-invocable: false # 可选：对用户隐藏 /skill-name
allowed-tools: # 可选：限制可用工具
  - Read
  - Grep
  - Glob
model: sonnet # 可选：指定执行模型
context: fork # 可选：在子代理中隔离执行
agent: Explore # 可选：context: fork 时的代理类型
hooks: # 可选：作用域为此 Skill 的 Hooks
  PreToolUse:
    - matcher: Write
      hooks:
        - type: command
          command: "echo 'Write called in skill'"
---

其中所有字段都是可选的，但强烈建议提供 description，否则 Claude 无法判断何时使用。

让我逐一解释核心字段：

• name 字段：最大 64 字符，只能使用小写字母、数字、连字符，推荐使用动名词形式：code-reviewing、api-documenting、bug-fixing。如果省略了这个字段（通常不大可能啦），则自动使用目录名（.claude/skills/code-reviewing/ → name 为 code-reviewing）

• description 字段：这是最重要的字段——它决定 Skill 何时被触发。这个字段应该包含两部分信息：这个 Skill 做什么，以及什么情况下使用它。如果省略了这个字段（也不大可能啦），系统会使用 Markdown 正文的第一段作为 description。

注意：所有 Skill 的 description 会被加载到上下文中供 Claude 判断选择，默认总预算为 15,000 字符。如果你的 Skills 很多，导致 description 被截断，可以运行 /context 查看警告，并通过环境变量 SLASH_COMMAND_TOOL_CHAR_BUDGET 调大预算。

• argument-hint 字段：自动补全提示，为用户提供参数格式提示，在输入 /skill-name 时系统会自动补全显示：

argument-hint: "[issue-number]"          # /fix-issue [issue-number]
argument-hint: "[filename] [format]"     # /convert [filename] [format]

• disable-model-invocation 和 user-invocable这两个字段组合起来控制“谁能触发这个 Skill”。

img

allowed-tools 字段用来限制 Skills 被激活时 Claude 能使用的工具。Skills 支持的工具包括：

img

还可以更精细地控制 Bash 命令。

allowed-tools:
  - Bash(git:*)      # 只能执行 git 命令
  - Bash(npm test:*) # 只能执行 npm test 相关命令

• 权限交互：allowed-tools 中的工具在 Skill 激活时无需逐次确认。你的全局权限设置（/permissions）仍然控制其他工具的审批行为。

• context、agent、model——Skills 的执行环境。

• hooks——Skill 级别的 Hooks，可以为 Skill 定义仅在其生命周期内生效的 Hooks。

总结

什么时候用参考型 Skill，什么时候用任务型 Skill？什么时候必须手动触发？

简而言之，CLAUDE.md 放“Claude 每次都该知道的少量规则”（< 100 行）；Skill 放“特定场景下的详细指令和知识”（可以很长，按需加载）。如果你犹豫放 CLAUDE.md 还是 Skill，那么就放 Skill，并在 CLAUDE.md 里加一行引用。

AI 总览

Skills 是 Agent 生态中一种按需加载的认知结构，它将领域知识、执行步骤等封装成可语义触发的能力单元，解决了在有限上下文窗口中，Agent 在正确时刻获取正确知识的问题。它作为可操作知识，实现了从“人调度模型”到“模型调度能力”的范式转变，并可作为企业SOP体系的数字化映射。

Skills 核心概念与生态位

Skills 的本质与定义

• Skills 是一种按需加载的认知结构，封装了领域知识、执行步骤、输出规范和约束条件 [citation-3]。
• 它通过语义触发，渐进式加载到主 Agent 的认知空间中 [citation-3]。
• 核心解决 Agent 在有限上下文窗口中，在正确时刻拥有正确领域知识的认知问题 [citation-4]。

Agent 生态四大支柱

• Tools: 行动原语，回答“能做什么”，类似人的双手 [citation-5]。
• SubAgents: 执行分工，回答“谁来做”，处理复杂任务的专职职责 [citation-6]。
• Hooks: 流程规则，回答“什么时候检查”，在关键节点触发质量校验或合规约束 [citation-7]。
• Skills: 可操作知识结构，回答“怎么做，以及何时做”，提供特定领域的规范、流程和模式 [citation-8]。

Skills 作为可操作知识

• 与静态文档不同，Skill 具备语义入口、定义执行步骤、约束输出格式、限制工具范围，并可自动验证 [citation-9]。
• 实现了从“人调度模型”到“模型调度能力”的范式转变，模型根据 description 理解并决定何时加载能力 [citation-10]。
• “技能化”思路已扩展到其他智能体平台和AI工程工具，如Claude的Agent Skills公用仓库和Coze的技能商店 [citation-11]。

企业本体论视角下的 Skills

Skills 作为组织的 SOP 体系

• Skills 类似于企业的标准操作程序（SOP），将组织的“做事方式”封装为可语义调用的能力单元 [citation-12]。
• 它使企业经验结构化，不再依赖个体记忆或散落文档，而是模型可理解、选择和继承的结构 [citation-13]。
• 通用模型通过Skills获得专业化、按需调用的能力，应用于数据分析、校验、报告生成等任务 [citation-14]。

Skills 在 Agent 系统中的层级

• Tools: 回答“能做什么” [citation-15]。
• Skills: 回答“该怎么做” [citation-16]。
• Agents: 回答“什么时候做什么，以及由谁来做” [citation-17]。
• 企业本体论: 回答“在什么世界里做”，是组织共享的语义边界 [citation-18]。
• Skills 连接“行动能力”与“语义世界”，将企业本体中的概念与规范转译为可执行行为模式 [citation-19]。

Skill 的触发机制与设计

Skills 触发方式

• 支持两种触发方式：用户通过斜杠命令显式触发（如 /review）和 Claude 自动进行语义判断触发 [citation-20]。
• 这种双向触发机制满足了用户明确需求和描述性需求两种场景 [citation-21]。
• 触发机制依赖 LLM 语义推理，而非精确匹配，Claude 通过理解 description 判断相关性 [citation-22]。

渐进式加载与上下文优化

• Skills 采用渐进式加载机制，仅将 description 常驻上下文，全文在触发时加载，显著节省 token 成本 [citation-23]。
• 当用户请求可能匹配多个 Skills 时，Claude 评估 description 相关性，选择最相关者，或在不确定时询问用户 [citation-24]。
• disable-model-invocation: true 的 Skill 其 description 不会加载到上下文，只能通过用户命令触发 [citation-25]。

Skill 设计原则与结构

• SKILL.md 应控制在 500 行以内，详细参考资料应移至独立文件并引用 [citation-29]。
• Skills 存放位置决定使用权限和优先级：Enterprise > Personal > Project [citation-30]。
• Monorepo 项目中，Claude Code 会自动发现子目录下的 .claude/skills/ [citation-31].

Skills 的类型与实践

参考型 Skills

• 定义“在这个世界里，什么是正确的做法”，如API设计标准、代码风格，属于“世界规则” [citation-35]。
• 通常由模型根据语义自动判断加载，不主导行动，而是塑造行动方式 [citation-35]。
• 示例：api-conventions Skill，定义API设计模式、响应格式、错误处理等，无执行步骤和输出模板 [citation-39].

任务型 Skills

• 定义明确的行动，如部署、发布、迁移、生成报告，属于“世界事件” [citation-36]。
• 这类行为通常具有边界和风险，常需显式触发，配合 disable-model-invocation 使用 [citation-36]。

description 写作公式

• description = [做什么] + [怎么做] + [什么时候用]，确保清晰具体，避免模糊词汇 [citation-48]。
• 好的 description 应列出具体动作、包含用户可能说的关键词，并明确触发场景 [citation-47]。
• 多个 Skills 之间 description 应有明确区分，避免功能重叠导致冲突 [citation-52]。

Skills Frontmatter 字段

• name: Skill名称，最大64字符，推荐动名词形式 [citation-56]。
• description: 最重要字段，决定Skill何时被触发，包含“做什么”和“何时用” [citation-57]。
• argument-hint: 为用户提供参数格式提示，用于斜杠命令自动补全 [citation-59]。
• disable-model-invocation 和 user-invocable: 控制Skill的触发方式（模型自动或用户手动） [citation-62]。
• allowed-tools: 限制Skill激活时Claude能使用的工具，支持精细控制Bash命令 [citation-65]。
• context, agent, model: 定义Skills的执行环境 [citation-69]。
• hooks: 定义Skill级别的Hooks，仅在其生命周期内生效 [citation-70]。