古法编程

Claude Code技能系统是结构化代理工作流的核心扩展点，它通过15个Frontmatter字段精细控制技能行为，内置9个常用功能如代码审查和调试，并存在“直接调用”和“Agent预加载”两种调用模式，分别以weather-svg-creator和weather-fetcher为典型示例。

Claude Code Skills 深度解析：15 个字段、9 个内置技能、两种调用模式

在从 Vibe Coding 到 Agentic Engineering 的转型中，Claude Code的技能（Skills）模块扮演着关键角色。技能是一个可组合的指令集，存储于 .claude/skills/ 目录下，以 SKILL.md 文件定义。它们不是独立的代理，而是供命令（Commands）或子代理（Subagents）调用的标准化任务单元。理解其配置字段、内置类型和调用模式，是构建复杂自动化工作流的基础。

15 个 Frontmatter 字段详解

每个技能的核心是其 SKILL.md 文件头部的 YAML Frontmatter。这 15 个字段决定了技能的元信息、行为模式和权限控制。

字段 类型 是否必需 说明
name string 否 显示名称和 /slash-command 标识符。省略时默认为目录名。
description string 推荐 技能功能的描述。会显示在自动补全中，也用于 Claude 的自动发现。
when_to_use string 否 为 Claude 提供额外上下文，说明何时应调用此技能——包括触发短语和示例请求。它会被附加到 description 中，并计入 1,536 字符的上限。
argument-hint string 否 自动补全时显示的提示（例如 [issue-number], [filename]）。
arguments string/list 否 用于技能内容中 $name 替换的命名位置参数。接受空格分隔的字符串或 YAML 列表，名称按顺序映射到参数位置。
disable-model-invocation boolean 否 设置为 true 可防止 Claude 自动调用此技能。
user-invocable boolean 否 设置为 false 可从 / 菜单中隐藏——技能仅作为背景知识，旨在供代理预加载。这是区分两种模式的关键字段。
allowed-tools string 否 当此技能激活时，无需权限提示即可使用的工具。
model string 否 技能运行时使用的模型（例如 haiku, sonnet, opus）。
effort string 否 调用时覆盖模型的推理强度级别（low, medium, high, xhigh, max）。
context string 否 设置为 fork 可在一个隔离的子代理上下文中运行技能。
agent string 否 当设置 context: fork 时指定的子代理类型（默认为 general-purpose）。
hooks object 否 限定于此技能的作用域生命周期钩子。
paths string/list 否 限制技能何时自动激活的 Glob 模式。接受逗号分隔的字符串或 YAML 列表。仅当处理匹配文件时，Claude 才会加载该技能。
shell string 否 用于 !`command` 代码块的 Shell 类型——bash（默认）或 powershell。需要设置环境变量 CLAUDE_CODE_USE_POWERSHELL_TOOL=1。

关键字段解读：

  • user-invocable: false：这是创建“Agent Skill”的核心。当设为 false 时，该技能不会出现在用户的 / 菜单中，仅供代理在初始化时作为知识库预加载。
  • context: fork：此设置能让技能在独立的子代理上下文中运行，避免干扰主对话的上下文，适合执行长时间或隔离的任务。
  • allowed-tools：预先声明技能所需的工具（如 Bash, WebFetch），可以简化用户的权限确认步骤。

9 个内置官方技能

Claude Code 预置了 9 个开箱即用的技能，覆盖了常见的开发任务。

