第7章三端部署 — Claude Skills 完全指南

三端速览

环境	Skill 位置	激活方式	典型用途
Claude Code	`~/.claude/skills/` 或 `.claude/skills/`	自动扫描 + 对话激活	开发、调试、个人工作流
Claude API	请求参数里 `skills` 字段,上传 zip	代码显式传入	业务集成、Agent 后端
Claude.ai	网页上传到"我的 Skill"	选中后对话激活	团队共享、非开发者使用

Claude Code 端

两级目录

~/.claude/skills/              ← 用户级(所有项目共享)
└── pdf-form-filler/
    ├── SKILL.md
    └── ...

<project>/.claude/skills/      ← 项目级(仅当前项目)
└── project-specific/
    ├── SKILL.md
    └── ...

用户级 vs 项目级

个人通用能力(PDF 处理、Markdown 工具)放用户级;项目特定的(业务 schema、部署脚本)放项目级。同名时项目级覆盖。

团队共享

项目级的 .claude/skills/ 应该提交到 Git,团队所有人拉代码就自动拿到 Skill。

命令行诊断

# 列出可用 Skills(2025 Claude Code 新增)
claude skill list

# 查看某个 Skill 详情
claude skill info pdf-form-filler

# 测试 Skill 能否被激活
claude skill test pdf-form-filler "帮我填 invoice.pdf"

显式激活

如果 description 写得不够好,Claude 没自动激活,可以在对话里显式引用:

> use pdf-form-filler skill to fill expense.pdf with data from data.json

Claude 看到 "use X skill" 就会强制读那个 SKILL.md,适合调试或用户习惯指定 Skill。

Claude API 端

请求结构(概念)

from anthropic import Anthropic

client = Anthropic()

resp = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[{"role": "user", "content": "填 expense.pdf"}],
    skills=[
        {"id": "skill_abc123"},  # 预上传的 Skill ID
        {"id": "skill_xyz789"},
    ],
    tools=[
        {"type": "bash_20250124", "name": "bash"},
        {"type": "text_editor_20250124", "name": "str_replace_editor"},
    ],
)

注意
API 的 Skills 必须配合 Bash 工具或 Text Editor 工具才有意义——因为 Skill 的脚本需要 Bash 执行,references 需要 Read 读取。单纯 Skills 不搭工具等于 Body 也读不到。

Skill 的上传

# 打包
cd ~/.claude/skills/pdf-form-filler
zip -r /tmp/pdf-form-filler.zip .

# 上传(通过 Files API 或 Skills API)
curl https://api.anthropic.com/v1/skills \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F file=@/tmp/pdf-form-filler.zip \
  -F "metadata={\"name\":\"pdf-form-filler\"}"

# 返回 skill_abc123,在 messages 调用时引用

Skill 的生命周期

上传:zip → Anthropic,获得 skill_id
测试:小流量场景跑几十条,看激活率 / 回答质量
挂 production:在正式 prompt 里带上 skill_id
迭代:改本地文件 → 重新上传 → 获得新 skill_id → A/B 测试
废弃:旧 skill_id 保留一段时间,等新老切换完成再删

Claude.ai 网页端

面向非开发者:产品经理、设计师、法务。他们不写代码,但可以用你预制的 Skill。

访问 claude.ai/skills(或个人工作区的"Skill"入口)
点"Upload Skill",上传 zip
在对话框里,点右下角"Skills"图标,勾选要用的 Skill
正常对话,Claude 会按 description 激活

团队工作区
Claude for Team / Enterprise 有"组织级 Skill 库",管理员上传后,全组织可见可用。结合权限管控,等于一个私有 Skill Marketplace。

跨端兼容性:一份代码的注意事项

路径

SKILL.md 里写 相对路径:scripts/fill.py。不要写 ~/.claude/skills/... 绝对路径——API 沙箱和 Claude.ai 环境下没有这路径。

依赖安装

Claude Code 可以 pip install 到用户环境;API 沙箱每次冷启动,依赖要轻量;Claude.ai 依赖环境受限。跨端首选:用标准库能实现就用标准库。

环境变量

Claude Code 读本机 ~/.env,API 调用时环境变量在服务端,Claude.ai 通常无法设置。把 API key 类参数通过对话传入,别依赖 env。

文件系统

API Bash 有独立沙箱目录 /workspace;Claude Code 在用户当前目录;Claude.ai 附件上传后可访问。SKILL.md 说明"请先提供文件路径"统一三端。

差异化配置

有时一个 Skill 在不同端需要微调——比如 Claude Code 可以本地运行 ffmpeg,API 沙箱可能没装。用条件块或多入口:

方法 1: 在 SKILL.md 里显式说明

## 环境适配

- Claude Code / Desktop:默认使用 `scripts/local_ffmpeg.sh`
- API 沙箱:`ffmpeg` 不可用,改用 `scripts/remote_transcode.py` 调云端服务

方法 2: 按端准备不同的 Skill

一份本地版 skill,一份 API 版 skill,共享同一个 references/,脚本不同。

media-tools-local/   ← Claude Code 用
media-tools-cloud/   ← API 用
shared-references/   ← git submodule 或 symlink

部署流水线

┌─── developer 编辑 SKILL.md + scripts ────┐ │ │ ▼ │ git commit │ │ │ ▼ │ GitHub Actions │ ├─ lint SKILL.md (yaml 校验, description 长度) │ ├─ test: 跑 eval 场景集 │ ├─ build: zip 打包 │ └─ deploy: │ ├─ upload to Claude API → skill_id │ ├─ sync to organization (Claude.ai) │ └─ tag release → 同步到用户 Claude Code │ │ ───────────────────────────────────────────────────┘

本章小结

    Claude Code:~/.claude/skills/(用户)与 .claude/skills/(项目),自动扫描
Claude API:上传 zip → skill_id,在 messages.create 带 skills + bash/editor tool
Claude.ai:网页上传,团队共享,非开发者也能用
跨端兼容:相对路径、轻量依赖、不依赖 env,用 SKILL.md 说明路径约定
成熟 Skill 进 CI/CD:lint + eval + 打包 + 三端分发

  

Skill 在 Claude Code / API / App 三端

三端速览

Claude Code 端

两级目录

命令行诊断

显式激活

Claude API 端

请求结构(概念)

Skill 的上传

Skill 的生命周期

Claude.ai 网页端

跨端兼容性:一份代码的注意事项

差异化配置

方法 1: 在 SKILL.md 里显式说明

方法 2: 按端准备不同的 Skill

部署流水线

本章小结