# Claude Agent Skills: A First Principles Deep Dive # Claude 智能体技能：第一性原理深度解析 **Author:** Han Lee **Date:** Oct 26, 2025 **Read Time:** 41 min read Claude’s Agent `Skills` system represents a sophisticated prompt-based meta-tool architecture that extends LLM capabilities through specialized instruction injection. Unlike traditional function calling or code execution, `skills` operate through **prompt expansion** and **context modification** to modify how Claude processes subsequent requests without writing executable code. Claude 的智能体 `Skills`（技能）系统代表了一种复杂的、基于提示词（Prompt）的“元工具”架构，它通过注入专门的指令来扩展大语言模型（LLM）的能力。与传统的函数调用或代码执行不同，`skills` 通过**提示词扩展**和**语境修改**来运作，它不直接编写可执行代码，而是改变 Claude 处理后续请求的方式。 This deep dive deconstructs Claude’s Agent `Skills` system from first principles, documents the architecture where a tool named “`Skill`” acts as a meta-tool for injecting domain-specific prompts into the conversation context. We’ll walk through the complete lifecycle using the `skill-creator` and `internal-comms` skill as case studies, examining everything from file parsing to API request structure to Claude’s decision-making process. 本文将从第一性原理出发，深度拆解 Claude 的智能体 `Skills` 系统，记录其架构细节——即一个名为 “`Skill`” 的工具如何作为“元工具”（Meta-tool），将特定领域的提示词注入到对话语境中。我们将以 `skill-creator` 和 `internal-comms` 技能为例，完整梳理其生命周期，从文件解析、API 请求结构，一直剖析到 Claude 的决策过程。 --- ## Claude Agent Skills Overview ## Claude 智能体技能概览 Claude uses `Skills` to improve how it performs specific tasks. `Skills` are defined as folders that include instructions, scripts, and resources that Claude can load when needed. Claude uses a **declarative, prompt-based system** for skill discovery and invocation. The AI model (Claude) makes the decision to invoke `skills` based on textual descriptions presented in its system prompt. **There is no algorithmic `skill` selection or AI-powered intent detection** at the code level. The decision-making happens entirely within Claude’s reasoning process based on the skill descriptions provided. Claude 使用 `Skills` 来提升其执行特定任务的能力。`Skills` 被定义为包含指令、脚本和资源的文件夹，Claude 可在需要时加载它们。Claude 使用一套**声明式的、基于提示词的系统**来发现和调用技能。AI 模型（Claude）根据系统提示词中呈现的文本描述来决定是否调用 `skills`。在代码层面，**不存在算法式的 `skill` 选择或基于 AI 的意图检测模块**。所有的决策完全发生在 Claude 根据提供的技能描述进行推理的过程中。 `Skills` are not executable code. They do **NOT** run Python or JavaScript, and there’s no HTTP server or function calling happening behind the scenes. They are also not hardcoded into Claude’s system prompt. `Skills` live in a separate part of the API request structure. `Skills` 本身不是可执行代码。它们**不**运行 Python 或 JavaScript，后台也没有 HTTP 服务器或函数调用。它们也没有被硬编码进 Claude 的系统提示词中。`Skills` 存在于 API 请求结构的一个独立部分。 So what are they? `Skills` are specialized prompt templates that inject domain-specific instructions into the conversation context. When a skill is invoked, it modifies both the conversation context (by injecting instruction prompts) and the execution context (by changing tool permissions and potentially switching the model). Instead of executing actions directly, skills expand into detailed prompts that prepare Claude to solve a specific type of problem. Each skill appears as a dynamic addition to the tool schema that Claude sees. 那它们到底是什么？`Skills` 是专门的提示词模板，用于将特定领域的指令注入到对话语境中。当一个技能被调用时，它不仅会修改对话语境（通过注入指令提示词），还会修改执行语境（通过改变工具权限，甚至可能切换模型）。技能并不直接执行动作，而是展开成详细的提示词，让 Claude 做好解决特定类型问题的“准备”。每一个技能都像是动态添加到 Claude 可见工具列表中的新能力。 When users send a request, Claude receives three things: user message, the available tools (Read, Write, Bash, etc.), and the `Skill` tool. The `Skill` tool’s description contains a formatted list of every available skill with their `name`, `description`, and other fields combined. Claude reads this list and uses its native language understanding to match your intent against the skill descriptions. If you say “help me create a skill for logs,” Claude sees the `internal-comms` skill’s description (“When user wants to write internal communications using format that his company likes to use”), recognizes the match, and invokes the `Skill` tool with `command: "internal-comms"`. 当用户发送请求时，Claude 接收三样东西：用户消息、可用工具（Read, Write, Bash 等）以及 `Skill` 工具。`Skill` 工具的描述包含了一个格式化的列表，列出了所有可用技能及其 `name`（名称）、`description`（描述）和其他字段的组合。Claude 读取这个列表，利用其自然语言理解能力将你的意图与技能描述进行匹配。如果你说“帮我创建一个日志相关的技能”，Claude 看到 `internal-comms` 技能的描述（“当用户想要使用公司偏好的格式编写内部通信时”），识别出匹配项，并调用 `Skill` 工具，参数为 `command: "internal-comms"`。 > **Terminology Note / 术语说明**: > > * **`Skill` tool** (capital S) = The meta-tool that manages all skills. It appears in Claude’s `tools` array alongside Read, Write, Bash, etc. > **`Skill` 工具**（大写 S）= 管理所有技能的“元工具”。它出现在 Claude 的 `tools` 数组中，与 Read、Write、Bash 等并列。 > * **skills** (lowercase s) = Individual skills like `pdf`, `skill-creator`, `internal-comms`. These are the specialized instruction templates that the `Skill` tool loads. > **skills**（小写 s）= 个体技能，如 `pdf`、`skill-creator`、`internal-comms`。这些是 `Skill` 工具加载的专门指令模板。 Here’s a more visual representation on `skills` are used by Claude. 下图更直观地展示了 Claude 如何使用 `skills`： ![Claude Skill Flowchart](/assets/img/2025-10-26/01-claude-skill-1.png) The skill selection mechanism has no algorithmic routing or intent classification at the code level. Claude Code doesn’t use embeddings, classifiers, or pattern matching to decide which skill to invoke. Instead, the system formats all available skills into a text description embedded in the `Skill` tool’s prompt, and lets Claude’s language model make the decision. This is pure LLM reasoning. No regex, no keyword matching, no ML-based intent detection. The decision happens inside Claude’s forward pass through the transformer, not in the application code. 技能选择机制在代码层面没有任何算法路由或意图分类。Claude Code 不使用嵌入（Embeddings）、分类器或模式匹配来决定调用哪个技能。相反，系统将所有可用技能格式化为文本描述，嵌入到 `Skill` 工具的提示词中，让 Claude 的语言模型自己做决定。这是纯粹的大模型推理。没有正则表达式，没有关键词匹配，没有基于机器学习的意图检测。决策发生在 Claude 通过 Transformer 的前向传播过程中，而不是在应用程序代码里。 When Claude invokes a skill, the system follows a simple workflow: it loads a markdown file (`SKILL.md`), expands it into detailed instructions, injects those instructions as new user messages into the conversation context, modifies the execution context (allowed tools, model selection), and continues the conversation with this enriched environment. This is fundamentally different from traditional tools, which execute and return results. Skills *prepare Claude* to solve a problem, rather than solving it directly. 当 Claude 调用一个技能时，系统遵循一个简单的工作流：加载一个 Markdown 文件（`SKILL.md`），将其扩展为详细指令，将这些指令作为新的用户消息注入到对话语境中，修改执行语境（允许的工具、模型选择），然后在且在这个增强后的环境中继续对话。这与传统工具（执行并返回结果）有本质区别。技能是*让 Claude 做好准备*去解决问题，而不是直接解决问题。 The following is a table to help better disambiguating the difference between Tools and Skills and their capabilities: 下表有助于更好地区分传统工具（Tools）和技能（Skills）及其能力差异： | Aspect / 维度 | Traditional Tools / 传统工具 | Skills / 技能 | | :--- | :--- | :--- | | **Execution Model**
**执行模式** | Synchronous, direct
同步，直接执行 | Prompt expansion
提示词扩展 | | **Purpose**
**目的** | Perform specific operations
执行特定操作 | Guide complex workflows
引导复杂工作流 | | **Return Value**
**返回值** | Immediate results
即时结果 | Conversation context + execution context changes
对话语境 + 执行语境变更 | | **Example**
**示例** | `Read`, `Write`, `Bash` | `internal-comms`, `skill-creator` | | **Concurrency**
**并发性** | Generally safe
通常安全 | Not concurrency-safe
非并发安全 | | **Type**
**类型** | Various
多种多样 | Always `"prompt"`
始终是 `"prompt"` | --- ## Building Agent Skills ## 构建智能体技能 Now lets dive into how to build Skills by examining the [`skill-creator` Skill](https://github.com/anthropics/skills/tree/main/skill-creator) from Anthropic’s skill repository as a case study. As a reminder, agent `skills` are organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks. `Skills` extend Claude’s capabilities by packaging your expertise into composable resources for Claude, transforming general-purpose agents into specialized agents that fit your needs. 现在，让我们以 Anthropic 技能库中的 [`skill-creator` 技能](https://github.com/anthropics/skills/tree/main/skill-creator)为例，深入探讨如何构建技能。提醒一下，智能体 `skills` 是包含指令、脚本和资源的文件夹，智能体可以动态发现并加载它们，以便更好地执行特定任务。`Skills` 通过将你的专业知识打包成 Claude 可组合的资源，扩展了 Claude 的能力，将通用智能体转变为符合你需求的专用智能体。 > **Key Insight**: Skill = Prompt Template + Conversation Context Injection + Execution Context Modification + Optional data files and Python Scripts > > **核心洞察**：技能 = 提示词模板 + 对话语境注入 + 执行语境修改 + 可选数据文件和 Python 脚本 Every `Skill` is defined in a markdown file named `SKILL.md` (case-insensitive) with optional bundled files that’s stored under `/scripts`, `/references`, and `/assets`. These bundled files can be Python scripts, shell scripts, font definitions, templates, etc. Using `skill-creator` as an example, it contains `SILL.md`, `LICENSE.txt` for the license, and a few Python scripts under the `/scripts` folder. `skill-creator` does not have any `/references` or `/assets`. 每个 `Skill` 都定义在一个名为 `SKILL.md`（大小写不敏感）的 Markdown 文件中，并可以在 `/scripts`（脚本）、`/references`（参考资料）和 `/assets`（资产）目录下存放可选的捆绑文件。这些文件可以是 Python 脚本、Shell 脚本、字体定义、模板等。以 `skill-creator` 为例，它包含 `SKILL.md`、用于许可的 `LICENSE.txt`，以及 `/scripts` 文件夹下的几个 Python 脚本。`skill-creator` 没有 `/references` 或 `/assets`。 ![skill-creator package](/assets/img/2025-10-26/03-claude-skill-package.png) Skills are discovered and loaded from multiple sources. Claude Code scans user settings (`~/.config/claude/skills/`), project settings (`.claude/skills/`), plugin-provided skills, and built-in skills to build the available skills list. For Claude Desktop, we can upload a custom skill as follows. 技能可以从多个来源发现和加载。Claude Code 会扫描用户设置（`~/.config/claude/skills/`）、项目设置（`.claude/skills/`）、插件提供的技能以及内置技能，以构建可用技能列表。对于 Claude Desktop，我们可以按如下方式上传自定义技能。 ![Claude Desktop Skill](/assets/img/2025-10-26/02-claude-desktop-skill.png) > **NOTE:** The most important concept for building Skills is **Progressive Disclosure** - showing just enough information to help agents decide what to do next, then reveal more details as they need them. In the case of `agent skills`, it: > 1. Disclose Frontmatter: minimal (name, description, license) > 2. If a `skill` is chosen, load SKILL.md: comprehensive but focused > 3. And then load helper assets, references, and scripts as the `skill` is being executed > > **注意：** 构建技能最重要的概念是**渐进式披露（Progressive Disclosure）** —— 即只展示足够让智能体决定下一步做什么的信息，然后在需要时再展示更多细节。在 `agent skills` 的场景下，意味着： > 1. 披露 Frontmatter（前置元数据）：最小化信息（名称、描述、许可）。 > 2. 如果选中某个 `skill`，加载 `SKILL.md`：内容全面但重点突出。 > 3. 随着 `skill` 的执行，再加载辅助资产、参考资料和脚本。 ### Writing SKILL.md ### 编写 SKILL.md `SKILL.md` is the core of an skill’s prompt. It is a markdown file that follows a two-part structure - frontmatter and content. The frontmatter configures HOW the skill runs (permissions, model, metadata), while the markdown content tells Claude WHAT to do. [Frontmatter](https://docs.github.com/en/contributing/writing-for-github-docs/using-yaml-frontmatter) is the header of the markdown file written in YAML. `SKILL.md` 是技能提示词的核心。它是一个 Markdown 文件，遵循两部分结构——前置元数据（Frontmatter）和内容。Frontmatter 配置技能**如何**运行（权限、模型、元数据），而 Markdown 内容则告诉 Claude **做**什么。[Frontmatter](https://docs.github.com/en/contributing/writing-for-github-docs/using-yaml-frontmatter) 是用 YAML 编写的文件头。 ```plaintext ┌─────────────────────────────────────┐ │ 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 / 给 Claude 的提示词 │ │ │ Purpose explanation │ │ Detailed instructions │ │ Examples and guidelines │ │ Step-by-step procedures │ └─────────────────────────────────────┘ ``` #### Frontmatter / 前置元数据 The frontmatter contains metadata that controls how Claude discovers and uses the skill. As an example, here’s the frontmatter from `skill-creator`: Frontmatter 包含控制 Claude 如何发现和使用技能的元数据。以 `skill-creator` 为例： ```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 --- ``` Lets walk through the fields for the frontmatter one by one. 让我们逐一查看 Frontmatter 的各个字段。 ![Claude Skills Frontmatter](/assets/img/2025-10-26/04-claude-skill-frontmatter.png) ##### `name` (Required) / `name`（必填） Self explanatory. Name of the `skill`. The `name` of a `skill` is used as a `command` in `Skill Tool`. 顾名思义，即 `skill` 的名称。`skill` 的 `name` 会作为 `Skill Tool` 中的 `command`（命令）使用。 ##### `description` (Required) / `description`（必填） The `description` field provides a brief summary of what the skill does. This is the primary signal Claude uses to determine when to invoke a skill. In the example above, the description explicitly states “This skill should be used when users want to create a new skill” — this type of clear, action-oriented language helps Claude match user intent to skill capabilities. `description` 字段提供了技能功能的简要总结。这是 Claude 决定何时调用技能的主要信号。在上面的例子中，描述明确指出“当用户想要创建一个新技能时应使用此技能”——这种清晰的、面向行动的语言有助于 Claude 将用户意图与技能能力进行匹配。 The system automatically appends source information to the description (e.g., `"(plugin:skills)"`), which helps distinguish between skills from different sources when multiple skills are loaded. 系统会自动将来源信息附加到描述中（例如 `"(plugin:skills)"`），这有助于在加载多个技能时区分不同来源的技能。 ##### `when_to_use` (Undocumented—Likely Deprecated or Future Feature) ##### `when_to_use`（未记录文档——可能已弃用或为未来功能） > **⚠️ Important Note**: The `when_to_use` field appears extensively in the codebase but is **not documented in any official Anthropic documentation**. This field may be: > * A deprecated feature being phased out > * An internal/experimental feature not yet officially supported > * A planned feature that hasn’t been released > > **Recommendation**: Rely on a detailed `description` field instead. Avoid using `when_to_use` in production skills until it appears in official documentation. > > **⚠️ 重要提示**：`when_to_use` 字段在代码库中大量出现，但**并未在 Anthropic 的任何官方文档中记录**。此字段可能是： > * 正在逐步淘汰的已弃用功能 > * 尚未正式支持的内部/实验性功能 > * 尚未发布的计划功能 > > **建议**：请依赖详细的 `description` 字段。在官方文档提及之前，避免在生产环境的技能中使用 `when_to_use`。 Despite being undocumented, here’s how `when_to_use` currently works in the codebase: 尽管未记录，但以下是 `when_to_use` 目前在代码库中的工作方式： ```javascript function formatSkill(skill) { let description = skill.whenToUse ? `${skill.description} - ${skill.whenToUse}` : skill.description; return `"${skill.name}": ${description}`; } ``` When present, `when_to_use` gets appended to the description with a hyphen separator. For example: 如果存在，`when_to_use` 会用连字符分隔并附加到描述后面。例如： ```plaintext "skill-creator": Create well-structured, reusable skills... - When user wants to build a custom skill package with scripts, references, or assets ``` This combined string is what Claude sees in the Skill tool’s prompt. However, since this behavior is undocumented, it could change or be removed in future releases. The safer approach is to include usage guidance directly in the `description` field, as shown in the `skill-creator` example above. 这个组合字符串就是 Claude 在 Skill 工具提示词中看到的内容。然而，由于此行为未记录，它可能会在未来版本中更改或删除。更安全的方法是将使用指南直接包含在 `description` 字段中，如上面的 `skill-creator` 示例所示。 ##### `license` (Optional) / `license`（可选） Self explanatory. 顾名思义。 ##### `allowed-tools` (Optional) / `allowed-tools`（可选） The `allowed-tools` field defines which tools the skill can use without user approval, similar to Claude’s allowed-tools. `allowed-tools` 字段定义了该技能可以在无需用户批准的情况下使用的工具，类似于 Claude 的 allowed-tools 配置。 This is a comma-separated string that gets parsed into an array of allowed tool names. You can use wildcards to scope permissions, e.g., `Bash(git:*)` allows only git subcommands, while `Bash(npm:*)` permits all npm operations. The skill-creator skill uses `"Read,Write,Bash,Glob,Grep,Edit"` to give it broad file and search capabilities. A common mistake is listing every available tool, which creates a security risk and defeats the security model. 这是一个逗号分隔的字符串，会被解析为允许的工具名称数组。你可以使用通配符来限制权限范围，例如，`Bash(git:*)` 仅允许 git 子命令，而 `Bash(npm:*)` 允许所有 npm 操作。skill-creator 技能使用 `"Read,Write,Bash,Glob,Grep,Edit"` 来赋予其广泛的文件和搜索能力。一个常见的错误是列出所有可用工具，这会造成安全风险并破坏安全模型。 > Only include what your skill actually needs—if you’re just reading and writing files, `"Read,Write"` is sufficient. > 只包含你的技能实际需要的工具——如果你只是读写文件，`"Read,Write"` 就足够了。 ```yaml # ✅ skill-creator allows multiple tools / skill-creator 允许使用多个工具 allowed-tools: "Read,Write,Bash,Glob,Grep,Edit" # ✅ Specific git commands only / 仅限特定的 git 命令 allowed-tools: "Bash(git status:*),Bash(git diff:*),Bash(git log:*),Read,Grep" # ✅ File operations only / 仅限文件操作 allowed-tools: "Read,Write,Edit,Glob,Grep" # ❌ Unnecessary surface area / 不必要的攻击面 allowed-tools: "Bash,Read,Write,Edit,Glob,Grep,WebSearch,Task,Agent" # ❌ Unnecessary surface area with all npm commands / 开放所有 npm 命令，不必要的攻击面 allowed-tools: "Bash(npm:*),Read,Write" ``` ##### `model` (Optional) / `model`（可选） The `model` field defines which model the skill can use. It defaults to inheriting the current model in the user session. For complex tasks like code review, skills can request more capable models such as Claude Opus or other OSS Chinese models. IYKYK. `model` 字段定义了该技能可以使用的模型。默认情况下，它继承用户会话中的当前模型。对于像代码审查这样复杂的任务，技能可以请求更强大的模型，如 Claude Opus 或其他开源中文模型（懂的都懂）。 ```yaml model: "claude-opus-4-20250514" # Use specific model / 使用特定模型 model: "inherit" # Use session's current model (default) / 使用会话当前模型（默认） ``` ##### `version`, `disable-model-invocation`, and `mode` (Optional) ##### `version`、`disable-model-invocation` 和 `mode`（可选） Skills support three optional frontmatter fields for versioning and invocation control. The `version` field (e.g., version: "1.0.0") is a metadata field for tracking skill versions, parsed from the frontmatter but primarily used for documentation and skill management purposes. 技能支持三个可选的 Frontmatter 字段，用于版本控制和调用控制。`version` 字段（例如 version: "1.0.0"）是用于跟踪技能版本的元数据字段，虽然会被解析，但主要用于文档和技能管理目的。 The `disable-model-invocation` field (boolean) prevents Claude from automatically invoking the skill via the `Skill` tool. When set to true, the skill is excluded from the `` list shown to Claude and can only be invoked manually by users via `/skill-name`, making it ideal for dangerous operations, configuration commands, or interactive workflows that require explicit user control. `disable-model-invocation` 字段（布尔值）阻止 Claude 通过 `Skill` 工具自动调用该技能。当设置为 true 时，该技能将从展示给 Claude 的 `` 列表中排除，只能由用户通过 `/skill-name` 手动调用。这非常适合危险操作、配置命令或需要用户明确控制的交互式工作流。 The `mode` field (boolean) categorizes a skill as a “mode command” that modifies Claude’s behavior or context. When set to true, the skill appears in a special “Mode Commands” section at the top of the skills list (separate from regular utility skills), making it prominent for skills like debug-mode, expert-mode, or review-mode that establish specific operational contexts or workflows. `mode` 字段（布尔值）将技能分类为修改 Claude 行为或语境的“模式命令”。当设置为 true 时，该技能会出现在技能列表顶部的特殊“Mode Commands”部分（与常规实用技能分开），这使得像 debug-mode（调试模式）、expert-mode（专家模式）或 review-mode（审查模式）等确立特定操作语境或工作流的技能更加突出。 #### SKILL.md Prompt Content / SKILL.md 提示词内容 After the frontmatter comes the markdown content - the actual prompt that Claude receives when the `skill` is invoked. This is where you define the `skill`’s behavior, instructions, and workflows. The key to writing effective skill prompts is keeping them focused and using progressive disclosure: provide core instructions in SKILL.md, and reference external files for detailed content. Frontmatter 之后是 Markdown 内容——即 Claude 在调用 `skill` 时实际接收到的提示词。在这里，你可以定义 `skill` 的行为、指令和工作流。编写有效技能提示词的关键是保持聚焦并使用渐进式披露：在 `SKILL.md` 中提供核心指令，并引用外部文件以获取详细内容。 Here’s a recommended content structure: 以下是推荐的内容结构： ```markdown --- # Frontmatter here / Frontmatter 区域 --- # [Brief Purpose Statement - 1-2 sentences] / [简短目的陈述 - 1-2句话] ## Overview / 概览 [What this skill does, when to use it, what it provides] [此技能做什么，何时使用，提供什么] ## Prerequisites / 前置条件 [Required tools, files, or context] [需要的工具、文件或语境] ## Instructions / 指令 ### Step 1: [First Action] / [第一个动作] [Imperative instructions] / [命令式指令] [Examples if needed] / [如有需要提供示例] ### Step 2: [Next Action] / [下一个动作] [Imperative instructions] ### Step 3: [Final Action] / [最后动作] [Imperative instructions] ## Output Format / 输出格式 [How to structure results] [如何构建结果] ## Error Handling / 错误处理 [What to do when things fail] [失败时该怎么做] ## Examples / 示例 [Concrete usage examples] [具体使用示例] ## Resources / 资源 [Reference scripts/, references/, assets/ if bundled] [如有打包，引用 scripts/, references/, assets/] ``` As an example, `skill-creator` skill contains the following instructions that specifies each steps of the workflow required to create skills. 例如，`skill-creator` 技能包含以下指令，详细说明了创建技能所需工作流的每个步骤。 ```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 / 打包技能 ``` When Claude invokes this skill, it receives the entire prompt as new instructions with the base directory path prepended. The `{baseDir}` variable resolves to the skill’s installation directory, allowing Claude to load reference files using the Read tool: `Read({baseDir}/scripts/init_skill.py)`. This pattern keeps the main prompt concise while making detailed documentation available on demand. 当 Claude 调用此技能时，它会收到整个提示词作为新指令，并预置了基础目录路径。`{baseDir}` 变量会解析为技能的安装目录，允许 Claude 使用 Read 工具加载参考文件：`Read({baseDir}/scripts/init_skill.py)`。这种模式既保持了主提示词的简洁，又能在需要时提供详细文档。 **Best practices for prompt content:** **提示词内容的最佳实践：** * Keep under 5,000 words (~800 lines) to avoid overwhelming context. 保持在 5,000 字（约 800 行）以内，以免上下文过载。 * Use imperative language (“Analyze code for…”) not second person (“You should analyze…”). 使用命令式语言（“分析代码以……”），而非第二人称（“你应该分析……”）。 * Reference external files for detailed content rather than embedding everything. 引用外部文件获取详细内容，而不是把所有东西都嵌入进去。 * Use `{baseDir}` for paths, never hardcode absolute paths like `/home/user/project/`. 使用 `{baseDir}` 作为路径，切勿硬编码绝对路径如 `/home/user/project/`。 ```markdown ❌ Read /home/user/project/config.json ✅ Read {baseDir}/config.json ``` When the skill is invoked, Claude receives access only to the tools specified in `allowed-tools`, and the model may be overridden if specified in the frontmatter. The skill’s base directory path is automatically provided, making bundled resources accessible. 当技能被调用时，Claude 仅能访问 `allowed-tools` 中指定的工具，如果 Frontmatter 中有指定，模型也可能会被覆盖。技能的基础目录路径会自动提供，使得打包的资源可以被访问。 ### Bundling Resources with Your Skill ### 随技能打包资源 `Skills` become powerful when you bundle supporting resources alongside SKILL.md. The standard structure uses three directories, each serving a specific purpose: 当你在 `SKILL.md` 旁打包支持资源时，`Skills` 会变得非常强大。标准结构使用三个目录，每个目录都有特定用途： ```plaintext my-skill/ ├── SKILL.md # Core prompt and instructions / 核心提示词和指令 ├── scripts/ # Executable Python/Bash scripts / 可执行的 Python/Bash 脚本 ├── references/ # Documentation loaded into context / 加载到语境中的文档 └── assets/ # Templates and binary files / 模板和二进制文件 ``` **Why bundle resources?** Keeping SKILL.md concise (under 5,000 words) prevents overwhelming Claude’s context window. Bundled resources let you provide detailed documentation, automation scripts, and templates without bloating the main prompt. Claude loads them only when needed using progressive disclosure. **为什么要打包资源？** 保持 `SKILL.md` 简洁（低于 5,000 字）可以防止挤占 Claude 的上下文窗口。打包资源允许你提供详细的文档、自动化脚本和模板，而不会使主提示词臃肿。Claude 仅在需要时通过渐进式披露来加载它们。 #### The `scripts/` Directory / `scripts/` 目录 The `scripts/` directory contains executable code that Claude runs via the Bash tool—automation scripts, data processors, validators, or code generators that perform deterministic operations. `scripts/` 目录包含 Claude 通过 Bash 工具运行的可执行代码——自动化脚本、数据处理器、验证器或执行确定性操作的代码生成器。 As an example, `skill-creator`’s SKILL.md reference scripts like this: 例如，`skill-creator` 的 `SKILL.md` 像这样引用脚本： ```markdown When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable. Usage: ```scripts/init_skill.py --path ``` The script: - Creates the skill directory at the specified path - Generates a SKILL.md template with proper frontmatter and TODO placeholders - Creates example resource directories: scripts/, references/, and assets/ - Adds example files in each directory that can be customized or deleted ``` When Claude sees this instruction, it executes `python {baseDir}/scripts/init_skill.py`. The `{baseDir}` variable automatically resolves to the skill’s installation path, making the skill portable across different environments. 当 Claude 看到这条指令时，它会执行 `python {baseDir}/scripts/init_skill.py`。`{baseDir}` 变量自动解析为技能的安装路径，使得技能在不同环境中具有可移植性。 **Use scripts/ for** complex multi-step operations, data transformations, API interactions, or any task requiring precise logic better expressed in code than natural language. **何时使用 scripts/：** 复杂的多步操作、数据转换、API 交互，或任何比起自然语言更适合用代码表达的需要精确逻辑的任务。 #### The `references/` Directory / `references/` 目录 The `references/` directory stores documentation that Claude reads into its context when referenced. This is text content—markdown files, JSON schemas, configuration templates, or any documentation Claude needs to complete the task. `references/` 目录存储 Claude 在被引用时读取到其上下文中的文档。这是文本内容——Markdown 文件、JSON 模式、配置模板，或 Claude 完成任务所需的任何文档。 As an example, `mcp-creator`’s SKILL.md reference references like this: 例如，`mcp-creator` 的 `SKILL.md` 像这样引用参考资料： ```markdown #### 1.4 Study Framework Documentation **Load and read the following reference files:** - **MCP Best Practices**: [📋 View Best Practices](./reference/mcp_best_practices.md) - Core guidelines for all MCP servers **For Python implementations, also load:** - **Python SDK Documentation**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md` - [🐍 Python Implementation Guide](./reference/python_mcp_server.md) - Python-specific best practices and examples **For Node/TypeScript implementations, also load:** - **TypeScript SDK Documentation**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md` - [⚡ TypeScript Implementation Guide](./reference/node_mcp_server.md) - Node/TypeScript-specific best practices and examples ``` When Claude encounters these instructions, it uses the Read tool: `Read({baseDir}/references/mcp_best_practices.md)`. The content gets loaded into Claude’s context, providing detailed information without cluttering SKILL.md. 当 Claude 遇到这些指令时，它会使用 Read 工具：`Read({baseDir}/references/mcp_best_practices.md)`。内容被加载到 Claude 的上下文中，提供了详细信息而不弄乱 `SKILL.md`。 **Use references/ for** detailed documentation, large pattern libraries, checklists, API schemas, or any text content that’s too verbose for SKILL.md but necessary for the task. **何时使用 references/：** 详细文档、大型模式库、检查清单、API 模式，或任何对 `SKILL.md` 来说过于冗长但对任务必要的文本内容。 #### The `assets/` Directory / `assets/` 目录 The `assets/` directory contains templates and binary files that Claude references by path but doesn’t load into context. Think of this as the skill’s static resources - HTML templates, CSS files, images, configuration boilerplate, or fonts. `assets/` 目录包含 Claude 通过路径引用但不加载到上下文中的模板和二进制文件。可以将其视为技能的静态资源——HTML 模板、CSS 文件、图片、配置样板或字体。 In SKILL.md: 在 `SKILL.md` 中： ```markdown Use the template at {baseDir}/assets/report-template.html as the report structure. Reference the architecture diagram at {baseDir}/assets/diagram.png. ``` Claude sees the file path but doesn’t read the content. Instead, it might copy the template to a new location, fill in placeholders, or reference the path in generated output. Claude 看到文件路径但不会读取内容。相反，它可能会将模板复制到新位置，填充占位符，或在生成的输出中引用该路径。 **Use assets/ for** HTML/CSS templates, images, binary files, configuration templates, or any file that Claude manipulates by path rather than reads into context. **何时使用 assets/：** HTML/CSS 模板、图片、二进制文件、配置模板，或任何 Claude 通过路径操作而不是读入上下文的文件。 The key distinction between `references/` and `assets/` are that: `references/` 和 `assets/` 之间的关键区别在于： * **references/**: Text content loaded into Claude’s context via Read tool **references/**：通过 Read 工具加载到 Claude 上下文中的文本内容。 * **assets/**: Files referenced by path only, not loaded into context **assets/**：仅通过路径引用，不加载到上下文中的文件。 This distinction matters for context management. A 10KB markdown file in `references/` consumes context tokens when loaded. A 10KB HTML template in `assets/` does not. Claude just knows the path exists. 这种区别对上下文管理至关重要。`references/` 中的 10KB Markdown 文件在加载时会消耗上下文 Token。`assets/` 中的 10KB HTML 模板则不会。Claude 只是知道路径存在。 > **Best practice:** Always use `{baseDir}` for paths, never hardcode absolute paths. This makes skills portable across user environments, project directories, and different installations. > **最佳实践：** 始终使用 `{baseDir}` 作为路径，切勿硬编码绝对路径。这使得技能在用户环境、项目目录和不同安装之间具有可移植性。 ### Common Skill Patterns ### 通用技能模式 As with everything engineering, understanding common patterns helps in design effective skills. Here are the most useful patterns for tool integration and workflow design. 正如工程领域的其他事物一样，理解通用模式有助于设计有效的技能。以下是工具集成和工作流设计中最有用的模式。 #### Pattern 1: Script Automation #### 模式 1：脚本自动化 **Use case:** Complex operations requiring multiple commands or deterministic logic. **用例：** 需要多个命令或确定性逻辑的复杂操作。 This pattern offloads computational tasks to Python or Bash scripts in the `scripts/` directory. The skill prompt tells Claude to execute the script and process its output. 此模式将计算任务卸载到 `scripts/` 目录中的 Python 或 Bash 脚本。技能提示词告诉 Claude 执行脚本并处理其输出。 ![Claude Skill Script Automation](/assets/img/2025-10-26/09-script-automation.png) **SKILL.md example:** ```markdown Run scripts/analyzer.py on the target directory: `python {baseDir}/scripts/analyzer.py --path "$USER_PATH" --output report.json` Parse the generated `report.json` and present findings. ``` **Required tools:** ```yaml allowed-tools: "Bash(python {baseDir}/scripts/*:*), Read, Write" ``` #### Pattern 2: Read - Process - Write #### 模式 2：读取 - 处理 - 写入 **Use case:** File transformation and data processing. **用例：** 文件转换和数据处理。 The simplest pattern — read input, transform it following instructions, write output. Useful for format conversions, data cleanup, or report generation. 最简单的模式——读取输入，按照指令转换，写入输出。用于格式转换、数据清理或报告生成。 ![Claude Skill Read Process Write](/assets/img/2025-10-26/10-read-process-write.png) **SKILL.md example:** ```markdown ## Processing Workflow 1. Read input file using Read tool 2. Parse content according to format 3. Transform data following specifications 4. Write output using Write tool 5. Report completion with summary ``` **Required tools:** ```yaml allowed-tools: "Read, Write" ``` #### Pattern 3: Search - Analyze - Report #### 模式 3：搜索 - 分析 - 报告 **Use case:** Codebase analysis and pattern detection. **用例：** 代码库分析和模式检测。 Search the codebase for patterns using Grep, read matching files for context, analyze findings, and generate a structured report. Or, search enterprise data store for data, analyze the retrieved data for information, and generate a structured report. 使用 Grep 在代码库中搜索模式，读取匹配的文件以获取上下文，分析发现，并生成结构化报告。或者，在企业数据存储中搜索数据，分析检索到的数据以获取信息，并生成结构化报告。 ![Claude Skill Search Analyze Report](/assets/img/2025-10-26/06-search-analyze-report.png) **SKILL.md example:** ```markdown ## Analysis Process 1. Use Grep to find relevant code patterns 2. Read each matched file 3. Analyze for vulnerabilities 4. Generate structured report ``` **Required tools:** ```yaml allowed-tools: "Grep, Read" ``` #### Pattern 4: Command Chain Execution #### 模式 4：命令链执行 **Use case:** Multi-step operations with dependencies. **用例：** 具有依赖关系的多步操作。 Execute a sequence of commands where each step depends on the previous one’s success. Common for CI/CD-like workflows. 执行一系列命令，其中每个步骤都依赖于上一步的成功。常见于类似 CI/CD 的工作流。 ![Claude Skill Command Chain Execution](/assets/img/2025-10-26/05-command-chain-execution.png) **SKILL.md example:** ```markdown Execute analysis pipeline: npm install && npm run lint && npm test Report results from each stage. ``` **Required tools:** ```yaml allowed-tools: "Bash(npm install:*), Bash(npm run:*), Read" ``` ### Advanced Patterns ### 高级模式 #### Wizard-Style Multi-Step Workflows #### 向导式多步工作流 **Use case:** Complex processes requiring user input at each step. **用例：** 每一步都需要用户输入的复杂流程。 Break complex tasks into discrete steps with explicit user confirmation between each phase. Useful for setup wizards, configuration tools, or guided processes. 将复杂任务分解为离散步骤，并在每个阶段之间进行明确的用户确认。用于设置向导、配置工具或引导式流程。 **SKILL.md example:** ```markdown ## Workflow ### Step 1: Initial Setup 1. Ask user for project type 2. Validate prerequisites exist 3. Create base configuration Wait for user confirmation before proceeding. ### Step 2: Configuration 1. Present configuration options 2. Ask user to choose settings 3. Generate config file Wait for user confirmation before proceeding. ### Step 3: Initialization 1. Run initialization scripts 2. Verify setup successful 3. Report results ``` #### Template-Based Generation #### 基于模板的生成 **Use case:** Creating structured outputs from templates stored in `assets/`. **用例：** 根据存储在 `assets/` 中的模板创建结构化输出。 Load templates, fill placeholders with user-provided or generated data, and write the result. Common for report generation, boilerplate code creation, or documentation. 加载模板，用用户提供或生成的数据填充占位符，并写入结果。常见于报告生成、样板代码创建或文档编写。 **SKILL.md example:** ```markdown ## Generation Process 1. Read template from {baseDir}/assets/template.html 2. Parse user requirements 3. Fill template placeholders: - {{projectName}} → user-provided name - {{summary}} → generated summary - {{date}} → current date 4. Write filled template to output file 5. Report completion ``` #### Iterative Refinement #### 迭代式优化 **Use case:** Processes requiring multiple passes with increasing depth. **用例：** 需要多次扫描且深度递增的流程。 Perform broad analysis first, then progressively deeper dives on identified issues. Useful for code review, security audits, or quality analysis. 首先进行广泛分析，然后对识别出的问题进行逐步深入的研究。用于代码审查、安全审计或质量分析。 **SKILL.md example:** ```markdown ## Iterative Analysis ### Pass 1: Broad Scan 1. Search entire codebase for patterns 2. Identify high-level issues 3. Categorize findings ### Pass 2: Deep Analysis For each high-level issue: 1. Read full file context 2. Analyze root cause 3. Determine severity ### Pass 3: Recommendation For each finding: 1. Research best practices 2. Generate specific fix 3. Estimate effort Present final report with all findings and recommendations. ``` #### Context Aggregation #### 上下文聚合 **Use case:** Combining information from multiple sources to build comprehensive understanding. **用例：** 结合多源信息以构建全面理解。 Gather data from different files and tools, synthesize into a coherent picture. Useful for project summaries, dependency analysis, or impact assessments. 从不同文件和工具收集数据，综合成连贯的图景。用于项目总结、依赖分析或影响评估。 **SKILL.md example:** ```markdown ## Context Gathering 1. Read project README.md for overview 2. Analyze package.json for dependencies 3. Grep codebase for specific patterns 4. Check git history for recent changes 5. Synthesize findings into coherent summary ``` --- ## Agent Skills Internal Architecture ## 智能体技能内部架构 With the overview and building process covered, we can now examine how skills actually work under the hood. The skills system operates through a meta-tool architecture where a tool named `Skill` acts as a container and dispatcher for all individual skills. This design fundamentally distinguishes skills from traditional tools in both implementation and purpose. 在介绍了概览和构建过程后，我们现在来看看技能在底层是如何实际运作的。技能系统通过一个“元工具”架构运作，其中一个名为 `Skill` 的工具充当所有个体技能的容器和调度器。这种设计在实现和目的上都将技能与传统工具从根本上区分开来。 > The `Skill` tool is a meta-tool that manages all skills > `Skill` 工具是管理所有技能的元工具。 ### Skills Object Design ### 技能对象设计 Traditional tools like `Read`, `Bash`, or `Write` execute discrete actions and return immediate results. Skills operate differently. Rather than performing actions directly, they inject specialized instructions into the conversation history and dynamically modify Claude’s execution environment. This happens through two user messages—one containing metadata visible to users, another containing the full skill prompt hidden from the UI but sent to Claude - and by altering the agent’s context to change permissions, switch models, and adjust thinking token parameters for the duration of the skill’s use. 传统工具如 `Read`、`Bash` 或 `Write` 执行离散动作并返回即时结果。技能则不同。它们不直接执行动作，而是将专门指令注入到对话历史中，并动态修改 Claude 的执行环境。这是通过两条用户消息完成的——一条包含对用户可见的元数据，另一条包含从 UI 隐藏但发送给 Claude 的完整技能提示词——并通过改变智能体的语境来更改权限、切换模型，以及调整技能使用期间的思维 Token 参数。 ![Claude Skill Execution Flow](/assets/img/2025-10-26/08-claude-skill-execution-flow.png) | Feature / 特性 | Normal Tool / 普通工具 | Skill Tool / 技能工具 | | :--- | :--- | :--- | | **Essence**
**本质** | Direct action executor
直接动作执行器 | Prompt injection + context modifier
提示词注入 + 语境修改器 | | **Message Role**
**消息角色** | assistant → tool_use
user → tool_result | assistant → tool_use Skill
user → tool_result
user → skill prompt ← INJECTED!（注入！） | | **Complexity**
**复杂度** | Simple (3-4 messages)
简单（3-4 条消息） | Complex (5-10+ messages)
复杂（5-10+ 条消息） | | **Context**
**语境** | Static
静态 | Dynamic (modified per turn)
动态（每轮修改） | | **Persistence**
**持久性** | Tool interactions only
仅工具交互 | Tool interactions + skill prompts
工具交互 + 技能提示词 | | **Token Overhead**
**Token 开销** | Minimal (~100 tokens)
极小（~100 tokens） | Significant (~1,500+ tokens per turn)
显著（每轮 ~1,500+ tokens） | | **Use Case**
**用例** | Simple, direct tasks
简单直接的任务 | Complex, guided workflows
复杂引导式工作流 | The complexity is substantial. Normal tools generate simple message exchanges—an assistant tool call followed by a user result. Skills inject multiple messages, operate within a dynamically modified context, and carry significant token overhead to provide the specialized instructions that guide Claude’s behavior. 复杂性是巨大的。普通工具生成简单的消息交换——助手的工具调用后跟用户的返回结果。技能注入多条消息，在动态修改的语境中运行，并带有显著的 Token 开销，以提供引导 Claude 行为的专门指令。 Understanding how the `Skill` meta-tool works reveals the mechanics of this system. Let’s examine its structure: 理解 `Skill` 元工具的工作原理揭示了该系统的机制。让我们看看它的结构： ```javascript Pd = { name: "Skill", // The tool name constant: $N = "Skill" inputSchema: { command: string // E.g., "pdf", "skill-creator" }, outputSchema: { success: boolean, commandName: string }, // 🔑 KEY FIELD: This generates the skills list // 🔑 关键字段：这生成了技能列表 prompt: async () => fN2(), // Validation and execution / 验证和执行 validateInput: async (input, context) => { /* 5 error codes */ }, checkPermissions: async (input, context) => { /* allow/deny/ask */ }, call: async *(input, context) => { /* yields messages + context modifier */ } } ``` The `prompt` field distinguishes the Skill tool from other tools like `Read` or `Bash`, which have static descriptions. Instead of a fixed string, the Skill tool uses a dynamic prompt generator that constructs its description at runtime by aggregating the names and descriptions of all available skills. This implements **progressive disclosure** — the system loads only the minimal metadata (skill names and descriptions from frontmatter) into Claude’s initial context, providing just enough information for the model to decide which skill matches the user’s intent. The full skill prompt loads only after Claude makes that selection, preventing context bloat while maintaining discoverability. `prompt` 字段将 Skill 工具与 `Read` 或 `Bash` 等其他工具区分开来，后者的描述是静态的。Skill 工具不使用固定字符串，而是使用动态提示词生成器，通过聚合所有可用技能的名称和描述，在运行时构建其描述。这实现了**渐进式披露**——系统仅将最小化的元数据（来自 Frontmatter 的技能名称和描述）加载到 Claude 的初始语境中，提供足够的信息让模型决定哪个技能匹配用户意图。完整的技能提示词仅在 Claude 做出选择后才加载，既防止了上下文臃肿，又保持了可发现性。 ```javascript async function fN2() { let A = await atA(), { modeCommands: B, limitedRegularCommands: Q } = vN2(A), G = [...B, ...Q].map((W) => W.userFacingName()).join(", "); l(`Skills and commands included in Skill tool: ${G}`); let Z = A.length - B.length, Y = nS6(B), J = aS6(Q, Z); return `Execute a skill within the main conversation When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge. How to use skills: - Invoke skills using this tool with the skill name only (no arguments) - When you invoke a skill, you will see The "{name}" skill is loading - The skill's prompt will expand and provide detailed instructions on how to complete the task - Examples: - \`command: "pdf"\` - invoke the pdf skill - \`command: "xlsx"\` - invoke the xlsx skill - \`command: "ms-office-suite:pdf"\` - invoke using fully qualified name Important: - Only use skills listed in below - Do not invoke a skill that is already running - Do not use this tool for built-in CLI commands (like /help, /clear, etc.) ${Y}${J} `; } ``` Unlike how some tools lives in the system prompts for certain assistants such as ChatGPT, Claude **agent skills do not live in the system prompt**. They live in the `tools` array as part of the `Skill` tool’s description. Names of the individual skills is represented as part of the `Skill` meta-tool’s input schema’s `command` field. To better visualize how it looks, here’s the actual API request structure: 与某些助手（如 ChatGPT）将部分工具放在系统提示词中不同，Claude **智能体技能并不存在于系统提示词中**。它们作为 `Skill` 工具描述的一部分，存在于 `tools` 数组中。个体技能的名称表现为 `Skill` 元工具输入模式（Schema）的 `command` 字段的一部分。为了更直观地展示，以下是实际的 API 请求结构： ```json { "model": "claude-sonnet-4-5-20250929", "system": "You are Claude Code, Anthropic's official CLI...", // ← System prompt / 系统提示词 "messages": [ {"role": "user", "content": "Help me create a new skill"}, // ... conversation history / ... 对话历史 ], "tools": [ // ← Tools array sent to Claude / 发送给 Claude 的 Tools 数组 { "name": "Skill", // ← The meta-tool / 元工具 "description": "Execute a skill...\n\n...\n\n\n...", "input_schema": { "type": "object", "properties": { "command": { "type": "string", "description": "The skill name (no arguments)" // ← Name of individual skill / 个体技能名称 } } } }, { "name": "Bash", "description": "Execute bash commands...", // ... }, { "name": "Read", // ... } // ... other tools / ... 其他工具 ] } ``` The `` section lives within the Skill tool’s description and gets regenerated for each API request. The system dynamically builds this list by aggregating currently loaded skills from user and project configurations, plugin-provided skills, and any built-in skills, subject to a token budget limit of 15,000 characters by default. This budget constraint forces skill authors to write concise descriptions and ensures the tool description doesn’t overwhelm the model’s context window. `` 部分存在于 Skill 工具的描述中，并为每个 API 请求重新生成。系统通过聚合当前加载的技能（来自用户和项目配置、插件提供的技能以及内置技能）动态构建此列表，默认受限于 15,000 个字符的 Token 预算。这一预算限制迫使技能作者编写简洁的描述，并确保工具描述不会挤占模型的上下文窗口。 ### Skill Conversation and Execution Context Injection Design ### 技能对话与执行语境注入设计 Most LLM APIs supports `role: "system"` messages that could theoretically carry system prompts. In fact, OpenAI’s ChatGPT carries its default tools in its system prompts, including `bio` for memory, `automations` for task scheduling, `canmore` for controlling canvas, `img_gen` for image generation, `file_search`, `python`, and `web` for Internet search. And at the end, the tools prompt takes up around 90% of the token counts in its system prompt. This could be useful but hardly efficient if we have lots of tools and/or skills to be loaded into the context. 大多数 LLM API 支持 `role: "system"` 消息，理论上可以承载系统提示词。事实上，OpenAI 的 ChatGPT 将其默认工具放在系统提示词中，包括用于记忆的 `bio`、用于任务调度的 `automations`、用于控制 Canvas 的 `canmore`、`img_gen`（图像生成）、`file_search`、`python` 以及用于联网搜索的 `web`。最终，工具提示词占据了其系统提示词约 90% 的 Token 计数。如果我们需要加载大量工具和/或技能到上下文中，这种做法虽然有用但效率极低。 However, system messages have different semantics that make them unsuitable for skills. System messages set global context that persists across the entire conversation, affecting all subsequent turns with higher authority than user instructions. 然而，系统消息具有不同的语义，使其不适合技能。系统消息设定了贯穿整个对话的全局语境，影响所有后续轮次，且权限高于用户指令。 Skills need temporary, scoped behavior. The `skill-creator` skill should only affect skill creating related tasks, not transform Claude into a permanent PDF specialist for the rest of the session. Using `role: "user"` with `isMeta: true` makes the skill prompt appear as user input to Claude, keeping it temporary and localized to the current interaction. After the skill completes, the conversation returns to normal conversation context and execution context without residual behavioral modifications. 技能需要临时的、有作用域的行为。`skill-creator` 技能应仅影响技能创建相关的任务，而不是将会话剩余时间的 Claude 永久转变为 PDF 专家。使用 `role: "user"` 配合 `isMeta: true` 使技能提示词对 Claude 表现为用户输入，保持其临时性并局限于当前交互。技能完成后，对话返回正常的对话语境和执行语境，没有残留的行为修改。 Normal tools like `Read`, `Write`, or `Bash` have simple communication patterns. When Claude invokes `Read`, it sends a file path, receives the file contents, and continues working. The user sees “Claude used the Read tool” in their transcript, and that’s sufficient transparency. The tool did one thing, returned a result, and that’s the end of the interaction. Skills operate fundamentally differently. Instead of executing discrete actions and returning results, skills inject comprehensive instruction sets that modify how Claude reasons about and approaches the task. This creates a design challenge that normal tools never face: users need transparency about which skills are running and what they’re doing, while Claude needs detailed, potentially verbose instructions to execute the skill correctly. If users see the full skill prompts in their chat transcript, the UI becomes cluttered with thousands of words of internal AI instructions. If the skill activation is completely hidden, users lose visibility into what the system is doing on their behalf. The solution requires separating these two communication channels into distinct messages with different visibility rules. 普通工具如 `Read`、`Write` 或 `Bash` 具有简单的通信模式。当 Claude 调用 `Read` 时，它发送文件路径，接收文件内容，然后继续工作。用户在记录中看到“Claude 使用了 Read 工具”，这就有足够的透明度。工具做了一件事，返回一个结果，交互就结束了。技能的运作方式根本不同。技能不执行离散动作并返回结果，而是注入全面的指令集，修改 Claude 推理和处理任务的方式。这创造了一个普通工具从未面临的设计挑战：用户需要了解哪些技能正在运行以及它们在做什么的透明度，而 Claude 需要详细、可能很冗长的指令来正确执行技能。如果用户在聊天记录中看到完整的技能提示词，UI 就会被成千上万字的内部 AI 指令填满。如果技能激活完全隐藏，用户就失去了系统代表他们做了什么的可见性。解决方案需要将这两个通信渠道分离为具有不同可见性规则的独特消息。 The skills system uses an `isMeta` flag on each message to control whether it appears in the user interface. When `isMeta: false` (or when the flag is omitted and defaults to false), the message renders in the conversation transcript that users see. When `isMeta: true`, the message gets sent to the Anthropic API as part of Claude’s conversation context but never appears in the UI. This simple boolean flag enables sophisticated dual-channel communication: one stream for human users, another for the AI model. Meta-prompting for meta-tools! 技能系统在每条消息上使用 `isMeta` 标志来控制其是否出现在用户界面中。当 `isMeta: false`（或省略标志默认为 false）时，消息渲染在用户看到的对话记录中。当 `isMeta: true` 时，消息作为 Claude 对话语境的一部分发送到 Anthropic API，但从不出现在的 UI 中。这个简单的布尔标志实现了复杂的双通道通信：一条流面向人类用户，另一条面向 AI 模型。元工具的元提示（Meta-prompting）！ When a skill executes, the system injects two separate user messages into the conversation history. The first carries skill metadata with `isMeta: false`, making it visible to users as a status indicator. The second carries the full skill prompt with `isMeta: true`, hiding it from the UI while making it available to Claude. This split solves the transparency vs clarity tradeoff by showing users what’s happening without overwhelming them with implementation details. 当技能执行时，系统向对话历史注入两条独立的用户消息。第一条携带 `isMeta: false` 的技能元数据，使其作为状态指示器对用户可见。第二条携带 `isMeta: true` 的完整技能提示词，将其从 UI 隐藏但对 Claude 可用。这种拆分通过向用户展示正在发生的事情而不让他们被实现细节淹没，解决了透明度与清晰度之间的权衡。 The metadata message uses a concise XML structure that the frontend can parse and display appropriately: 元数据消息使用前端可解析并适当显示的简洁 XML 结构： ```javascript let metadata = [ `${statusMessage}`, `${skillName}`, args ? `${args}` : null ].filter(Boolean).join('\n'); // Message 1: NO isMeta flag → defaults to false → VISIBLE // 消息 1: 无 isMeta 标志 → 默认为 false → 可见 messages.push({ content: metadata, autocheckpoint: checkpointFlag }); ``` When the PDF skill activates, for example, users see a clean loading indicator in their transcript: 例如，当 PDF 技能激活时，用户在记录中看到一个干净的加载指示器： ```xml The "pdf" skill is loading

