Claude Code Skills 是一种可复用、自动触发的 AI 能力扩展机制，支持将领域知识、工作流和最佳实践封装为可发现、可组合的模块。Skills 基于 Progressive Disclosure（渐进式加载）架构，具备灵活的前置字段配置和三种调用方式（用户、Claude、自动），大幅提升了 AI 协作与自动化效率。本文将详解 Skills 的原理、结构、配置及与旧版 Commands 的核心区别，帮助你系统掌握 Claude Code 的技能体系。

Claude Code Skills 体系详解：构建可复用、可自动触发的 AI 技能

Claude Code Skills 是什么？简单来说，Skills 是一种基于文件系统的 AI 能力扩展机制，可将专业知识、工作流和团队最佳实践打包成“技能”，让 Claude 在需要时自动加载、复用和组合这些能力。相比传统的 prompt 或一次性指令，Skills 支持自动发现、按需加载和多场景复用，是 Claude Code 生态的核心扩展方式。

Skills 体系不仅提升了 AI 的专业性和一致性，还极大减少了重复指令输入，支持团队共享与自动化，适用于个人、项目和企业级场景。Skills 机制已全面取代并升级了旧版 Slash Commands（斜杠命令），成为推荐的扩展方式。

一、Skills 的架构与工作原理

1. Progressive Disclosure：渐进式加载架构

Skills 采用 Progressive Disclosure 架构，将技能内容分为三个加载层级，只有在真正需要时才加载详细内容，极大优化了上下文窗口的利用效率：

层级	何时加载	令牌消耗	内容说明
Level 1: 元数据	启动时总是加载	~100 tokens/Skill	YAML frontmatter 的 name 和 description
Level 2: 指令正文	技能被触发时	<5k tokens	SKILL.md 主体，包含详细指令与范例
Level 3+: 资源文件	需要时加载	几乎无限	关联脚本、模板、文档等，仅按需读取

这种架构让你可以放心安装大量 Skills，而不会影响 Claude 的响应速度或上下文容量。只有 Skill 被触发时，才会将详细内容注入到 AI 的上下文中。

2. 多层次发现与优先级

Claude Code 会自动发现以下目录下的 Skills：

• 项目级：.claude/skills/<skill-name>/SKILL.md
• 个人级：~/.claude/skills/<skill-name>/SKILL.md
• 企业级：组织统一配置
• 插件内：<plugin>/skills/<skill-name>/SKILL.md

优先级为：企业 > 个人 > 项目。插件 Skill 独立命名空间不会冲突。支持嵌套目录和 --add-dir 动态加载，适合 monorepo 等复杂项目结构。

3. 与旧版 Slash Commands 的关系

Skills 体系已全面兼容并替代了旧版 Slash Commands（见Slash Commands 完整参考）。原有 .claude/commands/ 目录仍可用，支持相同 frontmatter 字段，但建议新开发统一采用 Skills 目录结构。同名时，Skills 优先生效。

二、Skill 文件结构与配置详解

1. 目录结构示例

my-skill/
├── SKILL.md           # 主体指令与说明（必需）
├── templates/         # 模板文件
│   └── output-format.md
├── scripts/           # 可执行脚本
│   └── validate.sh
├── references/        # 参考文档
│   └── api-spec.md
└── examples/          # 示例输出
    └── sample.md

2. SKILL.md 前置字段（Frontmatter）全表

字段	说明
name	技能名（小写字母/数字/短横线，≤64字符，不能含“anthropic”或“claude”）
description	技能作用+触发场景（≤1024字符），决定自动触发匹配度
argument-hint	/ 自动补全提示（如 [filename] [format]）
disable-model-invocation	true 时仅用户可触发，Claude 不会自动调用
user-invocable	false 时隐藏在 / 菜单，仅 Claude 可自动调用
allowed-tools	限定可用工具（如 Read, Grep, Glob）
model	指定激活时用的模型（如 opus、sonnet）
effort	任务强度覆盖（low/medium/high/max）
context	fork 时以子代理独立上下文运行
agent	指定子代理类型（如 Explore、Plan）
shell	指定命令行环境（bash 默认，或 powershell）
hooks	技能级生命周期钩子（详见Hooks 指南）

