跳至主要內容

基础与生态概览

2026/6/27大约 14 分钟

本文档基于 Claude Code v2.1.191 前后版本及 2026 年 6 月社区 Skills 生态编写。

基础与生态概览

什么是 Skill

Skill 是 Claude Code 对 AI 编程 Agent 的一种可复用能力扩展机制。一个 Skill 就是一个包含 SKILL.md 文件的目录，它教会 Claude 如何以结构化的方式完成特定任务。

把 Skill 想象成给 Claude 的一份"新员工入职手册"——它不是一次性的提示词，而是一个持久的、可被反复调用的能力模块。一旦安装，Claude 在每次对话中自动知道什么时候该用这个 Skill，以及怎么用。

Skill 遵循 Agent Skills 开放标准。这意味着同一个 SKILL.md 文件可以在多个 AI 编程工具之间通用——Claude Code、Cursor、Windsurf、Gemini CLI、GitHub Copilot、OpenCode、Codex CLI 等。写一次，全平台运行。

为什么需要 Skill

没有 Skill 时，Claude Code 是一个"通才"——它对很多事情都知道一点，但不精通任何特定领域。每次对话你都需要重新解释你的偏好、流程和工作流。更关键的是：

  • 上下文浪费：每次在对话中重复"请用 TDD 方式开发"、"先写测试再实现"这类指令，消耗宝贵的 Context Window
  • 结果不一致：同样的需求，不同会话中 Claude 可能给出不同风格的输出，因为没有标准化的指令约束
  • 知识无法沉淀：你的最佳实践存在于你的脑子里，无法变成 Claude 的"肌肉记忆"

Skill 解决了这些问题——教会 Claude 一次，永久受益。

Skill 不是什么：概念辨析

Claude Code 中有多个扩展机制，容易混淆。以下是明确区分：

概念定位触发方式典型场景
CLAUDE.md项目级持久记忆每次会话自动加载"这个项目用 pytest"、"缩进用 2 空格"
Skill可复用能力模块模型自动匹配触发，或 /command 手动调用TDD 工作流、代码审查流程、前端设计规范
Slash Command简单提示词模板用户手动 /command已合并入 Skills 体系——定义了 argument-hint 的 Skill 自动生成 / 命令
MCP Server外部工具/数据连接工具调用（tool invocation）连接数据库、调用外部 API、文件系统访问
Plugin打包分发单位安装后自动激活包含多个 Skills + Hooks + Agents + MCP 的集合
Hook事件驱动的自动化脚本生命周期事件触发保存文件时自动格式化、提交前运行 lint
Subagent独立子会话执行者主 Agent 派发并行代码审查、独立执行某个任务

简化理解：

  • CLAUDE.md = "我是谁，我的习惯"（始终可见的自我描述）
  • Skill = "遇到 X 情况时，应该怎么做"（按需加载的指令集）
  • MCP = "给你连接外部世界的工具"（外部能力的管道）
  • Hook = "事情发生时自动运行的脚本"（事件的响应者）

Skill 的技术原理

三层渐进式披露（Progressive Disclosure）

Skill 的设计核心是渐进式披露——不是把全部内容一次性塞进上下文，而是分三个层级按需加载。这一设计使安装几十个 Skill 成为可能，而不会撑爆 Context Window。

第一层：元数据（YAML frontmatter）——进入 skill listing

Claude Code 每轮把已安装 Skill 的 name、description（及 when_to_use）载入 skill listing，预算默认占模型 context window 的 1%（skillListingBudgetFraction: 0.01）。这是 Claude 判断「要不要加载某个 Skill」的依据，不是把完整 SKILL.md 常驻系统提示词。

单条 description + when_to_use 合计上限 1536 字符（maxSkillDescriptionChars）。预算溢出时，低频 Skill 的 description 会先被缩短或 dropped（名字仍保留，自动匹配变弱）。详见 描述预算。

---
name: test-driven-development
description: Use when implementing any feature or bugfix, before writing implementation code
---

关键：description 字段决定了 Skill 是否会被触发。它同时包含"这个 Skill 做什么"和"什么时候应该用它"两方面的信息。这是一个写给模型看的字段，不是写给人看的摘要。

第二层：指令体（SKILL.md body）——匹配触发时加载

当 Claude 判断当前任务与某个 Skill 的 description 匹配时，它加载完整的 SKILL.md 正文（Skill 工具）。此时工作流指令、最佳实践、检查清单等内容才进入 Context Window。

第三层：关联文件（references/、scripts/、assets/）——仅在引用时加载

Skill 目录中可以包含额外的 Markdown 文件、Python/Shell 脚本、模板资源等。Claude 只在 SKILL.md 中显式引用这些文件时才会读取它们。

