ByteNoteByteNote
字

字节笔记本

2026年2月21日

Claude Agent Skills 第一性原理深度解析

#Claude Code
API中转
¥120
每日科技简报 · 每天一篇,快速了解科技圈大事

Claude Agent Skills 是一个基于提示词的元工具架构，它通过专门的指令注入来扩展 LLM 能力。与传统函数调用或代码执行不同，Skills 通过提示扩展和上下文修改来运作，在不编写可执行代码的情况下改变 Claude 处理后续请求的方式。

本文从第一性原理出发，解构 Claude Agent Skills 系统，剖析名为 "Skill" 的工具如何作为元工具将领域特定提示注入对话上下文。我们将以 skill-creator 和 internal-comms 为例，完整展示从文件解析到 API 请求结构再到 Claude 决策过程的整个生命周期。

Claude Agent Skills 概述

Claude 使用 Skills 来改进特定任务的执行方式。Skills 被定义为包含指令、脚本和资源的文件夹，Claude 可以在需要时加载它们。Claude 采用声明式、基于提示的系统进行技能发现和调用。AI 模型（Claude）根据系统提示中呈现的文本描述来决定是否调用 skills。

在代码层面不存在算法化的 skill 选择或 AI 驱动的意图检测。决策完全发生在 Claude 的推理过程中，基于提供的技能描述。

Skills 不是可执行代码。它们不运行 Python 或 JavaScript，背后也没有 HTTP 服务器或函数调用。它们也不是硬编码到 Claude 的系统提示中。Skills 存在于 API 请求结构的独立部分。

那么它们是什么？Skills 是专门的提示模板，将领域特定指令注入对话上下文。当调用 skill 时，它会修改对话上下文（通过注入指令提示）和执行上下文（通过更改工具权限和可能切换模型）。Skills 不直接执行操作，而是扩展为详细提示，让 Claude 准备好解决特定类型的问题。每个 skill 都作为 Claude 看到的工具模式中的动态添加项出现。

当用户发送请求时，Claude 会收到三样东西：用户消息、可用工具（Read、Write、Bash 等）和 Skill 工具。Skill 工具的描述包含每个可用 skill 的格式化列表，包括它们的 name、description 和其他字段。Claude 阅读此列表，使用其原生语言理解将您的意图与技能描述进行匹配。如果您说"帮我创建一个日志 skill"，Claude 会看到 internal-comms skill 的描述（"当用户想要使用公司喜欢的格式撰写内部通讯时"），识别匹配，然后调用 Skill 工具并执行 command: "internal-comms"。

术语说明：

  • Skill 工具（大写 S）= 管理所有 skills 的元工具。它出现在 Claude 的 tools 数组中，与 Read、Write、Bash 等并列。
  • skills（小写 s）= 单个 skill，如 pdf、skill-creator、internal-comms。这些是由 Skill 工具加载的专门指令模板。

技能选择机制在代码层面没有算法路由或意图分类。Claude Code 不使用嵌入、分类器或模式匹配来决定调用哪个 skill。相反，系统将所有可用 skills 格式化为嵌入在 Skill 工具提示中的文本描述，让 Claude 的语言模型做出决定。这是纯 LLM 推理。没有正则表达式、没有关键词匹配、没有基于 ML 的意图检测。决策发生在 Claude 前向传播通过 transformer 的过程中，而不是在应用代码中。

当 Claude 调用 skill 时，系统遵循简单的工作流程：加载 markdown 文件（SKILL.md），将其扩展为详细指令，将这些指令作为新用户消息注入对话上下文，修改执行上下文（允许的工具、模型选择），然后在这个丰富的环境中继续对话。这与传统工具有根本不同，传统工具执行并返回结果。Skills 让 Claude 准备好解决问题，而不是直接解决它。

构建 Agent Skills

现在让我们通过检查 Anthropic skill 仓库中的 skill-creator Skill 来深入了解如何构建 Skills。提醒一下，agent skills 是包含指令、脚本和资源的组织化文件夹，agents 可以动态发现和加载它们以在特定任务上表现更好。Skills 通过将您的专业知识打包成可组合的资源来扩展 Claude 的能力，将通用 agents 转变为满足您需求的专门 agents。

核心洞察：Skill = 提示模板 + 对话上下文注入 + 执行上下文修改 + 可选的数据文件和 Python 脚本

每个 Skill 都在名为 SKILL.md（不区分大小写）的 markdown 文件中定义，带有可选的捆绑文件，存储在 /scripts、/references 和 /assets 下。这些捆绑文件可以是 Python 脚本、shell 脚本、字体定义、模板等。以 skill-creator 为例，它包含 SKILL.md、LICENSE.txt 许可证，以及 /scripts 文件夹下的几个 Python 脚本。

