部署模式的选择决定了 Skills 的服务形态

结论先行：在 Claude Skills 生态中，部署模式即服务形态。CLI 模式把 Skill 变成开发者的私有工具箱，API 模式将它推上生产级服务的轨道，Web 模式则让它隐身于产品界面之后。三种模式共享同一套“渐进式披露”机制，却在并发隔离、认证体系、用户触达和上下文管理上走向了三岔口——选错模式的代价不是功能缺失，而是整个交付链路从自动化根基上被架空。

1. 现象：一条指令，三种交付

2025 年末至 2026 年初，Anthropic 在 Claude.ai、Claude Code 和 API 三端同步开放了 Skills 能力。与此同时，OpenAI Codex 的 Agent Skills 也走上类似的 CLI + API 路线，Cursor 等编辑器甚至将 Skills 与 Rules、MCP 并列作为核心扩展入口。开发者很快发现，同一个“ PDF 分析 Skill”可以被安装到终端，被封装成 REST 端点，也可以嵌入团队知识库的搜索框——但三者的实现代价和适用场景截然不同。

这条分岔路的核心原因在于：Skills 本身只是文件夹（包含 SKILL.md、脚本、资源），它的“服务形态”完全由运行时环境定义。你的部署选择，实际上是在为 Skill 决定：

• 它是随用随取的本地命令行工具，还是需要承载 500 人并发的后端服务？
• 调用者是一个开发者，还是一个没有任何技术背景的运营人员？
• 上下文拥塞时，谁来决定激活哪个 Skill，又由谁承担上下文预算的超支？

理解了这三个问题，选型才不是拍脑袋。

2. 核心维度分析：三种模式的岔路口

下面这张表将三种模式放入四个致命维度中解剖。每一个维度的结论都来自当前调研资料中可验证的架构约束，而非直觉推导。

2.1 共通的基石：渐进式披露

无论选择哪种形态，Skills 都共享一套一致的上下文管理机制，这要归功于 Claude Skills 定义中的渐进式披露：

• 第一阶段（扫描）：系统只读取每个 Skill 的元数据（名称、描述、触发条件），大约消耗 100 tokens。
• 第二阶段（激活）：只有匹配当前任务的 Skill 才会被完整加载（指令部分控制在 5k tokens 以内）。
• 第三阶段（按需加载）：Skill 包含的脚本、参考文档等资源，仅在 AI 推理过程中实际调用时才注入上下文。

这个设计让同时挂载数十个 Skill 而不撑爆上下文窗口成为可能。但不同模式在“谁来执行扫描和匹配”这一点上出现了分化，这正是选型的本质。

3. 模式一：CLI 部署——开发者的首选与限制

# 从市场安装官方技能
/plugin marketplace add anthropics/skills

# 从本地文件夹直接加载技能
/plugin add /home/alice/skills/pdf-analyzer

CLI 模式是三种形态里上手成本最低、反馈循环最快的选项。你在终端里敲两条命令，Skill 就成为当前会话的一部分，Claude Code 引擎会自动完成元数据扫描和按需激活，开发者根本不需要关心上下文预算——这正是它能迅速在自动化流水线和开发者个人工具箱中站稳脚跟的原因。

使用场景缩影：

• CI/CD 中自动生成变更日志：在 GitHub Actions 里调用 claude 命令，挂载一个“changelog-writer” Skill，根据 commit 历史生成 release notes。
• 本地代码审查辅助：/plugin install 一个“code-review” Skill，每次 git diff 后自动触发安全检查建议。
• 数据库迁移脚本生成：DBA 装上“schema-migration” Skill，对话式生成 SQL 脚本。

致命限制：

1. 无并发与用户隔离。CLI 的进程天然绑定当前用户，当团队中有 20 个开发都想同时使用同一个 Skill 时，只能各自安装自己的副本——没有状态共享，也没有调用配额控制。如果 Skill 依赖一个本地端口或临时文件，并发冲突几乎是必然。
2. 无法直接触达非技术用户。你不可能让运营团队去终端里敲 /plugin add。
3. 技能发现全凭自觉。CLI 不会帮你推送可用的 Skills 列表，新成员加入团队时往往需要一份“技能清单”文档。

一句话取舍：CLI 模式是个人/小团队和自动化流水线的黄金搭档，但一旦服务对象变成一群人或一个产品界面，它的局限性就会立刻暴露。

4. 模式二：REST API 服务化——生产级集成的唯一正道

import anthropic
import fastapi
from pydantic import BaseModel

# 简化示例：将 Skill 封装为 API
app = fastapi.FastAPI()

class SkillRequest(BaseModel):
    prompt: str
    user_id: str

