Claude Skills 底层技术详解，太硬核了

Claude Skills 底层技术详解，太硬核了 Claude Skills 底层技术详解，太硬核了 Modified December 26, 2025 Code block JavaScript // 消息2：显式isMeta: true → 隐藏（仅发送到API，不在UI展示） messages.push({ content: fullPrompt, isMeta: true // 从UI隐藏，发送到API }); 典型skill提示词有500到5000字，提供全面指导来转换Claude的行为。 PDF skill提示词可能包含： Code block Markdown PDF 文本提取处理规范 角色定位 你是PDF处理专家，核心任务是使用pdftotext工具从PDF文档中提取文本。 执行流程（按顺序执行） 1. 验证目标PDF文件是否存在 2. 运行pdftotext命令提取文本内容 3. 读取命令输出的文本文件 4. 向用户清晰展示提取到的文本内容 可用工具 可调用的工具列表： Bash(pdftotext: )：执行pdftotext相关命令 Read：读取提取后的文本文件内容 Write：（可选）保存提取结果到文件 输出要求 提取的文本需以清晰、格式化的方式展示给用户。 基础配置 基础目录：/path/to/skill 用户传入参数（目标PDF）：report.pdf 这个提示词建立任务上下文、概述工作流、指定可用工具、定义输出格式，并提供环境特定路径。 带头的markdown结构、列表和代码块帮助Claude解析和遵循指令。 为什么两条消息而不是一条？ 单消息设计对用户体验不好。 设置 isMeta: false 会让整条消息可见，把成千上万字的AI指令倾倒到用户的聊天记录里。 用户会看到这样： • Code block Plain Text ┌─────────────────────────────────────────────────────────────────┐ │ "pdf" skill 正在加载 │ │ 【角色定位】 │ 你是PDF处理专家。 │ │ 【核心任务】 │ 用pdftotext工具从PDF文档提取文本。 │ │ 【执行流程】 │ 1. 验证PDF文件存在 │ 2. 运行pdftotext命令提取文本 │ 3. 读输出文件 │ ...[还有500行]... └─────────────────────────────────────────────────────────────────┘ UI变得不可用，充满了给Claude用的内部实现细节，不是给人类用的。 消息也服务于根本不同的受众和目的： 方面 元数据消息 Skill提示词消息 受众 人类用户 Claude（AI） 目的 状态/透明度 指令/指导 长度 约50 200字符 约500 5000字 格式 结构化XML 自然语言markdown 可见性 应该可见 应该隐藏 内容 "发生了什么？" "如何做？" 代码库甚至通过不同路径处理这些消息。 元数据消息被解析 <command message 标签，验证，并格式化用于UI显示。 skill提示词消息直接发送到API，没有解析或验证，它是只给Claude推理过程用的原始指令内容。 组合它们会违反单一职责原则。 强制一条消息通过两个不同的处理管道服务两个不同的受众。 案例研究：执行生命周期 既然介绍了Agent Skills的内部架构。 让我们走一遍当用户说"从report.pdf提取文本"时发生了什么。 阶段1：发现和加载（启动） Claude Code启动时，扫描skills： Code block JavaScript async function getAllCommands() { // 并行从所有来源加载命令 let [userCommands, skillsAndPlugins, pluginCommands, builtins] = await Promise.all([ loadUserCommands(), // /.claude/commands/ 用户自定义命令 loadSkills(), // .claude/skills/ + 插件 技能和插件命令 loadPluginCommands(), // 插件定义的命令 getBuiltinCommands() // 硬编码命令 内置命令 ]); // 合并所有命令并过滤仅启用的命令 return [ ...userCommands, ...skillsAndPlugins, ...pluginCommands, ...builtins ].filter(cmd = cmd.isEnabled()); } // 具体插件技能加载逻辑 async function loadPluginSkills(plugin) { // 如果插件没有技能路径，返回空数组 if (!plugin.skillsPath) return []; // 获取插件目录下所有技能markdown文件 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: , description: , whenToUse: frontmatter.when to use, allowedTools: parseTools(frontmatter['allowed tools']), model: frontmatter.model === "inherit" ? undefined : frontmatter.model, isSkill: true, promptContent: markdown, // ... 其他字段 }); } return skills; } 典型skill提示词有500到5000字，提供全面指导来转换Claude的行为。 PDF skill提示词可能包含： 这个提示词建立任务上下文、概述工作流、指定可用工具、定义输出格式，并提供环境特定路径。 带头的markdown结构、列表和代码块帮助Claude解析和遵循指令。 为什么两条消息而不是一条？ 单消息设计对用户体验不好。 设置 isMeta: false 会让整条消息可见，把成千上万字的AI指令倾倒到用户的聊天记录里。 用户会看到这样： • UI变得不可用，充满了给Claude用的内部实现细节，不是给人类用的。 消息也服务于根本不同的受众和目的： 方面 元数据消息 Skill提示词消息 受众 人类用户 Claude（AI） 目的 状态/透明度 指令/指导 长度 约50 200字符 约500 5000字 格式 结构化XML 自然语言markdown 可见性 应该可见 应该隐藏 内容 "发生了什么？" "如何做？" 方面 方面 元数据消息 元数据消息 Skill提示词消息 Skill提示词消息 受众 受众 人类用户 人类用户 Claude（AI） Claude（AI） 目的 目的 状态/透明度 状态/透明度 指令/指导 指令/指导 长度 长度 约50 200字符 约50 200字符 约500 5000字 约500 5000字 格式 格式 结构化XML 结构化XML 自然语言markdown 自然语言markdown 可见性 可见性 应该可见 应该可见 应该隐藏 应该隐藏 内容 内容 "发生了什么？" "发生了什么？" "如何做？" "如何做？" 代码库甚至通过不同路径处理这些消息。 元数据消息被解析 <command message 标签，验证，并格式化用于UI显示。 skill提示词消息直接发送到API，没有解析或验证，它是只给Claude推理过程用的原始指令内容。 组合它们会违反单一职责原则。 强制一条消息通过两个不同的处理管道服务两个不同的受众。 案例研究：执行生命周期 既然介绍了Agent Skills的内部架构。 让我们走一遍当用户说"从report.pdf提取文本"时发生了什么。 阶段1：发现和加载（启动） Claude Code启动时，扫描skills： 上图显示了我们到此为止做的事情。 执行上下文修改器被应用，预批准 Bash(pdftotext: ) 、 Read 和 Write 用于后续工具调用。 请求发送到Anthropic API。 这结束了skill执行。 如果这是普通工具，我们就完成了。但skills不同。 Agent skill只注入了对话上下文和执行上下文。 这意味着我们仍需用所有这些注入的上下文调用Claude Agent来完成用户请求！ 阶段5：Bash工具执行（用Skill上下文使用工具！） Claude收到带注入对话上下文的API响应。 skill提示词已经转换了Claude的行为，提供给它： • 专门的PDF处理指令（对话上下文） • 预批准访问 Bash(pdftotext: ) 、 Read 和 Write 工具（执行上下文） • 要遵循的清晰工作流（对话上下文） Claude处理上下文并遵循pdf skill的工作流： Claude使用Bash工具（预批准，不需要用户提示）： Bash工具成功执行，返回结果。 Claude然后用Read工具读输出文件，向用户展示提取的文本。 skill通过向对话上下文注入指令和修改工具权限的执行上下文，成功引导Claude完成了专门的PDF提取工作流。 总结：心智模型回顾 Claude Code里的Skills是 基于提示词的对话和执行上下文修改器 ，通过元工具架构工作： 关键要点： 1. Skills是 SKILL.md 文件里的 提示词模板 ，不是可执行代码 2. Skill工具 （大写S）是 tools 数组里管理单个skills的元工具，不在系统提示词里 3. Skills通过注入指令提示词（via isMeta: true 消息） 修改对话上下文 4. Skills通过改变工具权限和模型选择 修改执行上下文 5. 选择通过 LLM推理 发生，不是算法匹配 6. 工具权限通过执行上下文修改 限定在skill执行范围 7. Skills每次调用注入两条用户消息，一条用于用户可见的元数据，一条用于发送到API的隐藏指令 优雅的设计： 通过将专门知识作为 修改对话上下文的提示词 和 修改执行上下文的权限 ，Claude Code实现了传统函数调用难以达到的灵活性、安全性和可组合性。 就像给Claude装上不同的专业插件。 需要处理PDF？ 插上PDF专家插件。 需要创建skill？换上skill creator插件。 每个插件都带着自己的专业知识和工具权限，用完就卸载，干净利落。 参考资源 • Introducing Agent Skills[https://www.anthropic.com/news/skills] • Claude [https://docs.claude.com/en/docs/claude code/overview] • Anthropic API Reference[https://docs.anthropic.com/en/api/messages] • [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] 🔗 原文链接： https://mp.weixin.qq.com/s/GheJcz2L... https://mp.weixin.qq.com/s/GheJcz2L... 原创 向阳乔木 AI不插电2025年12月25日 10:43 天津 Claude的Skills系统，一套 基于提示词的元工具架构 ，像"一个管理工具的工具"。 直白点说，Skills系统就是用提示词来扩展AI的能力，而不是写代码。 原文来自：Claude Skill 第一性原理解读。 https://leehanchung.github.io/blogs/2025/10/26/claude skills deep dive/ 超级长，值得收藏学习， 太硬核了！ Skills到底是什么 先说清楚一件事： Skills不是可执行代码 。 它们不会运行Python或JavaScript，也没有HTTP服务器在后台。 Skills甚至不会写在Claude的系统提示词里。 那它们是什么？ Skills是专门的提示词模板 ，用来给对话上下文注入特定领域的指令。 当一个skill被调用时，它会修改对话上下文（注入提示词）。 也会修改执行上下文（改变工具权限，可能还会切模型）。 就像给Claude临时换了个专业顾问。 需要处理PDF时，PDF专家顾问上线。 需要创建新skill时，skill creator顾问接管。 skills不会直接执行动作，它们会展开成详细的提示词，让Claude准备好去解决某一类问题。 每个skill在Claude眼里，都是工具清单里动态新增的一项。 当你发送请求时，Claude收到三样东西： 你的消息、可用的工具（Read、Write、Bash等），以及Skill工具。 Skill 工具的描述信息包含了所有可用skill列表，每个skill都有 name 和 description 。 （名字和描述） Claude 会读这个列表，用它的语言理解能力来匹配你的意图。 比如你说"帮我从PDF里提取文字"，Claude看到 pdf skill的描述"提取PDF文档中的文本"，会认为工具匹配。 然后调用 Skill 工具，参数是 command: "pdf" 。 两个概念要分清 • Skill 工具 （大写S）：管理所有skills的元工具。它在Claude的 tools 工具数组里，和Read、Write、Bash并列。 • skills （小写s）：单个技能，比如 pdf 、 skill creator 。这些是 Skill 工具会加载的指令模板。 就像一个工具箱（Skill工具）里装着各种专业工具（单个skills）。 skill的选择机制，在代码层面没有任何算法路由或意图分类。 Claude Code不用embedding、不用分类器、不用模式匹配来决定调用哪个skill。 系统把所有可用的skills格式化成文本描述，嵌入在 Skill 工具的提示词里，让Claude的语言模型来做决定。 这是纯粹的LLM推理。 没有正则，没有关键词匹配，没有基于机器学习的意图检测。 决策发生在Claude的transformer前向传播里，不在应用代码里。 前向传播: 指数据在神经网络中从输入到输出的单向流动过程 。 这和传统工具完全不同。传统工具执行后返回结果。 Skills是 准备Claude去解决问题 ，而不是直接解决它。 方面 传统工具 Skills 执行模型 同步、直接 提示词展开 目的 执行特定操作 引导复杂工作流 返回值 即时结果 对话上下文+执行上下文变化 例子 Read、 Write 、 Bash internal comms、 skill creator 并发安全 一般安全 不保证并发安全 类型 各种 总是 "prompt" 方面 方面 传统工具 传统工具 Skills Skills 执行模型 执行模型 同步、直接 同步、直接 提示词展开 提示词展开 目的 目的 执行特定操作 执行特定操作 引导复杂工作流 引导复杂工作流 返回值 返回值 即时结果 即时结果 对话上下文+执行上下文变化 对话上下文+执行上下文变化 例子 例子 Read、 Write 、 Bash Read、 Write 、 Bash internal comms、 skill creator internal comms、 skill creator 并发安全 并发安全 一般安全 一般安全 不保证并发安全 不保证并发安全 类型 类型 各种 各种 总是 "prompt" 总是 "prompt" 如何构建一个Skill 我们用Anthropic的 skill creator 的官方案例来学习： 每个skill都定义在一个叫 SKILL.md 的markdown文件里（不区分大小写），另外附带一些脚本、参考文档和资源文件，分别放在 /scripts 、 /references 、 /assets 目录下。 注意：必须有SKILL.md，其他文件夹和文件不一定有。 skill creator 包含 SKILL.md 、 LICENSE.txt 许可证文件，以及 /scripts 文件夹下的几个Python脚本。 它没有 /references 或 /assets 。 Skills会从多个来源被发现和加载。 Claude Code会扫描用户设置（ /.config/claude/skills/ ）、项目设置（ .claude/skills/ ）、插件提供的skills，以及内置skills，来构建可用skills列表。 信息披露的层次是： 1. 先披露Frontmatter：最小信息（名字、描述、许可证） 2. 如果skill被选中，加载SKILL.md 3. 然后在skill执行时加载辅助资源、参考文档和脚本 Frontmatter （前置元数据）是文档开头的一块 元数据区域 ，用三个短横线 ⁠ 包裹，采用 YAML 格式。 编写SKILL.md SKILL.md 是skill提示词的核心。 它是一个markdown文件，分两部分：frontmatter和内容。 Frontmatter配置skill 如何运行 （权限、模型、元数据），markdown内容告诉Claude 做什么 。 示例如下： Frontmatter字段 skill creator 的frontmatter例子： name （必需） ：skill的名字，会用作 Skill 工具的 command 参数。 description （必需） ：简要说明skill做什么。 这是Claude用来决定何时调用skill的主要一句。描述要清晰，面向行动，比如"当用户想创建新skill时使用"。 系统会自动在描述后面加上来源信息（比如 "(plugin:skills)" ），帮助区分不同来源的skills。 when to use （未文档化，可能已废弃或未来特性） ：这个字段虽然没文档，但代码里是这样处理的： 如果存在， when to use 会追加到description后面，用连字符分隔。 不过因为这是未文档化的行为，可能会变。 更安全的做法是把使用指南直接写在 description 里。 allowed tools （可选） ：定义skill可以使用哪些工具，不需要用户批准。 常见工具有： 这是个逗号分隔的字符串，会被解析成工具名数组。 可以用通配符限定范围，比如 Bash(git: ) 只允许git子命令， Bash(npm: ) 允许所有npm操作。 model （可选） ：定义skill可以使用哪个模型。 默认继承当前会话的模型。 复杂任务可以请求更强大的模型。 version 、 disable model invocation 和 mode （可选） ： version 字段（比如 version: "1.0.0" ）是元数据字段，用于跟踪skill版本。 disable model invocation 字段（布尔值）阻止Claude通过 Skill 工具自动调用skill。 设为true时，skill不会显示在Claude看到的列表里，只能用户通过 /skill name 手动调用。 适合危险操作、配置命令或需要明确用户控制的交互式工作流。 mode 字段（布尔值）将skill归类为"模式命令"，用来修改Claude的行为或上下文。 设为true时，skill会出现在技能列表顶部的特殊"模式命令"区域（与常规工具skills分开），适合debug mode、expert mode或review mode这类建立特定操作上下文的skills。 SKILL.md提示词内容 frontmatter后面是markdown内容，也就是Claude在skill被调用时收到的实际提示词。 这里定义skill的行为、指令和工作流。 关键是保持聚焦，使用渐进披露： 在SKILL.md里提供核心指令，引用外部文件来提供详细内容。 推荐的内容结构： skill creator skill包含以下指令，指定了创建skills的每个步骤： 当Claude调用这个skill时，它会收到整个提示词作为新指令，并在前面加上基础目录路径。 {baseDir} 变量会解析为skill的安装目录，让Claude能用Read工具加载参考文件： Read({baseDir}/scripts/init skill.py) 。 这个模式让主提示词保持简洁，同时按需提供详细文档。 提示词内容的最佳实践： • 控制在5000字以内（约800行），避免压倒上下文 • 用命令式语言（"分析代码..."）而不是第二人称（"你应该分析..."） • 引用外部文件获取详细内容，而不是全部嵌入 • 用 {baseDir} 表示路径，绝不硬编码绝对路径 给Skill打包资源 Skills的强大之处在于可以在SKILL.md之外，打包其他资源。 标准结构用三个目录，每个有特定用途： 为什么打包资源？ 保持SKILL.md简洁（5000字以内）避免压倒Claude的上下文窗口。 打包资源让你提供详细文档、自动化脚本和模板，而不会让主提示词膨胀。 Claude只在需要时才加载它们，这叫渐进披露。 scripts目录 scripts/ 目录包含Claude通过Bash工具运行的可执行代码。 自动化脚本、数据处理器或代码生成器，执行确定性操作。 skill creator 的SKILL.md这样引用脚本： Claude看到这个指令时，会执行 python {baseDir}/scripts/init skill.py 。 {baseDir} 变量自动解析为skill的安装路径，让skill可以跨不同环境移植。 scripts/用于： 复杂的多步操作、数据转换、API交互，或 任何用代码表达比自然语言更好的任务 。 references 目录 references/ 目录存放Claude在被引用时会读入上下文的文档。 这是文本内容，markdown文件、JSON schema、配置模板，或Claude完成任务需要的任何文档。 mcp creator 的SKILL.md这样引用references： Claude遇到这些指令时，用Read工具： Read({baseDir}/references/mcp best practices.md) 。 内容会加载到Claude的上下文里，提供详细信息而不会让SKILL.md变得混乱。 references/用于： 详细文档、大型模式库、检查清单、API schema，或任何对SKILL.md来说太冗长但任务必需的文本内容。 assets 目录 assets/ 目录包含Claude通过路径引用但不加载到上下文的模板和二进制文件。 把它想成skill的静态资源，HTML模板、CSS文件、图片、配置样板或字体。 在SKILL.md里： Claude看到文件路径但不读内容。 它可能会把模板复制到新位置，填充占位符，或在生成的输出里引用路径。 assets/用于： HTML/CSS模板、图片、二进制文件、配置模板，或任何Claude通过路径操作而不是读入上下文的文件。 references/ 和 assets/ 的关键区别： • references/ ：通过Read工具加载到Claude上下文的文本内容 • assets/ ：只通过路径引用的文件，不加载到上下文 这个区别对上下文管理很重要。 references/ 里的10KB markdown文件会在加载时消耗上下文tokens。 assets/ 里的10KB HTML模板不会。 Claude只知道路径存在。 常见Skill模式 和所有工程一样，理解常见模式有助于设计有效的skills。 这里是工具集成和工作流设计最有用的模式。 模式1：脚本自动化 用例： 需要多个命令或确定逻辑的复杂操作。 这个模式把计算任务交给 scripts/ 目录里的Python或Bash脚本完成。 skill提示词告诉Claude执行脚本并处理输出。 SKILL.md示例： 需要的工具： 模式2：读 处理 写 用例： 文件转换和数据处理。 最简单的模式，读输入，按指令转换，写输出。 用于格式转换、数据清理或报告生成。 SKILL.md示例： 需要的工具： 模式3：搜索 分析 报告 用例： 代码库分析和模式检测。 用Grep搜索代码库的模式，读匹配文件获取上下文，分析发现，生成结构化报告。 或者搜索企业数据存储，分析检索的数据，生成结构化报告。 SKILL.md示例： 需要的工具： 模式4：命令链执行 用例： 有依赖关系的多步操作。 执行一系列命令，每步依赖前一步的成功。 常见于类似CI/CD的工作流。 CI/CD:一种 自动化软件开发流程 ，让代码从编写到上线的过程更快、更可靠、更频繁。翻译为：持续集成，持续交付。 SKILL.md示例： 需要的工具： 高级模式 向导式多步工作流 用例： 需要每步用户输入的复杂流程。 把复杂任务拆成独立步骤，每个阶段之间有明确的用户确认。 适合设置向导、配置工具或引导流程。 SKILL.md示例： 基于模板的生成 用例： 从 assets/ 里的模板创建结构化输出。 加载模板，用用户提供或生成的数据填充占位符，写入结果。 常用于报告生成、样板代码创建或文档。 SKILL.md示例： 迭代精炼 用例： 需要多轮、逐渐深入的流程。 先做广泛分析，然后对识别的问题逐步深入。 用于代码审查、安全审计或质量分析。 SKILL.md示例： 上下文聚合 用例： 从多个来源组合信息以建立全面理解。 从不同文件和工具收集数据，综合成连贯画面。 用于项目总结、依赖分析或影响评估。 SKILL.md示例： Skills的内部架构 介绍完概览和构建流程，现在看看skills实际上如何工作。 skills系统通过元工具架构运作，一个叫 Skill 的工具充当所有单个skills的容器和调度器。 这个设计从根本上区分了skills和传统工具，无论在实现还是目的上。 Skills对象设计 传统工具像 Read 、 Bash 或 Write 执行离散动作并返回即时结果。 Skills的运作不同。 它们不是直接执行动作，而是向对话历史注入专门的指令，并动态修改Claude的执行环境。 这通过两条用户消息实现。 一条包含对用户可见的元数据，另一条包含完整skill提示词，在UI里隐藏但发送给Claude。 同时通过改变代理的上下文来改变权限、切换模型、调整思考 token参数，在skill使用期间生效。 特性 普通工具 Skill工具 本质 直接动作执行器 提示词注入+上下文修改器 消息角色 assistant → tool use user → tool result assistant → tool use Skill user → tool result user → skill提示词 ← 注入！ 复杂度 简单（3 4条消息） 复杂（5 10+条消息） 上下文 静态 动态（每轮修改） 持久性 只有工具交互 工具交互+skill提示词 Token开销 最小（约100 tokens）