Skills 从多个来源被发现和加载。Claude Code 扫描用户设置（~/.config/claude/skills/）、项目设置（.claude/skills/）、插件提供的 skills 和内置 skills 来构建可用 skills 列表。

注意：构建 Skills 最重要的概念是渐进式披露，展示刚好足够的信息帮助 agents 决定下一步做什么，然后在需要时揭示更多细节。对于 agent skills：

  • 披露 Frontmatter：最少（name、description、license）
  • 如果选择 skill，加载 SKILL.md：全面但聚焦
  • 然后在 skill 执行过程中加载辅助 assets、references 和 scripts

编写 SKILL.md

SKILL.md 是 skill 提示的核心。它是一个 markdown 文件，遵循两部分结构，frontmatter 和内容。Frontmatter 配置 skill 如何运行（权限、模型、元数据），而 markdown 内容告诉 Claude 做什么。

Frontmatter 是用 YAML 编写的 markdown 文件头部。

text
┌─────────────────────────────────────┐
│ 1. YAML Frontmatter (Metadata)      │ ← Configuration
│ ---                                 │
│ name: skill-name                    │
│ description: Brief overview         │
│ allowed-tools: "Bash, Read"         │
│ version: 1.0.0                      │
│ ---                                 │
├─────────────────────────────────────┤
│ 2. Markdown Content (Instructions)  │ ← Prompt for Claude
│                                     │
│ Purpose explanation                 │
│ Detailed instructions               │
│ Examples and guidelines             │
│ Step-by-step procedures             │
└─────────────────────────────────────┘

Frontmatter

Frontmatter 包含控制 Claude 如何发现和使用 skill 的元数据。以下是 skill-creator 的 frontmatter 示例：

yaml
---
name: skill-creator
description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
license: Complete terms in LICENSE.txt
---

name（必填）

Skill 的名称。Skill 的 name 在 Skill 工具中用作 command。

description（必填）

description 字段提供 skill 功能的简要摘要。这是 Claude 用来决定何时调用 skill 的主要信号。在上面的示例中，描述明确说明"当用户想要创建新 skill 时应使用此 skill"，这种清晰、面向行动的语言帮助 Claude 将用户意图与 skill 能力匹配。

系统会自动将源信息附加到描述（例如 "(plugin:skills)"），这有助于在加载多个 skills 时区分来自不同来源的 skills。

when_to_use（未记录—可能已弃用或未来功能）

⚠️ 重要提示：when_to_use 字段在代码库中广泛出现，但未在任何官方 Anthropic 文档中记录。此字段可能是：

  • 正在逐步淘汰的已弃用功能
  • 尚未正式支持的内部/实验性功能
  • 尚未发布的计划功能

建议：依赖详细的 description 字段。避免在生产 skills 中使用 when_to_use，直到它出现在官方文档中。

license（可选）

许可证说明。

allowed-tools（可选）

allowed-tools 字段定义 skill 可以在无需用户批准的情况下使用哪些工具，类似于 Claude 的 allowed-tools。

这是一个逗号分隔的字符串，解析为允许的工具名称数组。您可以使用通配符来限定权限范围，例如 Bash(git:*) 只允许 git 子命令，而 Bash(npm:*) 允许所有 npm 操作。skill-creator skill 使用 "Read,Write,Bash,Glob,Grep,Edit" 赋予其广泛的文件和搜索能力。

常见错误是列出每个可用工具，这会创建安全风险并破坏安全模型。只包含您的 skill 实际需要的内容，如果您只是读取和写入文件，"Read,Write" 就足够了。

yaml
# ✅ skill-creator 允许多个工具
allowed-tools: "Read,Write,Bash,Glob,Grep,Edit"

# ✅ 仅特定 git 命令
allowed-tools: "Bash(git status:*),Bash(git diff:*),Bash(git log:*),Read,Grep"

# ✅ 仅文件操作
allowed-tools: "Read,Write,Edit,Glob,Grep"

# ❌ 不必要的攻击面
allowed-tools: "Bash,Read,Write,Edit,Glob,Grep,WebSearch,Task,Agent"

model（可选）

model 字段定义 skill 可以使用的模型。默认继承用户会话中的当前模型。对于代码审查等复杂任务，skills 可以请求更强大的模型，如 Claude Opus。

yaml
model: "claude-opus-4-20250514"  # 使用特定模型
model: "inherit"                 # 使用会话的当前模型（默认）

