Skills 系统：用户可扩展的能力框架

从定义开始

Skills 是 Claude Code 中一套基于提示词（Prompt-based）的可扩展能力框架。它允许用户通过简单的 Markdown 文件（SKILL.md）定义复杂的交互流程、多代理协作模式或特定领域的专家指令。

在 Claude Code 的世界观里，Skill 不同于 MCP（Model Context Protocol）工具。MCP 更多是外部 API 的桥接，而 Skill 是“复合型指令集”。一个 Skill 可以包含多个步骤、调用多个工具，甚至启动多个并行的子代理（Sub-agents）。它本质上是将一段经过验证的复杂工作流封装成一个 Slash Command（如 /simplify），让模型能够以确定性的方式执行高级任务。

运行时的真相

Skills 的实现核心位于 claude-code-opensource/src/skills/ 目录下，主要分为 加载机制、解析逻辑 和 内置实现 三部分：

加载机制 (loadSkillsDir.ts)： Claude Code 会从多个维度搜索并加载 Skills：
- 受管目录：~/.claude/skills（用户全局）。
- 项目目录：项目根目录下的 .claude/skills/。
- 动态发现：通过 discoverSkillDirsForPaths 随着文件读写动态加载工作空间深处的 Skill 定义。
- 遗留支持：同时也加载 commands/ 目录下的 .md 文件作为兼容项。
SKILL.md 格式与解析： Skill 以 SKILL.md 文件为核心，采用 YAML Frontmatter 定义元数据。解析逻辑在 parseSkillFrontmatterFields 中实现，支持以下关键字段：
- description：技能描述，用于让模型判断何时使用。
- allowed-tools：限制该技能可使用的工具集。
- user-invocable：是否允许用户在终端手动输入 / 命令触发。
- effort：执行该技能的预估复杂度（Low/Medium/High），影响资源分配。
- paths：条件触发模式。如果配置了 paths，该 Skill 只有在操作匹配的文件时才会被激活（见 activateConditionalSkillsForPaths）。
内置技能 (Bundled Skills)：在 src/skills/bundled/ 中，Claude Code 预置了一系列核心技能，如 simplify.ts、debug.ts、batch.ts。这些技能不再是单纯的文本，而是通过 registerBundledSkill 注册的硬编码逻辑。例如 simplify 技能会直接在提示词中指示模型使用 AgentTool 同时启动三个并行代理（Code Reuse, Quality, Efficiency）来审阅代码。

边界条件

安全隔离：MCP 加载的技能被标记为 untrusted。在 getPromptForCommand 实现中，来自 MCP 的技能严禁执行内联 Shell 命令（!...），而本地 Skills 则允许。
文件标识：系统通过 realpath 对技能文件进行去重（Deduplication），防止符号链接导致的重复加载。
条件激活：并非所有 Skills 都会一开始就塞给模型。带有 paths 属性的 Skills 是“按需激活”的，这有效节省了上下文窗口（Context Window）。

源码锚点

claude-code-opensource/src/skills/loadSkillsDir.ts: 核心加载逻辑。

📄 src/skills/loadSkillsDir.ts — 核心加载逻辑。L17-20 of 1087

typescript

  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
  logEvent,
} from '../services/analytics/index.js'
import { roughTokenCountEstimation } from '../services/tokenEstimation.js'

claude-code-opensource/src/skills/bundledSkills.ts: 内置技能注册框架。

📄 src/skills/bundledSkills.ts — 内置技能注册框架。L15-41 of 221

typescript

export type BundledSkillDefinition = {
  name: string
  description: string
  aliases?: string[]
  whenToUse?: string
  argumentHint?: string
  allowedTools?: string[]
  model?: string
  disableModelInvocation?: boolean
  userInvocable?: boolean
  isEnabled?: () => boolean
  hooks?: HooksSettings
  context?: 'inline' | 'fork'
  agent?: string
  /**
   * Additional reference files to extract to disk on first invocation.
   * Keys are relative paths (forward slashes, no `..`), values are content.
   * When set, the skill prompt is prefixed with a "Base directory for this
   * skill: <dir>" line so the model can Read/Grep these files on demand —
   * same contract as disk-based skills.
   */
  files?: Record<string, string>
  getPromptForCommand: (
    args: string,
    context: ToolUseContext,
  ) => Promise<ContentBlockParam[]>
}

claude-code-opensource/src/skills/bundled/: 内置技能的具体实现（simplify, debug 等）。

Skills 系统：用户可扩展的能力框架 ​

从定义开始 ​

运行时的真相 ​

边界条件 ​

推荐阅读路径 ​

源码锚点 ​

Skills 系统：用户可扩展的能力框架

从定义开始

运行时的真相

边界条件

推荐阅读路径

源码锚点