# 生产环境中需要自行实现元数据扫描与匹配调度
# 此处仅展示 API 包装骨架
@app.post("/skills/pdf-analyzer")
async def run_pdf_skill(req: SkillRequest):
    client = anthropic.Client()
    message = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        system="你是一个 PDF 分析专家...", # 这里注入 SKILL.md 指令
        messages=[{"role": "user", "content": req.prompt}]
    )
    return {"result": message.content}

当 Skill 需要被一个 Web 产品、移动 App 或第三方系统调用时，CLI 必然要让位于 REST API。Anthropic 已经提供了 /v1/skills 端点，但如果你想把 Skills 完全融入自己的认证体系、计费逻辑和多租户架构，通常需要在 API 外层套一层自己开发的后端服务。

API 化带来的根本变化：

• 多租户并发：可以加入请求队列、Worker 池和限流策略，支撑数百人同时调用同一个 Skill。
• 认证与授权：接入 OAuth2、API Key 验证，实现不同用户调用配额与数据隔离。
• 监控与计费：每次调用生成日志，结合平台统计，形成可量化的成本模型。
• 技能组合调度：你可以在服务端根据用户意图动态选择激活哪个 Skill，甚至组合多个 Skill 完成复杂任务。

不得不提的开发负担：

1. 技能发现与激活逻辑需自建。CLI 模式内置的扫描-匹配机制在 API 模式下消失，开发者必须自己实现“接收请求 → 扫描可用 Skill 元数据 → 匹配意图 → 加载完整指令 → 调用大模型”的完整链路。如果实现粗糙，要么漏掉合适的 Skill，要么每次都把全量 Skill 指令塞进系统提示词，瞬间耗尽上下文窗口。
2. 运维复杂度直线上升。你需要管理服务实例的健康、Skills 文件的版本同步、上下文预算的全局监控——这些在 CLI 模式下完全不需要考虑。

一句话取舍：REST API 是将 Skill 变成可售卖、可运营的产品的唯一路径，但它要求团队具备后端工程和 SRE 能力，不适合快速试错。

5. 模式三：Web 集成与 iFrame 嵌入——让 Skill 隐身于产品

┌─────────────────────────────┐
│     你的 Web 应用界面       │
│  ┌───────────────────────┐  │
│  │  <iframe>             │  │
│  │  技能调用输入框        │  │
│  │  结果展示区            │  │
│  │  </iframe>            │  │
│  └───────────────────────┘  │
│  通过 postMessage 传递参数   │
└─────────────────────────────┘

对于已经拥有成熟 Web 产品的团队，最优雅的交付方式不是让用户离开产品界面，而是将 Skill 能力直接嵌入现有页面。iFrame 是当前最轻量的实现方式，后端通过 API 为 Skill 提供服务能力，前端以浮层或侧边栏的形式渲染一个“智能功能卡片”。

这种模式的核心价值在于无感调用：用户不需要知道背后有 AI Agent 在工作，他们只是在表单旁多了一个“自动生成报告”按钮，点一下就能得到结果。

Web 集成的关键考量：

• UI 隔离：iFrame 天然提供样式和 JavaScript 隔离，技能内部的交互不会污染宿主页面。
• 认证穿透：需要通过 postMessage 或服务端代理把宿主产品的登录态传递到 Skill API，而不能在 iFrame 里重新拉起一套登录流程。
• 上下文数据传递：宿主页面抓取的数据（例如表格内容、选中的文本片段）通过消息管道传给 Skill，结果再回传渲染——这一过程必须做好域名校验，防止 XSS 攻击。

比起直接暴露 API 的优势：

你在 API 层做好权限控制后，Web 集成让 Skill 的最终消费者完全无需学习命令行，也无需在 Postman 里构造请求。对于企业内部的审批流、客服知识库辅助、工单自动分类等场景，Web 嵌入几乎是不二之选。

一句话取舍：Web 集成是降低用户门槛的终极武器，但它依赖于一个健壮的 API 后端，且前端交互的打磨成本不可低估。

6. 选型建议：五个场景，五种选型图

没有“最好”的模式，只有当前组织能力和产品阶段下的最优解。下面的建议表基于当前调研中社区广泛认同的实践整理而成，可以当作选型时的清单直接使用。

7. 从部署到分发：选型决定了生态的起点

部署模式的选择，表面上是一个技术决策，实质上它是一个“用户触达半径”的选择。CLI 模式圈定了开发者群体，API 模式打开了机器与机器之间的集成网络，Web 模式则把 Skill 推向最后一个非技术用户。

但这一切又引出一个新的问题：当你按场景生产出十几个 Skills 后，如何让团队发现、安装、更新这些 Skills？如何确保“代码审查 Skill”的 1.1 版不会与同事的 0.9 版打架？这就是建立内部 Skill 市场的必要性所在。

下一章《构建 Skills 市场是推广与分发的核心策略》将参考 LobeHub 等社区实践，带你搭建一个版本化、可依赖管理的内部注册中心——让部署模式所触达的每一个用户，都能在正确的时间用上正确的 Skill 版本。