pdf

report.pdf ``` This message stays intentionally minimal - typically 50 to 200 characters. The XML tags enable the frontend to render it with special formatting, validate that proper `` tags are present, and maintain an audit trail of which skills executed during the session. Because the `isMeta` flag defaults to false when omitted, this metadata automatically appears in the UI. 这条消息故意保持极简——通常 50 到 200 个字符。XML 标签使前端能够用特殊格式渲染它，验证是否存在正确的 `` 标签，并维护会话期间执行了哪些技能的审计跟踪。因为省略时 `isMeta` 标志默认为 false，此元数据会自动出现在 UI 中。 The skill prompt message takes the opposite approach. It loads the full content from `SKILL.md`, potentially augments it with additional context, and explicitly sets `isMeta: true` to hide it from users: 技能提示词消息采用相反的方法。它从 `SKILL.md` 加载完整内容，可能用额外的上下文进行扩充，并显式设置 `isMeta: true` 以对用户隐藏： ```javascript let skillPrompt = await skill.getPromptForCommand(args, context); // Augment with prepend/append content if needed // 如有需要，扩充前置/后置内容 let fullPrompt = prependContent.length > 0 || appendContent.length > 0 ? [...prependContent, ...appendContent, ...skillPrompt] : skillPrompt; // Message 2: Explicit isMeta: true → HIDDEN // 消息 2: 显式 isMeta: true → 隐藏 messages.push({ content: fullPrompt, isMeta: true // HIDDEN FROM UI, SENT TO API / UI 不可见，发送给 API }); ``` A typical skill prompt runs 500 to 5,000 words and provides comprehensive guidance to transform Claude’s behavior. The PDF skill prompt might contain: 典型的技能提示词长达 500 到 5,000 字，提供全面的指导以转变 Claude 的行为。PDF 技能提示词可能包含： ```markdown You are a PDF processing specialist. Your task is to extract text from PDF documents using the pdftotext tool. ## Process 1. Validate the PDF file exists 2. Run pdftotext command to extract text 3. Read the output file 4. Present the extracted text to the user ## Tools Available You have access to: - Bash(pdftotext:*) - For running pdftotext command - Read - For reading extracted text - Write - For saving results if needed ## Output Format Present the extracted text clearly formatted. Base directory: /path/to/skill User arguments: report.pdf ``` This prompt establishes task context, outlines the workflow, specifies available tools, defines output format, and provides environment-specific paths. The markdown structure with headers, lists, and code blocks helps Claude parse and follow the instructions. With `isMeta: true`, this entire prompt gets sent to the API but never clutters the user’s transcript. 此提示词建立了任务语境，概述了工作流，指定了可用工具，定义了输出格式，并提供了特定环境的路径。带有标题、列表和代码块的 Markdown 结构有助于 Claude 解析并遵循指令。有了 `isMeta: true`，整个提示词被发送到 API，但绝不会弄乱用户的记录。 Beyond the core metadata and skill prompt, skills can inject additional conditional messages for attachments and permissions: 除了核心元数据和技能提示词外，技能还可以为附件和权限注入额外的条件消息： ```javascript let allMessages = [ createMessage({ content: metadata, autocheckpoint: flag }), // 1. Metadata / 元数据 createMessage({ content: skillPrompt, isMeta: true }), // 2. Skill prompt / 技能提示词 ...attachmentMessages, // 3. Attachments (conditional) / 附件（条件性） ...(allowedTools.length || skill.model ? [ createPermissionsMessage({ // 4. Permissions (conditional) / 权限（条件性） type: "command_permissions", allowedTools: allowedTools, model: skill.useSmallFastModel ? getFastModel() : skill.model }) ] : []) ]; ``` Attachment messages can carry diagnostics information, file references, or additional context that supplements the skill prompt. Permission messages only appear when the skill specifies `allowed-tools` in its frontmatter or requests a model override, providing metadata that modifies the runtime execution environment. This modular composition allows each message to have a specific purpose and be included or excluded based on the skill’s configuration, extending the basic two-message pattern to handle more complex scenarios while maintaining the same visibility control through `isMeta` flags. 附件消息可以携带诊断信息、文件引用或补充技能提示词的额外语境。权限消息仅在技能在 Frontmatter 中指定 `allowed-tools` 或请求模型覆盖时出现，提供修改运行时执行环境的元数据。这种模块化组合允许每条消息都有特定用途，并根据技能配置包含或排除，从而扩展了基本的双消息模式以处理更复杂的场景，同时通过 `isMeta` 标志保持相同的可见性控制。 #### Why Two Messages Instead of One? #### 为什么是两条消息而不是一条？ A single-message design would force an impossible choice. Setting `isMeta: false` would make the entire message visible, dumping thousands of words of AI instructions into the user’s chat transcript. Users would see something like: 单条消息设计会迫使我们做出不可能的选择。设置 `isMeta: false` 会使整个消息可见，将成千上万字的 AI 指令倾倒在用户的聊天记录中。用户会看到类似这样的内容： ```plaintext ┌─────────────────────────────────────────────┐ │ The "pdf" skill is loading │ │ │ │ You are a PDF processing specialist. │ │ │ │ Your task is to extract text from PDF │ │ documents using the pdftotext tool. │ │ │ │ ## Process │ │ │ │ 1. Validate the PDF file exists │ │ 2. Run pdftotext command to extract text │ │ 3. Read the output file │ │ ... [500 more lines] ... │ └─────────────────────────────────────────────┘ ``` The UI becomes unusable, filled with internal implementation details meant for Claude, not humans. Alternatively, setting `isMeta: true` would hide everything, providing no transparency about which skill activated or what arguments it received. Users would have no visibility into what the system is doing on their behalf. UI 变得不可用，充满了给 Claude 而非人类看的内部实现细节。或者，设置 `isMeta: true` 会隐藏一切，不提供关于哪个技能被激活或接收了什么参数的透明度。用户对系统代表他们做了什么一无所知。 The two-message split resolves this by giving each message a different `isMeta` value. Message 1 with `isMeta: false` provides user-facing transparency. Message 2 with `isMeta: true` provides Claude with detailed instructions. This granular control enables transparency without information overload. 双消息拆分通过给每条消息不同的 `isMeta` 值解决了这个问题。带有 `isMeta: false` 的消息 1 提供面向用户的透明度。带有 `isMeta: true` 的消息 2 为 Claude 提供详细指令。这种细粒度的控制实现了透明度而无信息过载。 The messages also serve fundamentally different audiences and purposes: 这些消息也服务于根本不同的受众和目的： | Aspect / 维度 | Metadata Message / 元数据消息 | Skill Prompt Message / 技能提示词消息 | | :--- | :--- | :--- | | **Audience**
**受众** | Human user
人类用户 | Claude (AI)
Claude (AI) | | **Purpose**
**目的** | Status/transparency
状态/透明度 | Instructions/guidance
指令/指导 | | **Length**
**长度** | ~50-200 chars
约 50-200 字符 | ~500-5,000 words
约 500-5,000 字 | | **Format**
**格式** | Structured XML
结构化 XML | Natural language markdown
自然语言 Markdown | | **Visibility**
**可见性** | Should be visible
应可见 | Should be hidden
应隐藏 | | **Content**
**内容** | “What is happening?”
“正在发生什么？” | “How to do it?”
“如何做？” | The codebase even processes these messages through different paths. The metadata message gets parsed for `` tags, validated, and formatted for UI display. The skill prompt message gets sent directly to the API without parsing or validation—it’s raw instructional content meant only for Claude’s reasoning process. Combining them would violate the Single Responsibility Principle by forcing one message to serve two distinct audiences through two different processing pipelines. 代码库甚至通过不同的路径处理这些消息。元数据消息会被解析 `` 标签，进行验证并格式化以供 UI 显示。技能提示词消息直接发送到 API，无需解析或验证——它是仅供 Claude 推理过程使用的原始指令内容。将它们合并会迫使一条消息通过两个不同的处理管道服务于两个不同的受众，违反了单一职责原则。 ### Case Study: Execution Lifecycle ### 案例研究：执行生命周期 Now covered Agent Skills internal architecture, let’s walk through what happens when a user says “Extract text from report.pdf” by examining the complete execution flow using a hypothetical `pdf` skill as a case study. 在介绍了智能体技能内部架构后，让我们以一个假设的 `pdf` 技能为例，通过检查完整的执行流程，来看看当用户说“从 report.pdf 中提取文本”时会发生什么。 ![Claude Skill Execution Flow](/assets/img/2025-10-26/07-claude-skill-sequence-diagram.png) #### Phase 1: Discovery & Loading (Startup) #### 阶段 1：发现与加载（启动） When Claude Code starts, it scans for skills: 当 Claude Code 启动时，它扫描技能： ```javascript async function getAllCommands() { // Load from all sources in parallel / 并行从所有来源加载 let [userCommands, skillsAndPlugins, pluginCommands, builtins] = await Promise.all([ loadUserCommands(), // ~/.claude/commands/ loadSkills(), // .claude/skills/ + plugins loadPluginCommands(), // Plugin-defined commands / 插件定义的命令 getBuiltinCommands() // Hardcoded commands / 硬编码的命令 ]); return [...userCommands, ...skillsAndPlugins, ...pluginCommands, ...builtins] .filter(cmd => cmd.isEnabled()); } // Specific skill loading / 特定技能加载 async function loadPluginSkills(plugin) { // Check if plugin has skills / 检查插件是否有技能 if (!plugin.skillsPath) return []; // Two patterns supported: / 支持两种模式： // 1. Root SKILL.md in skillsPath / 根目录 SKILL.md // 2. Subdirectories with SKILL.md / 子目录中的 SKILL.md const skillFiles = findSkillMdFiles(plugin.skillsPath); const skills = []; for (const file of skillFiles) { const content = readFile(file); const { frontmatter, markdown } = parseFrontmatter(content); skills.push({ type: "prompt", name: `${plugin.name}:${getSkillName(file)}`, description: `${frontmatter.description} (plugin:${plugin.name})`, whenToUse: frontmatter.when_to_use, // ← Note: underscores! / 注意：下划线！ allowedTools: parseTools(frontmatter['allowed-tools']), model: frontmatter.model === "inherit" ? undefined : frontmatter.model, isSkill: true, promptContent: markdown, // ... other fields }); } return skills; } ``` For the pdf skill, this produces: 对于 pdf 技能，生成结果如下： ```javascript { type: "prompt", name: "pdf", description: "Extract text from PDF documents (plugin:document-tools)", whenToUse: "When user wants to extract or process text from PDF files", allowedTools: ["Bash(pdftotext:*)", "Read", "Write"], model: undefined, // Uses session model / 使用会话模型 isSkill: true, disableModelInvocation: false, promptContent: "You are a PDF processing specialist...", // ... other fields } ``` #### Phase 2: Turn 1 - User Request & Skill Selection #### 阶段 2：第 1 轮 - 用户请求与技能选择 The user sends a request: “Extract text from report.pdf”. Claude receives this message along with the `Skill` tool in its tools array. Before Claude can decide to invoke the pdf skill, the system must present available skills in the Skill tool’s description. 用户发送请求：“Extract text from report.pdf”。Claude 收到这条消息以及其工具数组中的 `Skill` 工具。在 Claude 决定调用 pdf 技能之前，系统必须在 Skill 工具的描述中展示可用技能。 ##### Skill Filtering & Presentation / 技能过滤与展示 Not all loaded skills appear in the Skill tool. A skill MUST have either `description` OR `when_to_use` in frontmatter, or it’s filtered out. Filtering criteria: 并非所有加载的技能都会出现在 Skill 工具中。技能的 Frontmatter 中必须有 `description` 或 `when_to_use`，否则会被过滤掉。过滤标准： ```javascript async function getSkillsForSkillTool() { const allCommands = await getAllCommands(); return allCommands.filter(cmd => cmd.type === "prompt" && cmd.isSkill === true && !cmd.disableModelInvocation && (cmd.source !== "builtin" || cmd.isModeCommand === true) && (cmd.hasUserSpecifiedDescription || cmd.whenToUse) // ← Must have one! / 必须有一个！ ); } ``` ##### Skill Formatting / 技能格式化 Each skill is formatted for the `` section. As an example, our hypothetical `pdf` skill could be formatted into 每个技能都格式化为 `` 部分的内容。例如，我们假设的 `pdf` 技能可以格式化为： `"pdf": Extract text from PDF documents - When user wants to extract or process text from PDF files` ```javascript function formatSkill(skill) { let name = skill.name; let description = skill.whenToUse ? `${skill.description} - ${skill.whenToUse}` : skill.description; return `"${name}": ${description}`; } ``` ##### Claude’s Decision Process / Claude 的决策过程 Now, when user prompts: “Extract text from report.pdf”. Claude receives the API request with the `Skill` tool, reads the ``, and reasons (hypothetically, as we do not see reasoning traces): 现在，当用户提示：“Extract text from report.pdf”。Claude 收到带有 `Skill` 工具的 API 请求，读取 ``，并进行推理（假设过程，因为我们看不到推理痕迹）： ```plaintext Internal reasoning: - User wants to "extract text from report.pdf" - This is a PDF processing task - Looking at available skills... - "pdf": Extract text from PDF documents - When user wants to extract or process text from PDF files - This matches! The user wants to extract text from a PDF - Decision: Invoke Skill tool with command="pdf" 内部推理： - 用户想要“从 report.pdf 中提取文本” - 这是一个 PDF 处理任务 - 查看可用技能... - "pdf"：从 PDF 文档中提取文本 - 当用户想要提取或处理 PDF 文件中的文本时 - 这个匹配！用户想要从 PDF 中提取文本 - 决策：调用 Skill 工具，参数 command="pdf" ``` Note that there’s no algorithmic matching here. No lexical matching. No semantic matching. No searches. This is pure LLM reasoning for its decisions based on the description of the skill. Once done, Claude returns a tool use: 注意，这里没有算法匹配。没有词法匹配。没有语义匹配。没有搜索。这是纯粹的大模型根据技能描述进行决策推理。完成后，Claude 返回工具使用请求： ```json { "type": "tool_use", "id": "toolu_123abc", "name": "Skill", "input": { "command": "pdf" } } ``` #### Phase 3: Skill Tool Execution #### 阶段 3：Skill 工具执行 The Skill tool now executes. This corresponds to the yellow “SKILL TOOL EXECUTION” box in the sequence diagram, which performs validation, permission checks, file loading, and context modification before yielding the result. Skill 工具现在开始执行。这对应于时序图中的黄色“SKILL TOOL EXECUTION”框，它在产生结果之前执行验证、权限检查、文件加载和语境修改。 ##### Step 1: Validation / 步骤 1：验证 ```javascript async validateInput({ command }, context) { let skillName = command.trim().replace(/^\//, ""); // Error 1: Empty / 空 if (!skillName) return { result: false, errorCode: 1 }; // Error 2: Unknown skill / 未知技能 const allSkills = await getAllCommands(); if (!skillExists(skillName, allSkills)) { return { result: false, errorCode: 2 }; } // Error 3: Can't load / 无法加载 const skill = getSkill(skillName, allSkills); if (!skill) return { result: false, errorCode: 3 }; // Error 4: Model invocation disabled / 模型调用被禁用 if (skill.disableModelInvocation) { return { result: false, errorCode: 4 }; } // Error 5: Not prompt-based / 不是基于 prompt 的 if (skill.type !== "prompt") { return { result: false, errorCode: 5 }; } return { result: true }; } ``` The pdf skill passes all validation checks ✓ pdf 技能通过所有验证检查 ✓ ##### Step 2: Permission Check / 步骤 2：权限检查 ```javascript async checkPermissions({ command }, context) { const skillName = command.trim().replace(/^\//, ""); const permContext = (await context.getAppState()).toolPermissionContext; // Check deny rules / 检查拒绝规则 for (const [pattern, rule] of getDenyRules(permContext)) { if (matches(skillName, pattern)) { return { behavior: "deny", message: "Blocked by permission rules" }; } } // Check allow rules / 检查允许规则 for (const [pattern, rule] of getAllowRules(permContext)) { if (matches(skillName, pattern)) { return { behavior: "allow" }; } } // Default: ask user / 默认：询问用户 return { behavior: "ask", message: `Execute skill: ${skillName}` }; } ``` Assuming no rules, user is prompted: “Execute skill: pdf?” User approves ✓ 假设没有规则，用户会被提示：“Execute skill: pdf?” 用户批准 ✓ ##### Step 3: Load Skill File and Generate Execution Context Modification ##### 步骤 3：加载技能文件并生成执行语境修改 With validation and permissions approved, the Skill tool loads the skill file and prepares the execution context modification: 随着验证和权限获得批准，Skill 工具加载技能文件并准备执行语境修改： ```javascript async *call({ command }, context) { const skillName = command.trim().replace(/^\//, ""); const allSkills = await getAllCommands(); const skill = getSkill(skillName, allSkills); // Load the skill prompt / 加载技能提示词 const promptContent = await skill.getPromptForCommand("", context); // Generate metadata tags / 生成元数据标签 const metadata = [ `The "${skill.userFacingName()}" skill is loading`, `${skill.userFacingName()}` ].join('\n'); // Create messages / 创建消息 const messages = [ { type: "user", content: metadata }, // Visible to user / 用户可见 { type: "user", content: promptContent, isMeta: true }, // Hidden from user, visible to Claude / 用户隐藏，Claude 可见 // ... attachments, permissions ]; // Extract configuration / 提取配置 const allowedTools = skill.allowedTools || []; const modelOverride = skill.model; // Yield result with execution context modifier / 产出结果及执行语境修改器 yield { type: "result", data: { success: true, commandName: skillName }, newMessages: messages, // 🔑 Execution context modification function / 🔑 执行语境修改函数 contextModifier(context) { let modified = context; // Inject allowed tools / 注入允许的工具 if (allowedTools.length > 0) { modified = { ...modified, async getAppState() { const state = await context.getAppState(); return { ...state, toolPermissionContext: { ...state.toolPermissionContext, alwaysAllowRules: { ...state.toolPermissionContext.alwaysAllowRules, command: [ ...state.toolPermissionContext.alwaysAllowRules.command || [], ...allowedTools // ← Pre-approve these tools / ← 预批准这些工具 ] } } }; } }; } // Override model / 覆盖模型 if (modelOverride) { modified = { ...modified, options: { ...modified.options, mainLoopModel: modelOverride } }; } return modified; } }; } ``` The Skill tool yields its result containing `newMessages` (metadata + skill prompt + permissions for conversation context injection) and `contextModifier` (tool permissions + model override for execution context modification). This completes the yellow “SKILL TOOL EXECUTION” box from the sequence diagram. Skill 工具产出包含 `newMessages`（元数据 + 技能提示词 + 权限，用于对话语境注入）和 `contextModifier`（工具权限 + 模型覆盖，用于执行语境修改）的结果。这完成了时序图中黄色的“SKILL TOOL EXECUTION”框。 #### Phase 4: Send to API (Turn 1 Completion) #### 阶段 4：发送到 API（第 1 轮完成） The system constructs the complete messages array to send to the Anthropic API. This includes all messages from the conversation plus the newly injected skill messages: 系统构建完整的消息数组发送到 Anthropic API。这包括来自对话的所有消息加上新注入的技能消息： ```javascript // Complete message array sent to API for Turn 1 // 第 1 轮发送到 API 的完整消息数组 { model: "claude-sonnet-4-5-20250929", messages: [ { role: "user", content: "Extract text from report.pdf" }, { role: "assistant", content: [ { type: "tool_use", id: "toolu_123abc", name: "Skill", input: { command: "pdf" } } ] }, { role: "user", content: "The \"pdf\" skill is loading\npdf" // isMeta: false (default) - VISIBLE to user in UI / UI 用户可见 }, { role: "user", content: "You are a PDF processing specialist...\n\n## Process\n1. Validate PDF exists\n2. Run pdftotext...", isMeta: true // HIDDEN from UI, sent to API / UI 隐藏，发送到 API }, { role: "user", content: { type: "command_permissions", allowedTools: ["Bash(pdftotext:*)", "Read", "Write"], model: undefined } } ] } ``` ![Turn 1 Completion](/assets/img/2025-10-26/11-turn-1-completion.png) The above shows what we have done up to this point. The execution context modifier is applied, pre-approving `Bash(pdftotext:*)`, `Read`, and `Write` for subsequent tool calls. The request is sent to the Anthropic API. This concludes the skill execution. If this is a normal tool, we are all done. However, skills are different. Agent skill has only injected the conversation context and execution contexts. This means we still need to invoke Claude agent with all these injected contexts to complete user’s request! 以上展示了我们到目前为止所做的工作。执行语境修改器已应用，为后续工具调用预批准了 `Bash(pdftotext:*)`、`Read` 和 `Write`。请求被发送到 Anthropic API。这结束了技能执行。如果这是一个普通工具，我们就完成了。然而，技能不同。智能体技能仅仅注入了对话语境和执行语境。这意味着我们仍然需要在所有这些注入语境下调用 Claude 智能体，以完成用户的请求！ #### Phase 5: Bash Tool Execution (Tool use with Skill Context!) #### 阶段 5：Bash 工具执行（在技能语境下使用工具！） Claude receives the API response with the injected conversation context. The skill prompt has transformed Claude’s behavior, providing it with: Claude 收到带有注入对话语境的 API 响应。技能提示词已经转变了 Claude 的行为，为其提供了： * Specialized PDF processing instructions (conversation context) 专门的 PDF 处理指令（对话语境） * Pre-approved access to `Bash(pdftotext:*)`, `Read`, and `Write` tools (execution context) 预批准访问 `Bash(pdftotext:*)`、`Read` 和 `Write` 工具（执行语境） * A clear workflow to follow (conversation context) 清晰的可遵循工作流（对话语境） Claude processes the context and follows the pdf skill’s workflow: Claude 处理语境并遵循 pdf 技能的工作流： ```plaintext I'll extract text from report.pdf. Let me process the file. [Following pdf skill's instructions] 1. Validate that report.pdf exists 2. Run pdftotext command to extract text 3. Read the output file 4. Present the extracted text to you ``` Claude uses the Bash tool (pre-approved, no user prompt required): Claude 使用 Bash 工具（预批准，无需用户提示）： ```json { "type": "tool_use", "id": "toolu_456def", "name": "Bash", "input": { "command": "pdftotext report.pdf output.txt", "description": "Extract text from PDF using pdftotext" } } ``` The Bash tool executes successfully, returning the result. Claude then reads the output file using the Read tool and presents the extracted text to the user. The skill has successfully guided Claude through the specialized PDF extraction workflow by injecting instructions into the conversation context and modifying the execution context for tool permissions. Bash 工具成功执行并返回结果。Claude 随后使用 Read 工具读取输出文件，并将提取的文本呈现给用户。该技能通过将指令注入对话语境并修改工具权限的执行语境，成功引导 Claude 完成了专门的 PDF 提取工作流。 --- ## Conclusion: The Mental Model Recap ## 结论：心智模型重述 Skills in Claude Code are **prompt-based conversation and execution context modifiers** that work through a meta-tool architecture: Claude Code 中的技能是**基于提示词的对话和执行语境修改器**，通过元工具架构工作： **Key Takeaways / 关键要点：** 1. Skills are **prompt templates** in `SKILL.md` files, not executable code 技能是 `SKILL.md` 文件中的**提示词模板**，不是可执行代码。 2. The **Skill tool** (capital S) is a meta-tool in the `tools` array that manages individual skills, not in the system prompt **Skill 工具**（大写 S）是 `tools` 数组中管理个体技能的元工具，不在系统提示词中。 3. Skills **modify conversation context** by injecting instruction prompts (via `isMeta: true` messages) 技能通过注入指令提示词（经由 `isMeta: true` 消息）来**修改对话语境**。 4. Skills **modify execution context** by changing tool permissions and model selection 技能通过改变工具权限和模型选择来**修改执行语境**。 5. Selection happens via **LLM reasoning**, not algorithmic matching 选择通过**大模型推理**发生，而非算法匹配。 6. Tool permissions are **scoped to skill execution** via execution context modification 工具权限通过执行语境修改被**限定在技能执行范围内**。 7. Skills inject two user messages per invocation—one for user-visible metadata, one for hidden instructions sent to the API 技能每次调用注入两条用户消息——一条用于用户可见的元数据，一条用于发送给 API 的隐藏指令。 **The Elegant Design:** By treating specialized knowledge as *prompts that modify conversation context* and *permissions that modify execution context* rather than *code that executes*, Claude Code achieves flexibility, safety, and composability that would be difficult with traditional function calling. **优雅的设计：** 通过将专业知识视为*修改对话语境的提示词*和*修改执行语境的权限*，而不是*执行的代码*，Claude Code 实现了传统函数调用难以企及的灵活性、安全性和可组合性。 --- ## References ## 参考资料 * [Introducing Agent Skills](https://www.anthropic.com/news/skills) * [Equipping Agents for the Real World with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) * [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code/overview) * [Anthropic API Reference](https://docs.anthropic.com/en/api/messages) * [Official Documented Frontmatter Fields](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview#skill-structure) * [Internal Comms Skill](https://github.com/anthropics/skills/tree/main/internal-comms) * [Skill Creator Skill](https://github.com/anthropics/skills/tree/main/skill-creator) * [ChatGPT 5 System Prompt (leaked, not official)](https://github.com/elder-plinius/CL4R1T4S/blob/main/OPENAI/ChatGPT5-08-07-2025.mkd)