my-skill/
├── SKILL.md           # 第二层：主体指令
├── references/
│   ├── gotchas.md     # 第三层：常见陷阱（仅在需要时读取）
│   └── api-docs.md    # 第三层：API 参考（仅在需要时读取）
├── scripts/
│   └── helper.py      # 可执行脚本（运行但不占上下文）
└── assets/
    └── template.txt   # 资源模板

这种设计的精妙之处在于：Claude 知道有这些文件的存在（因为在安装时扫描了目录），但不会在不需要的时候读取它们。

自动触发 vs 手动调用

Skill 有两种触发方式：

自动触发（模型调用，Model-Invoked）

Claude 扫描当前任务，与所有已安装 Skill 的 description 字段做模式匹配。匹配成功时，自动加载 Skill 的完整指令并执行。

例如，当你说"给这个函数写测试"，Claude 检测到这与 test-driven-development Skill 的 description（"Use when implementing any feature or bugfix, before writing implementation code"）匹配，自动加载 TDD 指令，强制你先写测试再写实现代码。

手动调用（用户调用，User-Invoked）

Skill 定义了 argument-hint frontmatter 字段时，自动在 Claude Code 中生成 /skill-name 命令，输入 / 后会出现在自动补全列表中。

---
name: code-review
description: Review code for bugs, security issues, and maintainability
argument-hint: [file or directory to review]
---

然后用户可以手动触发：/code-review src/api/routes/users.ts

disable-model-invocation 字段

当你不希望 Claude 自动触发某个 Skill（只想通过 /command 手动调用）时，设置这个字段：

---
name: dangerous-operation
description: Perform a potentially destructive database migration
disable-model-invocation: true
---

这样 Claude 不会自动帮你跑数据库迁移，必须你显式输入 /dangerous-operation 才会执行。

描述预算（Description Budget）

一个常见的坑是：装了很多 Skill 但触发不了，原因就是描述预算被打爆了。

Claude Code 把所有已安装 Skill 的 name + description（以及 when_to_use）载入每轮 skill listing。预算占模型 context window 的 1%，默认 skillListingBudgetFraction: 0.01。此外，每个 Skill 的 description + when_to_use 合计还有单条上限 1536 字符（可通过 maxSkillDescriptionChars 调整，默认 1536）。

超过全局预算会发生什么？ 低频 Skill 的 description 会先被 shortened 或 dropped（只剩名字时 Claude 仍可调 /skill-name，但自动匹配变差）。用 /doctor 查看 truncation 数量与受影响 Skill。

经验上限：

  • 10 个 Skill 全量描述约占用 10K-15K tokens
  • 15-20 个是安全上限（含 bundled skills 和 Plugin 带来的 Skill）

诊断方法：

  • 运行 /doctor 查看哪些 Skill 描述被截断或丢弃
  • 运行 claude --verbose，查找 [skills] budget=... listed=... dropped=... 日志行

调优方法（按推荐顺序）：

  1. 首选：运行 /skills，禁用不常用的 Skill（disabled 的 Skill 不占预算）
  2. 在 ~/.claude/settings.json 中提高预算比例：
{
  "skillListingBudgetFraction": 0.02,
  "maxSkillDescriptionChars": 2048
}
  1. 设置环境变量 SLASH_COMMAND_TOOL_CHAR_BUDGET（固定字符数，优先级高于 fraction）
  2. 在 skillOverrides 中将低频 Skill 设为 "name-only" 或 "off"（四态见下表；在 /skills 中 Space 循环、Enter 写入 settings.local.json 或 settings.json）。Plugin 内的 Skill 不受 skillOverrides 影响，需用 /plugin disable 管理。
值对 Claude listing/ 菜单
on名字 + description可见
name-only仅名字可见
user-invocable-only不进 listing可见（仅手动）
off不进 listing隐藏
  1. 精简 description：把触发关键词放在前 100–150 字符

但最佳实践不是无限提高预算，而是控制安装数量——保留 10-15 个真正高频使用的核心 Skill。组合方案见 03 选型与组合方案，治理见 13 治理。

Skill 的存放位置与优先级

Claude Code 从四个位置加载 Skill，从高到低优先级：

位置路径生效范围优先级
Enterprise由 Managed Settings 部署全组织最高
Personal (全局)~/.claude/skills/<name>/SKILL.md当前用户的所有项目次高
Project (项目级).claude/skills/<name>/SKILL.md当前项目次高
Plugin<plugin>/skills/<name>/SKILL.mdPlugin 启用的所有项目标准

