Claude Code Skills 是存放在 .claude/skills/<name>/SKILL.md 的可复用过程文件，支持 Claude 自动调用，在 session 启动时注入上下文。本文系统整理 14 个配置字段，说明两种 Skill 调用模式，并结合官方实战案例讲解正确用法。

Claude Code Skills 完全指南：14 个配置字段与 5 个官方技能

什么是 Skill

Skill 是 Claude Code 的可复用过程文件，存放在 .claude/skills/<name>/SKILL.md。与 Commands 不同，Skill 的 description 会在 session 启动时注入上下文，Claude 可以根据语义自动判断何时调用。

Skill 的两种使用方式：

1. 独立 Skill：由 Claude 或 Command 通过 Skill tool 直接调用
2. Agent Skill（预加载）：在 Subagent 的 skills frontmatter 中声明，启动时完整注入 agent 上下文，作为 agent 的"领域知识"

适合用 Skill 的场景：

• 需要 Claude 自动感知并调用的可复用过程
• 可以从多个 Command、Agent 或 Claude 自身调用的通用能力
• 需要通过文件 glob 路径按需激活的规则

14 个 Frontmatter 字段

字段	类型	必填	说明
name	string	否	显示名和 /slash-command 标识符，省略时使用目录名
description	string	推荐	Skill 的说明和触发时机，注入 session 上下文供语义匹配
when_to_use	string	否	额外的触发场景描述，追加到 description，计入 1536 字符上限
argument-hint	string	否	自动补全时显示的提示（如 [filename]）
disable-model-invocation	boolean	否	设为 true 阻止 Claude 自动调用，只允许用户手动触发
user-invocable	boolean	否	设为 false 则从 / 菜单隐藏，仅用于 agent 预加载
allowed-tools	string	否	此 skill 激活时无需提示即可执行的工具
model	string	否	执行此 skill 时使用的模型（如 haiku、sonnet、opus）
effort	string	否	调用时的思考深度：low/medium/high/xhigh/max
context	string	否	设为 fork 则在隔离的 subagent 上下文中运行此 skill
agent	string	否	context: fork 时使用的 subagent 类型，默认 general-purpose
hooks	object	否	仅作用于此 skill 的生命周期钩子
paths	string/list	否	限制自动激活的文件 glob 模式，仅在操作匹配文件时加载此 skill
shell	string	否	!`command` 块使用的 shell：bash（默认）或 powershell

关键字段详解

description 是触发器，不是摘要：写给模型看的，应该描述"我应该在什么时候触发这个 skill"。例如："Use this skill PROACTIVELY when reviewing TypeScript files for type safety issues" 比 "TypeScript 代码审查 skill" 更有效。

context: fork：让 skill 在隔离的 subagent 中执行，主会话只看到最终结果，不看中间步骤。适合需要大量文件读取或工具调用但你不希望污染主上下文的场景。

paths 按路径激活：通过文件 glob 模式实现懒加载。例如：

paths: "src/**/*.ts,src/**/*.tsx"

只有当 Claude 操作匹配这些路径的文件时，才自动将此 skill 加入上下文。适合为特定语言或模块定制的规则，避免所有 skill 常驻内存。

user-invocable: false：隐藏 skill 的 / 菜单入口，设计为只在 agent 的 skills 字段中预加载使用，不对用户直接暴露。

两种 Skill 调用模式对比

在 weather 编排案例中可以清晰看到两种不同模式：

模式 1：独立 Skill（由 Command 或 Claude 直接调用）

# .claude/skills/weather-svg-creator/SKILL.md
---
name: weather-svg-creator
description: 创建迪拜天气 SVG 卡片，写入 weather.svg 和 output.md
---

• 由 Command 通过 Skill tool 显式调用
• 有完整的对外 / 命令入口（/weather-svg-creator）
• 从调用上下文中接收温度数据作为输入

模式 2：Agent Skill（预加载到 Subagent 中）

# .claude/skills/weather-fetcher/SKILL.md
---
name: weather-fetcher
description: 从 Open-Meteo API 获取迪拜当前温度
user-invocable: false
---

# .claude/agents/weather-agent.md
---
name: weather-agent
skills:
  - weather-fetcher  # 预加载，启动时完整注入
---

• user-invocable: false：不对用户暴露
• 在 agent 启动时完整注入上下文，成为 agent 的"内置知识"
• agent 自主决定何时、如何运用这个 skill

核心区别：Agent Skill 是给 agent 看的领域知识；独立 Skill 是给 Claude 或 Command 调用的工具接口。

5 个官方内置技能

#	Skill	说明
1	simplify	审查修改过的代码，找出可复用、优化质量和效率的地方
2	batch	对多个文件批量执行命令
3	debug	调试失败的命令或代码问题
4	loop	按周期间隔重复运行提示词或命令（最长 7 天）
5	claude-api	使用 Claude API 或 Anthropic SDK 构建应用，在检测到 anthropic/@anthropic-ai/sdk 导入时自动触发

官方还维护了一个社区 Skills 仓库，包含可直接安装的社区技能。

Skill 文件结构最佳实践

Skill 是文件夹，不是单个文件。推荐结构：

.claude/skills/my-skill/
├── SKILL.md          # 主 skill 定义（必须）
├── references/       # 参考文档
│   └── api-docs.md
├── scripts/          # 辅助脚本
│   └── helper.ts
└── examples/         # 示例
    └── sample.md

通过渐进式披露（progressive disclosure）控制 SKILL.md 的信息量：核心指令放在 SKILL.md 开头，详细参考资料放在子目录中按需引用。

如何创建 Skill

Claude Code 提供 skill-creator 技能（如果已安装），或直接让 Claude 生成：

claude
> 帮我创建一个 skill，当我操作 Python 文件时自动检查是否有类型注解问题

Claude 会在 .claude/skills/<name>/SKILL.md 中生成配置文件。

FAQ

Q: Skill 和 Command 都可以被用户调用，区别在哪里？ A: 最核心区别是 上下文注入时机。Skill 的内容在 session 启动时就注入上下文，Claude 可以随时感知并自动调用；Command 的内容只在用户明确输入 /command-name 时才注入。如果你想让 Claude 自动判断何时执行某个过程，用 Skill；如果需要用户明确触发并控制工作流入口，用 Command。

Q: 为什么 Boris 说"如果一件事你每天做超过一次，就把它做成 skill 或 command"？ A: 因为 Skill 的 description 会持久化到上下文，Claude 下次看到类似场景时会自动调用，省去你每次重复描述需求。命令则让工作流可复现、可版本控制、可团队共享。

Q: context: fork 会让 skill 变慢吗？ A: 是的，fork 需要启动一个新的 subagent 上下文，比直接执行略慢。只在 skill 需要大量中间步骤（会污染主上下文）时才使用。

Q: 一个 skill 可以调用另一个 skill 吗？ A: 可以，在 SKILL.md 的正文中用 Skill tool 调用其他 skill。也可以在 agent 的 skills 字段中预加载多个 skill，让 agent 自行组合使用。