version、disable-model-invocation 和 mode（可选）

Skills 支持三个可选的 frontmatter 字段用于版本控制和调用控制。version 字段（例如 version: "1.0.0"）是用于跟踪 skill 版本的元数据字段，从 frontmatter 解析但主要用于文档和 skill 管理目的。

disable-model-invocation 字段（布尔值）防止 Claude 通过 Skill 工具自动调用 skill。当设置为 true 时，skill 被排除在显示给 Claude 的列表之外，只能由用户通过 /skill-name 手动调用，这非常适合危险操作、配置命令或需要显式用户控制的交互式工作流。

mode 字段（布尔值）将 skill 归类为"模式命令"，修改 Claude 的行为或上下文。当设置为 true 时，skill 出现在 skills 列表顶部的特殊"模式命令"部分（与常规实用 skills 分开），使 debug-mode、expert-mode 或 review-mode 等 skills 突出显示，这些 skills 建立特定的操作上下文或工作流。

SKILL.md 提示内容

Frontmatter 之后是 markdown 内容，Claude 调用 skill 时接收的实际提示。这是您定义 skill 行为、指令和工作流的地方。编写有效 skill 提示的关键是保持聚焦并使用渐进式披露：在 SKILL.md 中提供核心指令，并引用外部文件获取详细内容。

推荐的内容结构：

markdown
---
# Frontmatter here
---

# [简要目的陈述 - 1-2 句话]

## Overview
[此 skill 做什么、何时使用、提供什么]

## Prerequisites
[必需的工具、文件或上下文]

## Instructions

### Step 1: [第一个行动]
[祈使指令]
[如需要示例]

### Step 2: [下一个行动]
[祈使指令]

### Step 3: [最终行动]
[祈使指令]

## Output Format
[如何构建结果]

## Error Handling
[失败时做什么]

## Examples
[具体使用示例]

## Resources
[引用 scripts/、references/、assets/（如果捆绑）]

例如，skill-creator skill 包含以下指令，指定创建工作流所需的每个步骤：

markdown
## Skill Creation Process

### Step 1: Understanding the Skill with Concrete Examples
### Step 2: Planning the Reusable Skill Contents
### Step 3: Initializing the Skill
### Step 4: Edit the Skill
### Step 5: Packaging a Skill

当 Claude 调用此 skill 时，它会接收整个提示作为新指令，并附加基础目录路径。{baseDir} 变量解析为 skill 的安装目录，允许 Claude 使用 Read 工具加载引用文件：Read({baseDir}/scripts/init_skill.py)。此模式保持主提示简洁，同时在需要时提供详细文档。

提示内容的最佳实践：

  • 保持在 5,000 字（约 800 行）以下，避免压倒上下文
  • 使用祈使语言（"分析代码以..."）而非第二人称（"你应该分析..."）
  • 引用外部文件获取详细内容，而非嵌入所有内容
  • 使用 {baseDir} 作为路径，永远不要硬编码绝对路径如 /home/user/project/

当调用 skill 时，Claude 只能访问 allowed-tools 中指定的工具，如果 frontmatter 中指定了模型，则模型可能会被覆盖。自动提供 skill 的基础目录路径，使捆绑资源可访问。

与 Skill 捆绑资源

当您将支持资源与 SKILL.md 一起捆绑时，Skills 变得更加强大。标准结构使用三个目录，每个目录服务特定目的：

text
my-skill/
├── SKILL.md              # 核心提示和指令
├── scripts/              # 可执行的 Python/Bash 脚本
├── references/           # 加载到上下文中的文档
└── assets/               # 模板和二进制文件

**为什么要捆绑资源？**保持 SKILL.md 简洁（5,000 字以下）可防止压倒 Claude 的上下文窗口。捆绑资源让您可以提供详细文档、自动化脚本和模板，而不会使主提示膨胀。Claude 仅在需要时使用渐进式披露加载它们。

scripts/ 目录

scripts/ 目录包含 Claude 通过 Bash 工具运行的可执行代码，自动化脚本、数据处理器、验证器或代码生成器，执行确定性操作。

例如，skill-creator 的 SKILL.md 这样引用脚本：

从头开始创建新 skill 时，始终运行 init_skill.py 脚本。该脚本方便地生成包含 skill 所需一切的模板 skill 目录，使 skill 创建过程更加高效可靠。

用法：scripts/init_skill.py <skill-name> --path <output-directory>