范例 frontmatter：

---
name: code-review
description: 全面代码审查，关注安全、性能与质量。用户请求代码审查、分析、评估 PR 时触发。
argument-hint: "[file]"
disable-model-invocation: false
user-invocable: true
allowed-tools: Read, Grep
context: fork
agent: Explore
shell: bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
---

3. SKILL.md 主体内容

• 指令说明：分步骤明确指引 Claude 如何执行
• 示例：具体输入输出样例
• 引用其它文件：用相对路径引用模板、参考文档等

内容建议 ≤500 行，详细资料分文件放 supporting files。

4. 动态变量与上下文注入

支持如下动态变量与命令输出注入：

变量	说明
$ARGUMENTS	用户传入的全部参数
$ARGUMENTS[N] 或 $N	第 N 个参数（0 起）
${CLAUDE_SESSION_ID}	当前会话 ID
${CLAUDE_SKILL_DIR}	技能目录路径
!`command`	执行 shell 命令并内联输出

示例：

---
name: pr-summary
description: 总结 PR 变更
context: fork
agent: Explore
---
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`

三、Skill 的三种调用方式

Claude Code Skills 支持三种调用模式，灵活适配不同场景：

配置	用户可触发	Claude 可自动触发
默认	✅	✅
disable-model-invocation: true	✅	❌
user-invocable: false	❌	✅

• 用户调用：通过 /skill-name 指令直接触发，适合显式操作（如 /deploy）。
• Claude 自动调用：Claude 根据 description 匹配用户自然语言请求，自动选择最合适的 Skill（如“请帮我做代码审查”）。
• 自动触发：有些技能仅供 Claude 背景知识用，不在菜单显示（如品牌语气、领域规范）。

调用控制建议：

• 有副作用的操作（如部署、提交）建议加 disable-model-invocation: true，避免 Claude 擅自执行。
• 仅作知识补充的技能（如 brand-voice）用 user-invocable: false，不暴露给用户。

四、Skill 类型与典型用法举例

• 参考类：补充知识、规范、风格指南（如 brand-voice skill）
• 任务类：分步骤操作指令（如 blog-draft skill、code-review skill）
• 自动化脚本：结合脚本自动化处理（如 doc-generator skill、refactor skill）
• 项目文档：如 claude-md skill，自动生成 CLAUDE.md

更多实战案例可参考：Claude Code 完全入门 和各 Skill 专文。

五、Skill 的管理与共享

• 查看已安装技能：

  ls ~/.claude/skills/
  ls .claude/skills/

  或直接问 Claude：“What Skills are available?”

• 编辑/更新技能：直接修改 SKILL.md 文件，重启 Claude Code 或保存后即时生效（--add-dir 支持热加载）。

• 团队共享：项目级技能放 .claude/skills/，通过 git 共享。

• 插件分发：打包到插件的 skills/ 目录，统一分发。

• 安全建议：仅安装信任来源的技能，Skill 可包含脚本与工具调用，务必审核全部内容。

六、Skill 与其它扩展机制的区别

功能	触发方式	适用场景
Skills	自动/手动	复用知识、工作流
Slash Commands	手动	快捷命令（现已合并进 Skills）
Subagents	自动委托	复杂任务分工，详见Subagents 指南
Memory (CLAUDE.md)	总是加载	持久项目上下文，见CLAUDE.md 深度指南
MCP	实时	外部数据/服务集成，见MCP 实战
Hooks	事件驱动	自动校验、格式化等，见Hooks 完全指南

更多对比可参考：六大扩展机制对比。

---

FAQ

Q: Skills 和旧版 Slash Commands 有什么区别？ A: Skills 体系更强大，支持自动触发、分层加载、丰富的前置字段和目录结构，已全面兼容并替代 Slash Commands，建议新开发统一用 Skills。

Q: Claude 为什么没有自动触发我的 Skill？ A: 可能是 description 不够具体，缺少关键词，或 Skill 被排除（如描述超出预算）。请优化描述并用 /context 检查加载情况。

Q: 如何让某个 Skill 只允许用户手动触发？ A: 在 SKILL.md 的 frontmatter 加 disable-model-invocation: true，这样 Claude 不会自动调用该技能。

---