第七章：基于 Claude API 开发技能(Skill with Claude API)
53%
47%
换个视角看这一节：如果说前面六节是在讲“技能是什么”和“技能怎么做”，那么第七章就是“把技能搬到不同平台上去跑”。
这一节的核心叙事是：你先在Claude Desktop里做好了两个技能，跑得很顺。现在你要把它们放到API里跑，那就不能指望环境自动帮你配好。你得手动把“代码执行沙箱”和“文件读写通道”这两个基础设施建起来，然后把技能文件放进去。
第一步：跨平台交通图——同一个技能，三种跑法
Skills是开放标准，可以在多个平台上无缝运行。但不同平台的运行环境差异很大：
#rvkUBKWQlAKw text { white-space: pre; }#rvkUBKWQlAKw .fb0 { stroke: var(--N900-FG, 0.15); }#rvkUBKWQlAKw .fb0 {stroke: rgba(31,35,41, 0.15)}#rvkUBKWQlAKw .fx0 { stroke-miterlimit: 10; }#rvkUBKWQlAKw .fx0 {stroke-miterlimit: 10}#rvkUBKWQlAKw .fa1 { fill: rgb(187, 191, 196); }#rvkUBKWQlAKw .fa1 {fill: rgb(187, 191, 196)}#rvkUBKWQlAKw .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#rvkUBKWQlAKw .fx1 {font-style: normal}#rvkUBKWQlAKw .fx2 { text-anchor: middle; }#rvkUBKWQlAKw .fx2 {text-anchor: middle}#rvkUBKWQlAKw .fx3 { dominant-baseline: central; }#rvkUBKWQlAKw .fx3 {dominant-baseline: central}#rvkUBKWQlAKw .fx4 { stroke: none; }#rvkUBKWQlAKw .fx4 {stroke: none}#rvkUBKWQlAKw .fc0 { fill: var(--text-caption); }#rvkUBKWQlAKw .fc0 {fill: #646a73}#rvkUBKWQlAKw .fa2 { fill: var(--text-link-disabled); }#rvkUBKWQlAKw .fa2 {fill: rgb(187, 191, 196)}#rvkUBKWQlAKw .fa3 { fill: rgb(222, 224, 227); }#rvkUBKWQlAKw .fa3 {fill: rgb(222, 224, 227)}#rvkUBKWQlAKw .fa4 { fill: rgb(225, 234, 255); }#rvkUBKWQlAKw .fa4 {fill: rgb(225, 234, 255)}#rvkUBKWQlAKw .fc1 { stroke: var(--B500); }#rvkUBKWQlAKw .fc1 {stroke: #336df4}#rvkUBKWQlAKw .fx5 { font: 400 16px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#rvkUBKWQlAKw .fx5 {font-style: normal}#rvkUBKWQlAKw .fx6 { text-anchor: start; }#rvkUBKWQlAKw .fx6 {text-anchor: start}#rvkUBKWQlAKw .fx7 { dominant-baseline: alphabetic; }#rvkUBKWQlAKw .fx7 {dominant-baseline: alphabetic}#rvkUBKWQlAKw .fc2 { fill: rgb(0, 0, 0); }#rvkUBKWQlAKw .fc2 {fill: rgb(0, 0, 0)}#rvkUBKWQlAKw .fx8 { font: 400 15px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#rvkUBKWQlAKw .fx8 {font-style: normal}#rvkUBKWQlAKw .fc3 { fill: var(--B500); }#rvkUBKWQlAKw .fc3 {fill: #336df4}#rvkUBKWQlAKw .fx9 { font: 400 13px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#rvkUBKWQlAKw .fx9 {font-style: normal}#rvkUBKWQlAKw .fb1 { fill: var(--N900-FG, 0.15); }#rvkUBKWQlAKw .fb1 {fill: rgba(31,35,41, 0.15)}#rvkUBKWQlAKw .fb2 { fill: rgba(255, 255, 255, 0.16); }#rvkUBKWQlAKw .fb2 {fill: rgba(255, 255, 255, 0.16)}#rvkUBKWQlAKw .fb3 { fill: rgba(255, 255, 255, 0.12); }#rvkUBKWQlAKw .fb3 {fill: rgba(255, 255, 255, 0.12)}#rvkUBKWQlAKw .fa5 { fill: var(--bg-body); }#rvkUBKWQlAKw .fa5 {fill: #fff}ABCDE1234平台Claude CodeClaude API / Messages API部署形态全托管Web/桌面应用终端优先的CLI工具可编程接口服务需要手动配置吗？❌ 开箱即用⚙️ 少量配置✅ 大量手动配置适用场景日常使用、技能原型验证开发工作流、代码库操作生产级服务、自动化流程与技能库关系技能可创建、编辑、使用技能安装在或项目目录下需自行管理技能文件、调度逻辑Claude.ai / Claude Desktop~/.claude/skills/
💡 核心洞察：三种模式共享同一套“渐进式披露”机制和技能文件格式，但在并发隔离、认证体系、环境搭建成本上走向三岔口——选错模式的代价不是功能缺失，而是整个交付链路从自动化根基上被架空。
第二步：一个容易被忽略但很重要的提醒
在手动搭建之前，必须清楚一个限制：
在Claude AI或Claude Desktop中创建/上传的技能，不会自动同步到Claude API或Claude Code。
🌐
也就是说，你在Claude Desktop里做好了time-series-analyzer技能，在API里想用它，需要把文件夹复制到API的访问路径下，并且配置好环境才能调用。这个限制对于理解跨平台工作流很重要：技能文件是可移植的，但不同环境之间不会自动共享技能库。
第三步：API部署前的准备工作——你需要手动搭建的三个核心件
课程的核心信息是：在Claude API中使用Skills，环境默认是“空”的，需要你主动去构建以下三个能力。
组件一：代码执行沙箱（Code Execution Sandbox）
它是什么：一个独立的、隔离的容器化运行环境。当Claude需要运行Python脚本、执行Bash命令或读写文件时，所有操作都在这个沙箱里发生，不会影响外部系统。
为什么需要它：Claude API本身不配备执行代码的能力——它只是一个对话接口。要让Claude运行SKILL.md里引用的scripts/脚本，必须给它一个“可以动手的地方”。
组件二：文件系统访问通道（Files API / File System）
它是什么：让Claude能够读取技能文件夹中的SKILL.md、scripts/、references/等文件，并能将生成的结果（PPT、PDF、数据报告）写回文件系统并下载。
为什么需要它：Skills本身就是文件系统上的一组文件夹。没有文件系统访问权限，Claude根本看不到这些技能。
组件三：技能发现与加载机制
它是什么：当Claude收到用户指令时，需要能够扫描可用的技能列表，根据description字段匹配相关技能，并按需加载SKILL.md的完整内容。
在API中如何实现：需要在Messages API请求中添加container.skills配置，并在请求中携带anthropic-beta: skills-2025-10-02标头。流程参考：
text
🔁 第四步：完整的数据流——从指令到结果
为了更直观地理解各组件如何协同，下图是API模式下Skills的完整执行链路：
代码块
Plain Text
┌─────────────────────────────────────────────────────────────────────────────┐│ API部署架构全景图 │├─────────────────────────────────────────────────────────────────────────────┤│ ││ 【用户】 → 发起请求（携带container.skills + 启用代码执行工具） ││ ││ 【Messages API】 → 解析请求，识别技能列表 ││ ││ 【第1层：元数据扫描】 → 技能目录扫描，仅读name+description ││ 加载元数据（~30-50 token/技能） ││ ││ 【第2层：匹配判断】 → Agent判断当前任务匹配哪些技能 ││ 按需激活对应技能的完整SKILL.md ││ ││ 【第3层：脚本执行】 → 调用代码执行工具，在沙箱环境中运行scripts/中的脚本 ││ ││ 【Files API】 → 读写文件系统，获取/存储技能所需的数据和产出 ││ ││ 【返回结果】 → 将执行结果返回给用户 ││ │└─────────────────────────────────────────────────────────────────────────────┘
📊 第五步：API模式 vs 桌面模式——一张表看懂差异
表格加载中...
🛠️ 第六步：动手检查清单——API跑技能前，请确认这五项
这既是课程脉络的总结，也是你准备上手时的实操指南。
•
技能文件夹是否已在API可访问的路径下？ 技能不自动同步，需要手动放置。
•
代码执行工具是否已启用？ 在请求中启用代码执行工具（目前处于beta阶段），并确认沙箱配额满足脚本运行需求。
•
文件系统访问是否已配置？ 通过Files API（或自行实现的文件访问逻辑）打通读写通道。
•
请求中是否包含container.skills列表和正确的beta版本标头？ 技能元数据扫描需要这两项配置。
•
脚本是否依赖特定的Python包或环境变量？ 如有依赖，需确保沙箱预装了这些依赖，或将依赖声明写入references/供Claude参考。
“Claude.ai是傻瓜相机，开箱即拍；Claude API是单反，机身在手、镜头和环境都要自己配。”
理解了这个类比，你就理解了为什么第七节花了大篇幅讲解代码执行工具、文件API和沙箱——不是在讲枯燥的配置，而是在教你如何为Skills搭建一个可以跑起来的舞台。而一旦舞台搭好，同一个技能文件夹就能在API中稳定运行，为生产级应用提供自动化能力。
🎯 第七节一句话收尾
📖 补充：平台独立性与开放标准
Skills的跨平台能力已经获得了更广泛的生态支持。Anthropic已将Skills作为开放标准发布，“像MCP一样，我们相信Skills应该跨工具和平台移植——无论你使用Claude还是其他AI平台，同一个技能都应该正常工作”。除Claude系产品外，OpenAI Codex、Cursor、Gemini CLI、VS Code等主流AI工具也已完成了兼容，任何一个支持Agent Skills标准的平台都可以直接加载和运行你在本课中创建的技能文件夹。