同名 Skill 的优先级：Enterprise > Personal > Project。任何级别的 Skill 都会覆盖同名的 bundled skill（例如项目级的 code-review 会替换内置 /code-review）。Plugin 的 Skill 使用 plugin-name:skill-name 命名空间，不会与其他来源冲突。

项目级 vs 全局级的实践建议：

  • 项目级（.claude/skills/）：与团队通过 git 共享，适合团队工作流规范
  • 全局级（~/.claude/skills/）：个人偏好的通用 Skill，跨所有项目可用

父目录自动发现：从启动目录向上到仓库根目录，每一层 .claude/skills/ 都会被加载。在子目录启动 Claude Code 时，根目录的 Skill 仍然可用。

嵌套目录按需发现：编辑 packages/frontend/ 下的文件时，packages/frontend/.claude/skills/ 下的 Skill 也会被加载。若与根目录同名，嵌套 Skill 以目录限定名出现（如 /apps/web:deploy）。

permissions.additionalDirectories 只授予文件访问，不会加载额外目录中的 Skills；只有 --add-dir / /add-dir 会加载该目录下的 .claude/skills/。

实时变更检测：~/.claude/skills/、项目 .claude/skills/ 以及 --add-dir 目录中的 SKILL.md 文本支持热重载。Plugin 的 hooks/MCP/agents 变更需运行 /reload-plugins。会话启动时不存在的 skills 目录，创建后需重启会话。

SKILL.md 结构速览

基本骨架

---
name: my-skill-name
description: What this skill does and when Claude should use it
---

# My Skill Name

## Instructions
Clear, step-by-step guidance for Claude to follow.

## Examples
Concrete examples of using this Skill.

Frontmatter 字段全集

字段必填说明
name否显示名称。命令名来自目录名（Plugin 根目录 SKILL.md 除外）。小写字母、数字、连字符，max 64
description推荐功能 + 触发时机。Claude 据此判断是否自动加载。与 when_to_use 合计 max 1536 字符
when_to_use否补充触发场景、示例话术。追加到 description 后一并展示，共享 1536 字符上限
argument-hint否补全时显示的参数提示，如 [issue-number]
arguments否命名 positional 参数，支持 $name 替换
disable-model-invocation否设为 true 禁止 Claude 自动加载，且 description 不会进入 listing（不占预算）。仅手动 /name 触发
user-invocable否设为 false 从 / 菜单隐藏。仅控制菜单可见性，不等于禁止模型调用
allowed-tools否该 Skill 激活时 Claude 可免确认使用的工具（如 Read Grep）
disallowed-tools否该 Skill 激活时从工具池移除的工具（如 AskUserQuestion）
model否该 Skill 激活时使用的模型（如 sonnet、opus），仅当前 turn 生效
effort否覆盖会话 Effort 等级：low / medium / high / xhigh / max
context否设为 fork 时在隔离的子代理上下文中运行
agent否context: fork 时指定子代理类型
hooks否该 Skill 生命周期的 Hooks
paths否Glob 模式，限制该 Skill 仅在操作匹配文件时激活
shell否行内命令使用的 Shell：bash（默认）或 powershell

agentskills.io 开放标准 中 name 和 description 为必填；Claude Code 侧仅 description 为推荐必填，省略时取正文第一段。

动态上下文注入

SKILL.md 正文中可用 !`command` 语法在 Skill 加载前执行命令，将输出内联到指令中：

## Current changes

!`git diff HEAD`

Summarize the changes above...

Claude 看到的是命令的实时输出，而非占位符。适合 diff、测试结果等随会话变化的内容。若需禁止 Skill 内 shell 执行，可在 settings 中设 "disableSkillShellExecution": true。

变量替换

SKILL.md 内容中支持以下变量：

变量说明
$ARGUMENTS调用时传入的全部参数
$ARGUMENTS[N] / $N按索引访问参数
${CLAUDE_SESSION_ID}当前会话 ID
${CLAUDE_EFFORT}当前 Effort 等级
$namearguments frontmatter 定义的命名参数
${CLAUDE_SKILL_DIR}Skill 所在目录的绝对路径

正文中的 \$ARGUMENTS 可输出字面量 $ARGUMENTS。若正文未包含 $ARGUMENTS，Claude Code 会在末尾自动追加 ARGUMENTS: 块。

篇幅建议：官方建议 SKILL.md ≤500 行；大 Skill 会参与内容 lifecycle 与 auto-compaction，compact 后需重新 invoke。

description 是 SKILL.md 中最重要的字段——它决定了 Skill 是否会被触发。Anthropic 官方明确建议：

"Write descriptions for the model, not for humans."
—— Anthropic 内部 Skills 工程博客，2026-06-03

好的 description 同时包含：

  1. 这个 Skill 做什么（capability description）
  2. 什么情况下应该用它（trigger conditions）

