Skills

Skills 与工具的区别

有必要弄清楚二者的区别，因为它们解决的是不同的问题：

• 工具（Tools） 将 Claude 连接到数据和操作。"查找这段代码"、"发送这封邮件"——Claude 调用工具，由其他东西来执行。
• Skills 教会 Claude 一套流程。"按照这个模板生成每日状态报告"——这是一份 Claude 阅读并遵循的操作手册，有时这也意味着它会自己运行打包好的脚本。

一个简单的记忆方法：工具关乎 Claude 能做什么，而 Skills 关乎您希望它怎么做。



还有一点值得了解：Skills 在启动时不会完全加载到上下文中。一开始只会加载名称和描述。当您的智能体判断某个 Skill 相关时，才会将完整的 Skill 加载到上下文中。这样即使有许多 Skills 可用，也能保持您的上下文精简。

上传一个 Skill

Skills 只需上传到您的工作区一次，之后通过 ID 引用即可。您可以直接在 Claude Platform 上上传，也可以通过编程方式完成：

skill = client.skills.create(
    display_name="Status Report Generator",
    files=files_from_dir("status-report-skill"),  # folder containing SKILL.md
)

print(skill.id)  # reference this ID in future requests

在这个示例中，我想要一个状态报告生成器。所有关于什么是好的状态报告的规则——章节、语气、如何总结、如何处理阻塞项——都预先打包在一个 Skill 中。活动日志本身只是在请求时传入的一个字符串。

将 Skill 附加到请求中

Skills 通过容器配置附加到请求中——容器内有一个 skills 数组，其中每个条目指定一个 skill_id 和 version。以下是状态报告生成器的完整调用：

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": skill.id,
                "version": "latest",
            }
        ]
    },
    tools=[
        {
            "type": "code_execution_20250825",
            "name": "code_execution",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": f"Generate the daily status report from this activity log:\n\n{activity_log}",
        }
    ],
)

有几点值得指出：

• 我们调用的是标准的 client.messages.create，不带任何 beta 头。Skills 现已在 Claude API 上正式发布（generally available），因此不再需要 skills-2025-10-02 beta 头；仍然发送该头的请求会继续正常工作。
• container.skills 是 Skill 附加的位置。它是一个列表，因此您可以在一次调用中叠加多个 Skills。
• 这里还启用了代码执行（Code execution）。这是必需的：在 API 上，Skills 运行在代码执行工具的容器内，这正是让 Skill 流程能够完成实际工作的原因——比如在终端中运行脚本。

运行它

输出结果是一份完全按照 Skill 所规定的格式生成的状态报告。章节、语气、阻塞项处理——所有这些都来自您上传的 SKILL.md 文件。用户提示只有一行；而流程则存在于 Skill 中。



在生产应用中，这正是团队在整个功能范围内统一输出的方式。借助这个每日状态报告端点，每位产品经理都能获得相同的结构、相同的语气、相同的章节，并按相同的顺序排列——而无需任何人把模板复制粘贴到提示中。



回顾

• Skills 打包您的流程。 一个 SKILL.md 文件（加上任何脚本和资源）教会 Claude 您希望某件事如何完成。
• 工具与 Skills 的区别： 工具关乎 Claude 能做什么；Skills 关乎您希望它怎么做。
• Skills 是渐进式加载的。 启动时只加载名称和描述；当智能体决定使用它时，完整的 Skill 才会加载到上下文中。
• 上传一次，使用 client.skills.create，然后在任何 messages.create 调用中通过 container.skills 附加——它是一个列表，因此您可以叠加多个 Skills。
• 当 Skill 的流程需要完成实际工作时，搭配代码执行使用。
• 当怎么做与做什么同样重要时，请选用 Skill。