脚本功能：

  • 在指定路径创建 skill 目录
  • 生成具有适当 frontmatter 和 TODO 占位符的 SKILL.md 模板
  • 创建示例资源目录：scripts/、references/ 和 assets/
  • 在每个目录中添加可自定义或删除的示例文件

当 Claude 看到此指令时，它执行 python {baseDir}/scripts/init_skill.py。{baseDir} 变量自动解析为 skill 的安装路径，使 skill 可跨不同环境移植。

对复杂多步操作、数据转换、API 交互或任何需要精确逻辑的任务使用 scripts/，这些逻辑用代码比用自然语言更好地表达。

references/ 目录

references/ 目录存储 Claude 在引用时读取到上下文中的文档。这是文本内容，markdown 文件、JSON 模式、配置模板或 Claude 完成任务所需的任何文档。

例如，mcp-creator 的 SKILL.md 这样引用 references：

1.4 学习框架文档

加载并阅读以下引用文件：

  • MCP 最佳实践：📋 查看最佳实践 - 所有 MCP 服务器的核心指南
  • Python 实现：使用 WebFetch 加载 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • 🐍 Python 实现指南 - Python 特定的最佳实践和示例

当 Claude 遇到这些指令时，它使用 Read 工具：Read({baseDir}/references/mcp_best_practices.md)。内容被加载到 Claude 的上下文中，提供详细信息而不会使 SKILL.md 混乱。

对详细文档、大型模式库、清单、API 模式或任何对于 SKILL.md 太冗长但对任务必要的文本内容使用 references/。

assets/ 目录

assets/ 目录包含 Claude 通过路径引用但不加载到上下文中的模板和二进制文件。将此视为 skill 的静态资源，HTML 模板、CSS 文件、图像、配置样板或字体。

在 SKILL.md 中：

markdown
使用 {baseDir}/assets/report-template.html 的模板作为报告结构。
引用 {baseDir}/assets/diagram.png 的架构图。

Claude 看到文件路径但不读取内容。相反，它可能复制模板文件、引用图像路径，或将 CSS 包含在生成的输出中。assets/ 中的文件通过路径访问，而不是通过内容。

对 Claude 引用但不读取的模板、样式表、图像、字体、配置文件或任何二进制数据使用 assets/。

Skill 调用生命周期

当 Claude 决定调用 skill 时，系统遵循明确定义的生命周期，将静态 SKILL.md 文件转换为动态执行上下文。

第 1 步：解析和加载

系统首先定位并解析 skill 的 SKILL.md 文件。它从 frontmatter 中提取元数据（name、description、allowed-tools、model），并分离 markdown 内容作为提示模板。

第 2 步：上下文注入

解析的 markdown 内容作为新用户消息注入对话上下文。这与 Claude 看到的常规用户消息不同，它被标记为系统级指令，指导 Claude 后续如何处理请求。

第 3 步：执行上下文修改

系统根据 frontmatter 修改执行上下文：

  • 工具权限：将可用工具限制为 allowed-tools 中指定的工具
  • 模型选择：如果指定了 model，切换到该模型
  • 基础目录：设置 {baseDir} 变量指向 skill 的安装路径

第 4 步：继续对话

通过注入的指令和修改的执行上下文，Claude 继续对话。Skill 的指令现在有效地"覆盖"了 Claude 的默认行为，直到 skill 完成或用户明确退出。

工具与 Skills 对比

特性传统工具Skills
执行模型同步、直接提示扩展
目的执行特定操作指导复杂工作流
返回值即时结果对话上下文 + 执行上下文更改
示例Read、Write、Bashinternal-comms、skill-creator
并发性通常安全非并发安全
类型各种始终 "prompt"

结论

Claude Agent Skills 代表了一种强大的元工具架构，通过提示注入而非代码执行来扩展 AI 能力。通过理解 Skills 的第一性原理，作为提示模板、通过上下文注入运作、修改执行环境，您可以构建复杂的、可重用的工作流，将通用 AI 助手转变为针对您特定需求量身定制的专门专家。

关键要点：

  • Skills 是提示模板，不是可执行代码
  • 选择是LLM 推理，不是算法路由
  • 渐进式披露保持上下文高效
  • 捆绑资源（scripts、references、assets）实现复杂工作流
  • Frontmatter 控制执行，markdown 内容指导行为

通过掌握这些原则，您可以创建不仅扩展 Claude 能力而且与您的工作流和组织需求深度集成的 Skills。

Claude Code
上一篇

AIstudioProxyAPI：将 Google AI Studio 转换为 OpenAI 兼容 API

下一篇

Claude Agent Skills 第一性原理深度解析

分享: