Agent Skills 多平台：一次编写，处处可用的能力封装

引言：Agent 的能力，不该锁死在某个平台里

Agent 生态正在快速分化：Claude、ChatGPT、Gemini、开源框架、企业自建智能体，各有各的工具调用协议、提示词格式和运行时。结果就是——你为一个平台精心调好的“能力”，换一个平台就要重写一遍。

Agent Skills 试图解决这个问题。它的核心主张很简单：把 Agent 的能力封装成独立的、可移植的文件单元，而不是散落在提示词和代码里。写一次，多个平台都能用。

需要先说清楚：“Agent Skills”目前主要指 Anthropic 提出的 SKILL.md 规范（Claude 生态中的技能包机制），其他平台也在跟进类似概念。具体字段、加载方式、支持程度以各平台官方文档为准，本文讲的是可迁移的通用方法。

一、Agent Skills 是什么？

一句话：用文件夹封装一项能力，用元数据描述何时使用，用渐进式加载控制上下文成本。

一个标准的 Skill 就是一个目录：

skills/
└── pdf-report/
    ├── SKILL.md          # 主文件：元数据 + 指令
    ├── scripts/          # 可选：辅助脚本
    │   └── render.py
    └── references/       # 可选：参考资料
        └── format.md

SKILL.md 由两部分组成：YAML 元数据（frontmatter）+ Markdown 指令正文。

---
name: pdf-report
description: 当用户需要把结构化数据导出为 PDF 报告时使用。
---

# 生成 PDF 报告

## 步骤
1. 校验输入数据字段完整性
2. 调用 scripts/render.py 渲染
3. 输出文件路径，不要输出二进制内容

## 注意事项
- 金额一律保留两位小数
- 缺字段时先询问，不要猜测

关键点：name 和 description 是给模型看的“索引”，决定它何时加载这个 Skill；正文才是真正执行时读取的指令。

二、渐进式加载：Skills 最重要的设计

为什么 Skills 比“把所有提示词塞进系统提示”更好？因为它解决了上下文成本问题。

渐进式加载分三层：

这意味着：你有 50 个 Skill，日常只消耗 50 条描述的 token；只有真正用到某个 Skill 时，才加载它的完整内容。

这是 Skills 能规模化的根本原因。 没有渐进式加载，Skill 越多，上下文越爆。

三、多平台适配：同一份 Skill，不同加载方式

这是本文的重点。同一套 Skill 文件，如何在不同平台跑起来？

平台一：Claude 生态（原生支持）

Claude 的 Skills 机制原生读取 SKILL.md，你只需把目录放到指定位置，模型会自动索引。

平台二：Claude Code 等编码智能体

在项目根目录放置 skills/，并在 AGENTS.md 或 CLAUDE.md 中声明：

# 项目约定
- 可用 Skills 位于 ./skills/，使用前先阅读对应 SKILL.md
- 涉及 PDF 导出时，必须使用 pdf-report skill

平台三：自建 Agent（通用适配层）

如果你的平台不支持原生 Skills，就自己写一个极简加载器。代码量很少：

import os, yaml

def load_skill_index(skills_dir):
    """L1：只读取所有 Skill 的元数据"""
    index = []
    for name in os.listdir(skills_dir):
        path = os.path.join(skills_dir, name, "SKILL.md")
        if not os.path.exists(path):
            continue
        meta, _ = parse_frontmatter(path)
        index.append(meta)   # 只保留 name + description
    return index

def load_skill_body(skills_dir, skill_name):
    """L2：命中时才读取正文"""
    path = os.path.join(skills_dir, skill_name, "SKILL.md")
    _, body = parse_frontmatter(path)
    return body

调用逻辑：把 load_skill_index() 的结果注入系统提示；模型选择某个 Skill 后，再调 load_skill_body() 加载正文。核心只有两个函数，但实现了渐进式加载。

平台四：转换成其他 Agent 框架的格式

很多框架（如 OpenAI 的函数调用、LangChain 工具）要求 JSON Schema。你可以从 SKILL.md 自动生成：

def skill_to_tool_schema(meta):
    return {
        "type": "function",
        "function": {
            "name": meta["name"],
            "description": meta["description"],
            "parameters": {"type": "object", "properties": {}}
        }
    }

这样，一份 Skill 定义，既能给原生支持的平台用，也能转成其他框架的工具描述。

四、多平台落地的三个关键约束

要让 Skill 真正跨平台可用，编写时必须遵守三条纪律：

1. 元数据要自洽

description 必须回答“什么时候用”，而不是“这是什么”。模型靠它做路由决策。

• 差：description: PDF 工具
• 好：description: 当用户需要将结构化数据导出为 PDF 报告时使用

2. 正文要平台无关

不要在 SKILL.md 里写死某个平台的 API、路径或变量名。用抽象描述：

• 差：调用 Anthropic 的 files API 上传
• 好：将生成的文件保存到工作目录并返回路径

3. 脚本要显式声明依赖

scripts/ 里的脚本，必须在正文中写明运行环境和依赖，否则换平台就报错

## 环境要求
- Python 3.10+
- 依赖：reportlab==4.0.0
- 运行：python scripts/render.py --input data.json

五、典型应用场景

Skills 特别适合可复用、有明确触发条件、逻辑稳定的能力：

• 文档处理：PDF 生成、格式转换、模板填充
• 数据分析：固定口径的报表、指标计算
• 合规检查：合同条款扫描、敏感信息识别
• 代码操作：特定框架的脚手架、迁移脚本
• 业务流程：退款审批、工单分类、邮件模板

不适合：一次性任务、强依赖实时上下文的对话、需要复杂多轮协商的决策。

六、避坑指南

1. 不要把 Skill 写成提示词垃圾场：一个 Skill 只做一件事，描述清晰。
2. 不要忽略 description 的质量：它是路由的唯一依据，写不好就不会被触发。
3. 不要在 L1 放太多内容：索引层越精简，规模化越轻松。
4. 不要硬编码平台细节：否则“多平台”只是口号。
5. 不要缺少版本管理：Skill 也是代码，需要 Git、需要评审、需要回归测试。
6. 不要忘了安全：Skill 中的脚本可能被执行，必须审查权限和输入校验。
7. 不要假设所有平台行为一致：加载时机、上下文注入方式、工具调用协议都不同，需要逐平台验证。

七、演进方向：Skill 会成为 Agent 的“标准件”吗？

目前 Skills 还处在“事实标准”阶段，但它指向了一个明确趋势：Agent 能力正在从提示词工程，走向可分发、可组合、可版本化的模块化封装。

如果这个方向成立，未来可能出现：

• 技能市场：像 npm 一样安装别人写好的 Skill
• 技能组合：多个 Skill 协同完成复杂任务
• 跨平台运行时：一套 Skill 定义，自动适配不同 Agent 框架
• 评测标准：Skill 的质量、安全、性能有统一度量

谁先建立起可移植的 Skill 资产，谁就在多平台 Agent 时代占据先机。

结语

Agent Skills 的价值不在“多了一个提示词文件”，而在把能力从平台中解耦出来。用 SKILL.md 描述意图，用渐进式加载控制成本，用适配层对接不同平台——这三件事做好，你写的每一项能力，都能在多个 Agent 上复用。

模型会换，平台会更迭，但可移植的能力封装，会是穿越周期的资产。少量代码，清晰约束，多平台复用——这就是 Agent Skills 的核心方法论。