Claude Code Agent Skills 自动发现原理详解

概述

Agent Skills 的自动发现采用声明式、基于提示的发现系统，通过语言模型推理来判断何时使用哪个技能，而非传统的算法匹配或规则引擎。

核心特点

特性	说明
发现方式	纯 LLM 推理，无算法级匹配
加载策略	渐进式披露，按需加载
触发信号	`description` 字段为核心信号
上下文管理	三级架构优化 token 使用

技术架构

渐进式披露设计

技能系统采用三级加载机制，优化上下文窗口使用：

复制代码

┌─────────────────────────────────────────────────────────────┐
│  Level 1: 元数据层（启动时始终加载）                           │
│  ├── name: 技能名称                                          │
│  ├── description: 触发条件描述                                │
│  ├── when_to_use: 使用时机                                   │
│  └── Token 消耗: ~100 tokens/skill                          │
├─────────────────────────────────────────────────────────────┤
│  Level 2: 指令层（匹配时加载）                                 │
│  ├── SKILL.md 主要内容                                       │
│  ├── 用途说明                                                │
│  ├── 允许的工具                                              │
│  ├── 参数定义                                                │
│  └── Token 消耗: <5k tokens                                 │
├─────────────────────────────────────────────────────────────┤
│  Level 3: 资源层（按需加载）                                   │
│  ├── scripts/ 可执行脚本                                     │
│  ├── references/ 参考文档                                    │
│  ├── templates/ 模板文件                                     │
│  └── assets/ 资源文件                                        │
└─────────────────────────────────────────────────────────────┘

优势分析

复制代码

上下文优化     → 只加载必要的层级，避免浪费
性能提升       → 元数据层轻量，可快速扫描大量技能
灵活扩展       → 可包含大量参考文件而不影响主上下文
智能分发       → 按需加载，精确控制 token 消耗

发现机制

核心：纯 LLM 推理

关键点：Claude 使用纯语言模型推理来判断是否调用技能，没有任何算法级的匹配或规则引擎。

复制代码

用户请求："Extract text from report.pdf"

Claude 内部推理过程：
┌─────────────────────────────────────────────────────────────┐
│ Step 1: 意图分析                                             │
│   → 用户想要从 PDF 文件中提取文本                             │
│                                                             │
│ Step 2: 技能扫描                                             │
│   → 扫描已加载的所有技能元数据                                │
│                                                             │
│ Step 3: 语义匹配                                             │
│   发现技能 "pdf":                                           │
│   description: "Extract text from PDF documents. When     │
│   user wants to extract or process text from PDF files"    │
│                                                             │
│ Step 4: 推理决策                                             │
│   → 用户意图 "从 PDF 提取文本"                               │
│   → 技能描述 "Extract text from PDF documents"             │
│   → 匹配度：高                                               │
│                                                             │
│ Step 5: 执行调用                                             │
│   → 调用 Skill 工具，command="pdf"                          │
└─────────────────────────────────────────────────────────────┘

技能过滤标准

不是所有扫描到的技能都会参与匹配，必须满足以下条件：

javascript 复制代码

// 官方代码中的过滤逻辑
return allCommands.filter(cmd =>
  cmd.type === "prompt" &&              // ✅ 必须是 prompt 类型
  cmd.isSkill === true &&               // ✅ 必须标记为技能
  !cmd.disableModelInvocation &&        // ✅ 未禁用自动调用
  (cmd.source !== "builtin" ||
   cmd.isModeCommand === true) &&
  (cmd.hasUserSpecifiedDescription ||   // ✅ 必须有描述字段
   cmd.whenToUse)
);

文件系统扫描路径

bash 复制代码

# 全局技能目录（所有项目共享）
~/.claude/skills/
├── pdf-processing/
├── code-review/
└── contract-parser/

# 项目本地技能目录（当前项目专用）
.claude/skills/
├── project-memory/
└── custom-validator/

