Skill with the Claude API

本节课我们将脱离 Claude AI 网页界面和桌面端 (Claude Desktop)，深入讲解如何通过 Claude Messages API 以编程方式调用技能 (Skills)，并掌握代码执行工具 (Code Execution Tool) 与 文件API (Files API) 的协同工作机制。

我们将重点解决 API 环境与桌面环境的核心差异：在 Claude AI 中开箱即用的文件操作能力，在 API 中需要通过手动配置沙箱环境（Sandbox Environment）来实现。

API vs. Desktop桌面环境

在使用 Claude API 调用技能前，必须理解两种运行环境的本质区别：

维度	Claude AI / Claude Desktop	Claude Messages API
执行环境	托管的虚拟机 (Managed VM)	需手动配置的沙箱容器 (Sandbox Container)
文件系统	开箱即用的文件读写	通过文件API (Files API) 显式上传/下载
网络访问	可访问互联网 (Internet-enabled)	无互联网连接 (Air-gapped)
代码执行	自动启用	需显式集成代码执行工具 (Code Execution Tool)
技能共享	云端同步	不共享 (需手动迁移)

关键区别：在桌面端，"代码执行与文件创建"是默认启用的系统设置；而在 API 环境中，开发者必须手动构建等效的能力栈，通过工具 (Tools) 与 API 接口的组合来实现。

核心工具链：沙箱环境的构建 (The Sandbox Stack)

要在 API 环境中使用技能，必须配置以下两个核心组件：

1. 代码执行工具 (Code Execution Tool)

该工具赋予 Claude 在隔离容器中运行 Bash/Shell 命令 的能力，支持：

创建、查看、编辑文件 (File CRUD operations)
执行代码与脚本 (Code execution)
访问受限的计算资源 (CPU/Memory/Disk limits)

技术限制 (Constraints)：

无网络访问：容器处于隔离网络环境，无法下载外部包（与桌面端有本质区别）
预装库限制：仅包含开箱即用的标准库，复杂依赖需预先打包
资源配额：受限于内存、磁盘和 CPU 配额

⚠️ 安全警告：这种沙箱设计虽限制了灵活性，但提供了确定性执行环境 (Deterministic Environment)，适用于企业级应用的安全合规要求。

2. 文件API (Files API)

文件API 提供与沙箱容器之间的文件传输层 (File Transport Layer)，实现：

上传 (Upload)：将本地文件传入沙箱供技能处理
下载 (Download)：将沙箱生成的文件（如报告、数据、代码）传回本地
标识管理：通过文件 ID (File ID) 在对话中引用特定文件

💡 实践经验：文件API 的强制接口设计看似繁琐，实则提供了可追溯性 (Traceability) 和访问控制 (Access Control)，比直接文件系统访问更适合生产环境的审计需求。

技能目录结构 (Skills Directory Structure)

在 API 环境中，技能以标准化目录结构 (Standardized Directory Structure) 存储于沙箱内：

sandbox/
└── skills/
    ├── skill-a/
    │   ├── 🌟 SKILL.md  # 核心技能入口文件 (Critical Skill Entry Point)
    │   └── ...          # skill-a 的附属资源
    ├── skill-b/
    │   ├── 🌟 SKILL.md  # skill-b 的核心入口文件
    │   └── data.txt     # 示例：其他支持文件
    └── ...

每个技能都拥有一个独立的目录，其中最重要的文件是 SKILL.md。

工作流程 (Workflow)：

通过文件API 将技能文件上传至沙箱的 skills/ 目录
代码执行工具读取 SKILL.md 解析指令
Claude 根据技能定义执行相应操作
生成的文件通过文件API 返回

🔍 深度观察：技能本质上是一种插件系统 ( Plugin System )，类似于 VS Code 扩展或 WordPress 插件。理解这一点有助于构建可复用的自动化工作流 (Automation Workflows)。

实施路径(Implementation Path)

从配置到调用

阶段 1：环境配置

启用代码执行工具 (Code Execution Tool)
配置文件API 的上传/下载端点
将技能文件批量上传至沙箱目录

阶段 2：技能调用

使用 Messages API 发送包含技能指令的请求
Claude 在沙箱中执行技能定义的代码逻辑
通过文件API 获取生成的文档、数据报告或代码文件阶段 3：结果交付
下载沙箱输出的文件（如练习题、时间序列分析报告）
清理临时文件或保留至下次会话

最佳实践与迁移策略 (Best Practices)

技能可移植性 (Skill Portability)

由于技能在 Claude AI / Claude Desktop 与 Claude API / Claude Code 之间不共享 (Not Shared)，建议采用以下策略：

策略	实施方法	优势
版本控制	将技能文件存放于 Git 仓库	跨环境一致性 (Consistency)
自动化部署	编写技能启动脚本 (Setup Scripts)	快速环境重建
文档化	为每个技能编写 README.md	降低迁移成本

应对网络限制 (Handling Air-gapped Constraints)

针对 API 沙箱的无互联网 (No Internet) 限制：

预下载依赖：在容器外下载所需包，通过文件API 传入
离线数据集：将常用数据集预先打包为技能资源
混合架构：结合外部 API 与沙箱内计算，通过文件API 传递中间结果

在进入下一章节内容之前，建议完成：

导出 Claude Desktop 中创建的现有技能
通过 API 调用简单技能（如生成练习题），熟悉 代码执行工具 + 文件API 的协作流程
识别日常工作中的可自动化任务 (Automatable Tasks)，设计对应的技能工作流

【教程地址】https://github.com/datawhalechina/agent-skills-with-anthropic

【课程列表链接】https://www.datawhale.cn/activityGroup/16?sourceId=1809

【视频教程地址】吴恩达 DeepLearning.AI - agent-skills-with-anthropic

【官网解读教程】sc-agent-skills-files

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

防止Agent胡来五大安全防线

防止 Agent 调用外部工具时“胡来”，不能仅依赖模型自身的指令遵循能力，必须构建**“架构隔离 + 代码校验 + 流程审批 + 全程审计”**的综合防御体系。通过本地化部署大模型减少数据外泄风险，并结合特定业务的风险预警模块，可显著提升系统的可控性与安全性。最终目标是实现效率与安全的平衡，确保智能体在既定规则范围内可靠运行。