# 技能 描述
1 code-review 审查当前 diff 的正确性错误，可选择推理强度级别。--comment 标志可将发现作为行内 PR 评论发布。
2 batch 批量对多个文件运行命令。
3 debug 调试失败的命令或代码问题。
4 loop 按定时间隔（最长 3 天）运行一个提示或斜杠命令。
5 claude-api 使用 Claude API 或 Anthropic SDK 构建应用。当检测到 anthropic 或 @anthropic-ai/sdk 导入时触发。
6 fewer-permission-prompts 扫描会话记录，找出常见的只读 Bash/MCP 调用，并向 .claude/settings.json 添加一个优先级允许列表以减少权限提示。
7 run 启动并驱动项目应用，以查看更改在实际应用中的效果（而不仅仅是测试）。要求 v2.1.145。
8 verify 构建并运行应用，以确认代码更改确实有效，而不回退到测试或类型检查。要求 v2.1.145。
9 run-skill-generator 教授 /run 和 /verify 如何构建和启动项目——在 .claude/skills/run-<name>/ 记录一个按项目定制的启动配方。要求 v2.1.145。

这些内置技能提供了强大的基础功能。社区维护的可安装技能可在官方技能仓库找到。

两种调用模式：直接调用 vs Agent 预加载

理解技能的两种根本模式是高效使用它们的关键。这两种模式在项目实现中得到了清晰对比。

模式 调用方式 示例 核心区别
Skill（技能） 通过 Skill(skill: “name”) 工具直接调用 weather-svg-creator 由命令或代理显式调用，执行特定任务。
Agent Skill（代理技能） 通过 skills: 字段在启动时预加载 weather-fetcher 在代理初始化时注入上下文，作为背景知识存在，不直接调用。

示例分析：Weather Fetcher 与 Weather SVG Creator

weather-fetcher 是典型的 Agent Skill： 其 Frontmatter 包含 user-invocable: false，这意味着用户无法在菜单中直接调用它。它在被某个代理（例如 weather-agent）通过 skills: [“weather-fetcher”] 字段引用后，其内容（获取天气数据的指令）会作为背景知识注入到该代理的上下文中。当代理需要天气数据时，它知道如何去做，但这个技能本身不会作为独立步骤被调用。

weather-svg-creator 是典型的直接调用 Skill： 它没有设置 user-invocable: false，因此可以通过 /weather-svg-creator 斜杠命令直接调用。它接收来自对话上下文的天气数据，并专注于创建 SVG 卡片和输出文件。这是一个可复用、可独立触发的任务单元。

在Command → Agent → Skill 架构中，命令可以编排多个代理，而代理则利用预加载的 Agent Skills 获取领域知识，并调用具体的 Skills 来完成子任务。

如何创建自己的技能

创建技能很简单。只需在 .claude/skills/ 目录下新建一个文件夹，并在其中创建 SKILL.md 文件。

目录结构：

.claude/
└── skills/
    └── my-custom-skill/
        └── SKILL.md

让 Claude 帮你生成： 你可以直接告诉 Claude：“请为我创建一个技能，用于……”，它会生成包含完整 Frontmatter 和指令体的 Markdown 文件。

技能体编写： Frontmatter 之后是技能的正文，使用 Markdown 编写。它应该包含清晰的任务描述、分步指令以及任何必要的上下文。例如，天气 SVG 创建者技能包含了创建 SVG、写入文件和写入摘要的详细步骤。

通过精心设计 Frontmatter 字段并选择适当的调用模式，你可以将重复性工作封装成可靠的技能，从而构建出强大而可维护的编排工作流。

FAQ

Q: 技能文件必须存放在哪里？ A: 技能文件存储在项目根目录下的 .claude/skills/<skill-name>/SKILL.md。Claude Code 会自动发现此目录下的所有技能。

Q: 必须配置所有 15 个字段吗？ A: 不必。只有 description 是被推荐的。多数字段都有合理默认值。例如，省略 name 将使用目录名，user-invocable 默认为 true。

Q: “Skill” 和 “Agent Skill” 最主要的区别是什么？ A: 最主要的区别在于调用方式。“Skill”通过工具显式直接调用，执行一个具体动作；“Agent Skill”通过设置 user-invocable: false 并作为代理的背景知识预加载，为代理提供特定领域的操作指南，但自身不作为一个独立的调用步骤出现。