示例对比：

# ❌ 不好的 description（只描述了做什么，没说什么时候用）
description: A skill for code review

# ✅ 好的 description（同时说明了做什么和什么时候用）
description: Review code for bugs, security vulnerabilities, and maintainability issues. Use when the user asks to review code, mentions PR review, or says "check my changes"

Skill 生态的发展历程

关键时间节点

日期版本/事件意义
2025-10-16Claude Code v2.0.20Skills 首次引入。在此之前只有 Slash Commands（提示词模板），Skill 引入了文件系统目录结构、frontmatter 配置和自动触发
2025-12Anthropic 开源 anthropics/skills官方示范仓库（含 frontend-design 等）；skill-creator 后改为独立 Plugin，见 06 工具链
2025-12-18Agent Skills 开放标准发布agentskills.io 上线，同一 SKILL.md 可在 Claude Code、Cursor、Gemini CLI、Codex 等 26+ 平台使用
2026-01-07Claude Code v2.1.0Skills + Fork——Skill 可以在隔离的 fork 上下文中执行，引入了 context: fork 和 agent 字段
2026-01-09Claude Code v2.1.3Commands 与 Skills 合并——.claude/commands/ 与 .claude/skills/ 等价；带 argument-hint 的 Skill 自动生成 / 命令
2026-03Garry Tan 开源 gstackY Combinator CEO 的个人 Skill 集，开源后迅速突破 111K+ stars
2026-04Matt Pocock 开源 mattpocock/skills24 小时 22K stars，GitHub Trending 全球 #1。标志着"配置 AI 如何工作"成为严肃的工程实践
2026-04vercel-labs/skills CLI + skills.shnpx skills add / npx skills find 统一安装与发现
2026-06-03Anthropic 发布内部 Skills 博客《Lessons from building Claude Code: How we use skills》——公开了内部 9 类 Skills 分类体系和 9 条工程技巧

Bundled Skills（内置 Skill）

Claude Code 自带一组 bundled skills，每个会话默认可用（除非在设置中 disableBundledSkills）：

Skill用途
/code-review代码审查
/debug系统化调试
/batch批量处理
/loop循环执行
/claude-apiClaude API 开发辅助
/run启动并驱动应用验证变更（v2.1.145+）
/verify构建运行应用确认变更有效（v2.1.145+）
/run-skill-generator为项目生成 /run / /verify 启动配方

Bundled skills 是 prompt-based 的——给 Claude 详细指令而非硬编码逻辑。项目级同名 Skill 会覆盖 bundled 版本。

生态的"npm 时刻"

2026 年 4 月，Matt Pocock 把他个人的 .claude 目录推送到 GitHub（仓库名 mattpocock/skills），没有任何推广——没有博客、没有 YouTube 视频、没有 Hacker News 提交。24 小时内获得 22,000 stars，GitHub Trending 全球 #1。

社区将这一事件称为 Skills 生态的 "npm 时刻"。这个类比有部分准确：

准确的部分：

  • Skill 有标准单元（SKILL.md）
  • 有统一安装器（npx skills add、/plugin install）
  • 有 marketplace 注册表（claude-plugins-official、社区 marketplace）

不准确的部分：

  • 缺少语义化版本（semver）
  • 缺少依赖解析
  • 缺少规模化安全审查
  • 缺少 lockfile

这四样东西正是让 npm 成为真正的包管理器的核心——Skills 生态在标准化分发方面还有很长的路要走。

与其他 AI 编程工具的 Skill 体系对比

Skills 正在成为一个跨工具的标准。以下是截至 2026 年 6 月已确认支持 SKILL.md 格式的主要 AI 编程工具：

工具安装方式
Claude Code/plugin install、npx skills add、/skills 管理
Codex CLI (OpenAI)/plugins 搜索安装
Gemini CLI (Google)gemini extensions install <url>
Cursor/add-plugin、npx skills add -a cursor、.cursor/skills/ 手动
GitHub Copilot CLIcopilot plugin install
Windsurf内置 marketplace / npx skills add -a windsurf
OpenCodenpx skills add -a opencode
跨平台注册表skills.sh + npx skills find [query]

vercel-labs/skills CLI 还支持 Antigravity、Trae、Qwen Code、Kilo、Augment、Cline、CodeBuddy、Factory Droid 等 20+ Agent。安装时先写入 .agents/skills/ 中心目录，再 symlink/copy 到各 Agent 对应路径。

本章资料来源：Anthropic 官方文档、agentskills.io、Anthropic 内部 Skills 工程博客（2026-06-03）、Claude World 演化分析、Anthropic 官方 PDF《The Complete Guide to Building Skills for Claude》