# 插件提供的技能
~/.claude/plugins/*/skills/

# 内置技能（Anthropic 预定义）
# 系统自动加载

元数据配置

YAML Frontmatter 结构

yaml 复制代码

---
# ===== 基础信息 =====
name: pdf-processing                    # 技能名称（必需）
                                       # - 最大 64 字符
                                       # - 只能包含小写字母、数字、连字符

version: 1.0.0                         # 版本号（可选）

author: your-team                      # 作者（可选）

license: MIT                           # 许可证（可选）

# ===== 发现相关 =====
description: |                         # 最关键的发现字段（必需）
  Extract text and structure from PDF documents.
  Use this skill when:
  - User wants to extract text from PDF files
  - User mentions "pdf", "parse pdf", "extract pdf"
  - Processing PDF forms or contracts
  - Converting PDF to other formats

when_to_use: |                         # 备用描述字段（可选）
  Extract text from PDF documents

# ===== 行为控制 =====
disable-model-invocation: false        # 禁用自动调用（可选）
                                       # true: 只能手动调用 /skill-name
                                       # false: 可自动发现并调用

mode: false                            # 模式命令（可选）
                                       # true: 成为持续激活的模式

# ===== 权限配置 =====
allowed-tools: |                       # 工具权限（可选）
  Read,Write,Bash(git:*),Bash(npm:*)

model: claude-opus-4-20250514          # 指定模型（可选）

# ===== 其他元数据 =====
tags: [pdf, document, extraction]      # 标签（可选）
---

# SKILL.md 内容开始...

`description` 字段的重要性

description 是技能发现的核心信号，应该包含：

yaml 复制代码

# ✅ 好的描述示例
description: |
  Set up and maintain a structured project memory system in
  docs/project_notes/ that tracks bugs with solutions, architectural
  decisions, key project facts, and work history.

  Use this skill when asked to:
  - "set up project memory"
  - "track our decisions"
  - "log a bug fix"
  - "update project memory"
  - "initialize memory system"

# ❌ 不好的描述示例
description: "Project memory skill"    # 太简短，缺少触发条件

技能命名规范

bash 复制代码

# ✅ 正确的命名
pdf-processor
code-reviewer
contract-parser

# ❌ 错误的命名
PDFProcessor           # 不能使用大写字母
pdf_processor          # 不能使用下划线
anthropic-tool         # 不能使用保留词
<xml>tag</xml>         # 不能包含 XML 标签

执行模式

两消息模式

技能执行时注入两条消息到对话上下文：

javascript 复制代码

// 消息 1：元数据消息（对用户可见）
{
  type: "user",
  content: `<command-message>The "pdf" skill is loading</command-message>`,
  isMeta: false  // 用户可见
}

// 消息 2：技能提示消息（对用户隐藏，发送给 API）
{
  type: "user",
  content: `
    You are a PDF processing specialist.

    ## Instructions
    1. Read the PDF file from the provided path
    2. Extract text content from each page
    3. Identify and extract form fields if present
    4. Output the results in the requested format

    ## Parameters
    - input_path: ${input_path}
    - output_format: ${output_format}
    - extract_forms: ${extract_forms}

    ## Allowed Tools
    - Read: For reading PDF files
    - Bash: For executing PDF processing scripts
  `,
  isMeta: true  // 用户隐藏，但发送给 API
}

执行上下文修改

技能可以临时修改执行环境：

修改类型	说明	示例
工具权限	临时批准特定工具使用	允许使用 Bash 执行脚本
模型切换	使用更强大的模型	从 Haiku 切换到 Opus
参数调整	修改 thinking tokens	增加 max_tokens

工作流程

完整执行流程图

复制代码

┌─────────────────────────────────────────────────────────────┐
│ Phase 1: 启动时发现和加载                                     │
│                                                             │
│  1.1 扫描所有技能目录                                        │
│      ├── ~/.claude/skills/                                  │
│      ├── .claude/skills/                                    │
│      └── ~/.claude/plugins/*/skills/                        │
│                                                             │
│  1.2 加载 Level 1 元数据                                     │
│      ├── name                                               │
│      └── description                                        │
│                                                             │
│  1.3 过滤符合标准的技能                                      │
│      └── 应用过滤条件（type, isSkill, description等）        │
│                                                             │
│  结果: 可用技能列表加载到系统提示中                           │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 2: 用户请求处理                                         │
│                                                             │
│  2.1 接收用户输入                                            │
│      "Extract text from report.pdf"                         │
│                                                             │
│  2.2 LLM 推理分析                                            │
│      ├── 分析用户意图                                        │
│      ├── 与技能描述进行语义匹配                               │
│      └── 计算匹配度                                          │
│                                                             │
│  2.3 决策                                                    │
│      ├── 匹配度 > 阈值 → 调用技能                            │
│      └── 匹配度 < 阈值 → 继续对话                             │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 3: 技能工具执行                                         │
│                                                             │
│  3.1 验证                                                    │
│      ├── 检查权限配置                                        │
│      └── 验证参数有效性                                      │
│                                                             │
│  3.2 加载 Level 2 指令                                       │
│      ├── 读取 SKILL.md 完整内容                              │
│      └── 解析指令和参数                                      │
│                                                             │
│  3.3 注入消息                                                │
│      ├── 元数据消息（用户可见）                               │
│      └── 技能提示消息（发送给 API）                           │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 4: API 请求                                            │
│                                                             │
│  4.1 构建增强上下文                                          │
│      ├── 原始对话历史                                        │
│      ├── 技能指令                                            │
│      └── 执行上下文修改                                      │
│                                                             │
│  4.2 发送 API 请求                                           │
│      ├── 使用指定的模型                                      │
│      ├── 应用工具权限                                        │
│      └── 设置参数限制                                        │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 5: 工具执行                                            │
│                                                             │
│  5.1 按技能指令执行                                          │
│      ├── 使用允许的工具                                      │
│      └── 按步骤完成任务                                      │
│                                                             │
│  5.2 返回结果                                                │
│      └── 将结果返回给用户                                    │
└─────────────────────────────────────────────────────────────┘

性能优化

Token 预算管理

javascript 复制代码

// 官方配置示例
{
  skillDescriptionLimit: 15000,  // 技能描述列表限制
  metadataTokens: ~100,           // 每个技能元数据
  instructionTokens: <5000,       // 技能指令内容
  maxTotalTokens: 200000          // 总 token 上限
}

懒加载策略

复制代码

启动时：仅加载元数据 (~100 tokens/skill)
         ↓
     匹配时：加载指令内容 (<5000 tokens)
         ↓
     执行时：按需加载脚本和参考文件

作用域隔离

复制代码

技能执行的影响范围：
├── 仅限当前会话
├── 不影响其他对话
└── 不修改全局配置

脚本执行优化

复制代码

传统方式（低效）：
脚本代码 → 上下文 → 高 token 消耗

Skills 方式（高效）：
脚本代码 → 执行环境 → 仅输出结果进上下文

最佳实践

编写有效的 `description`

yaml 复制代码

# ✅ 推荐：详细且包含触发条件
description: |
  Process PDF documents to extract text, forms, and structure.

  Use this skill when:
  - User wants to extract text from PDF files
  - User mentions "pdf", "parse pdf", "extract pdf", "pdf to text"
  - Processing PDF forms, contracts, or reports
  - Converting PDF content to JSON or Markdown

  Capabilities:
  - OCR text extraction
  - Form field detection and extraction
  - Table structure recognition
  - Multi-page document handling

# ❌ 避免：过于简短
description: "PDF processor"

合理使用禁用选项

yaml 复制代码

# 适合自动发现的技能
disable-model-invocation: false
# 示例：PDF 处理、代码审查等常用功能

# 适合手动调用的技能
disable-model-invocation: true
# 示例：敏感操作、破坏性操作、特定场景工具

技能组织建议

复制代码

~/.claude/skills/
├── general/                    # 通用技能
│   ├── pdf-processor/
│   ├── code-formatter/
│   └── document-generator/
├── project-specific/           # 项目特定技能
│   ├── api-tester/
│   └── db-migrator/
└── experimental/               # 实验性技能
    └── new-feature/

版本控制

bash 复制代码

# 将技能纳入版本控制
.claude/skills/
├── .gitkeep
├── custom-validator/
│   ├── SKILL.md
│   ├── README.md
│   └── scripts/
│       └── validate.js

# .gitignore
# 忽略敏感配置
.claude/skills/*/config.local.yaml

调试技巧

yaml 复制代码

# 在 SKILL.md 中添加调试指令
---
name: debug-example
description: "Debug skill"
---

## Debug Mode
当遇到问题时：
1. 检查技能是否正确加载
2. 验证 description 是否清晰
3. 确认 disable-model-invocation 设置
4. 查看日志文件 ~/.claude/audit.log

与其他功能的对比

特性	Skills	Slash Commands	Subagents	CLAUDE.md
发现方式	自动（LLM 推理）	手动（输入命令）	委托	自动加载
上下文隔离	❌	❌	✅ 独立上下文	❌
文件支持	✅ 多文件	❌ 单文件	❌	✅ 多文件
创建子代理	✅	✅	✅	❌
主要用途	专业可重复工作流	显式命令	研究密集型任务	项目规则

参考资源

一句话总结

Claude Code Agent Skills 的自动发现机制是一个精心设计的系统：

基于语义而非规则：使用 LLM 推理判断意图匹配，而非关键词匹配
渐进式加载：三级披露架构优化上下文使用
描述驱动 ：description 字段是发现的核心
透明且可控：用户可见加载状态，可禁用自动调用
高性能：懒加载策略和作用域隔离

这种设计使得系统能够智能地理解用户意图并选择合适的技能，同时保持高效的上下文管理和良好的用户体验。

Claude Code Agent Skills 自动发现原理详解

目录

概述

核心特点

技术架构

渐进式披露设计

优势分析

发现机制

核心：纯 LLM 推理

技能过滤标准

文件系统扫描路径

元数据配置

YAML Frontmatter 结构

description 字段的重要性

技能命名规范

执行模式

两消息模式

执行上下文修改

工作流程

完整执行流程图

性能优化

Token 预算管理

懒加载策略

作用域隔离

脚本执行优化

最佳实践

编写有效的 description

合理使用禁用选项

技能组织建议

版本控制

调试技巧

与其他功能的对比

参考资源

一句话总结

`description` 字段的重要性

编写有效的 `description`