如何编写和部署Agent SKill？

Agent Skills（智能体技能）是一组文件夹，里面包含指令、脚本和资源。当大型语言模型（LLM）判断任务相关时，可以加载这些内容，以一致、可重复的方式完成特定任务。这一开放框架由 Claude 于 2025 年首次提出。此后，越来越多的组织和 Agent 开发者开始采用该框架。

在过去，当你给 LLM 分配任务时，必须在每一次提示词中手动提供完整上下文。而使用 Agent Skills 后，你可以将资源和补充指令拆分成独立文件夹。只有当 LLM 判断确实需要时，才会访问这些内容。

例如，如果你希望 LLM 能生成 PowerPoint 演示文稿。相比每次都在提示词中加入公司的样式规范、图片素材和模板，你可以把这些内容统一放进一个 Skill 文件夹中。之后，每次生成演示文稿时，LLM 都能自动查找并使用这些资源。你可以创建大量 Skills。LLM 可以像使用工具一样引用它们。

在本教程中，你将创建一个用于PDF 解析的 Agent Skill。同时，你还可以为其添加可选文件夹，用于存放参考文档和素材资源。

第一步 —— 创建 Skill

最简单的 Skill 实现方式，是创建一个包含SKILL.md文件的文件夹。

该 Markdown 文件用于描述元数据和指令，告诉 Agent 如何完成特定任务。

你也可以在文件夹中加入：

• 资源文件
• 模板
• 脚本
• 参考文档

文件夹结构

your-skill-name/├──SKILL.md#必需：指令+元数据├──scripts/#可选：可执行代码├──references/#可选：文档└──assets/#可选：模板、资源

Skill 文件夹的名称，就是 Skill 的名称。文件夹中必须包含 SKILL.md 文件，其余内容可按需添加。

首先，创建一个名为 skills 的文件夹。该文件夹将存放你编写的所有 Skills。

在其中创建一个名为 pdf-parsing 的文件夹。该文件夹用于存放 PDF 解析相关的全部文件。

在 pdf-parsing 文件夹中，新建一个 SKILL.md 文件，内容如下：

---name: pdf-processingdescription: Extracts textfromPDF filesusingPyPDF2.---
# PDF Processing Skill
## When to use this skillUsethisskillwhena user needs to extract textfroma PDFfile.
## How to Use this SkillThis skill provides the `extract_text()` functionfromthe `parse_pdf.py` script. Import itintoyour agent script:
pythonfromskills.pdf_parsing.parse_pdf import extract_text
result = extract_text(  file_path="/path/to/document.pdf",  pages="all"# or "1-3" or "1,2,3")
### Parameters- `file_path` (str): Path to the PDFfile- `pages` (str): Pages to extract -"all","1-3"(range),or"1,2,3"(specific pages)
### ReturnsJSONobjectwith:- `success` (bool): Whether extraction succeeded- `file_path` (str): Path to the processedfile- `total_pages` (int): Total pagesinPDF- `extracted_pages` (int): Number of pages extracted- `pages` (list): Array of {page: number, text:string} objects
Alternatively, you can call the script directlyfromthe command line:commandpython skills/pdf-parsing/parse_pdf.py extract_text --file_path /path/to/file.pdf --pages all

关于 Frontmatter

在 Markdown 文件顶部的 Frontmatter 中：

• name 和 description 是必需字段
• Agent 会解析这些字段，用于判断哪个 Skill 最适合当前请求

你还可以添加可选字段，例如：

• license
• compatibility
• metadata
• allowed-tools

在自定义 Agent 工作流中，你可以自由扩展这些字段。

Agent 会将所有 Skill 的 Frontmatter 与用户请求一起进行匹配，以确定最合适的 Skill。

编写解析脚本

接下来，你可以：

• 使用已有的免费 PDF 解析脚本
• 或自行创建 parse_pdf.py 文件，并实现 extract_text() 函数

如果使用示例脚本，需要安装 PyPDF2：

pip3installPyPDF2

这将安装 PyPDF2 Python 包。

第二步 —— 集成 Skill

要让 Agent 使用 Skills，需要完成以下流程：

1. 扫描所有包含SKILL.md的目录
2. 在启动时加载每个 Skill 的元数据（名称与描述）
3. 将用户请求与可用 Skills 进行匹配
4. 激活 Skill，加载完整指令内容
5. 根据指令执行脚本或加载资源

一些 Agent（如 Claude Code、Codex）已经自动支持该流程。越来越多的 Agent 平台正在集成这一标准。

如果你想将你的 Skill 集成到自己定制的智能体（agent）中，主要有两种方式：一种是基于文件系统的模式，另一种是基于工具的模式。

在基于文件系统的模式中，大语言模型（LLM）的工作流运行在一个计算机环境中，并输出诸如 cat /path/to/my-skill/skill.md 这样的 shell 命令，随后这些命令会被执行。

而在基于工具的方法中，Skill 会被封装成 LLM 可以直接调用的工具。

本教程不涉及从零开始构建一个支持 SKill 的智能体，但你可以使用我们提供的这个智能体脚本。该脚本通过 DigitalOcean Gradient AI 平台的无服务器推理（Serverless Inference）功能调用 Llama 3.3 70B 模型。你需要先获取一个模型访问密钥，才能在 DigitalOcean Gradient AI 平台上使用无服务器推理服务。请将你的模型访问密钥添加到脚本的 main() 函数中。

在这里我们简单先介绍一下DigitalOcean Gradient AI平台的无服务推理。

DigitalOcean Gradient AI 平台的无服务器推理（Serverless Inference）是一种让开发者无需管理任何底层基础设施，就能调用强大 AI 模型进行推理计算的服务。这种模式通过简洁的 API 让你直接访问包括开源模型和主流大模型提供者的能力，无需自行部署或维护服务器集群。它由 DigitalOcean 平台自动处理扩容、可用性和资源调度等复杂工作，使开发者可以集中精力构建应用逻辑，而不必担心底层算力的管理和运维。

无服务器推理采用按使用量计费模式，即按输入和输出的 Token 数量收费，没有闲置服务器的成本，这对于请求量波动较大的场景尤为经济。开发者通过申请和配置一个模型访问密钥（Model Access Key），即可通过统一的端点发起 HTTP 请求来调用模型进行文本生成、对话、分析等推理任务。

与传统需要预先部署、调整和监控基础设施的推理服务相比，Serverless Inference 的优势在于开箱即用、自动扩展、无需容量规划。它适用于内容增强、实时数据处理、原型快速迭代、嵌入式 AI 能力集成等多种场景，同时支持通过 SDK（如 Gradient Python SDK）以编程方式实现同步或异步调用。

总之，DigitalOcean Gradient AI 的无服务器推理为希望快速集成、灵活调用 AI 模型的开发者提供了一条低门槛、高效率的路径，让构建生产级 AI 功能更加简便直接。

OK，言归正传，继续回到教程来。当你将我们上文提到的脚本与你的 skills 文件夹放在同一目录下后，即可运行该脚本。

python3agent_example.py

在打开的输入框中输入：

PleaseparsethetextoutofthePDFat/path/to/your/document.pdf

你将看到 PDF 文本解析结果：

============================================================SIMPLETOOL-BASEDSKILLSEXAMPLE============================================================✅Found1skills:-pdf-processing:ExtractstextfromPDFfilesusingPyPDF2.============================================================CHAT(type'quit'toexit)============================================================Youleaseextractthetextfrom:/Desktop/document.pdf[Turn1]💭LLM:{"function_call":{"name":"activate_skill","arguments":{"skill_name":"pdf-processing"}}}..........ThecostofanRVis30,000

Agent 已成功完成以下流程：

• 找到 Skill
• 解析元数据
• 执行脚本
• 返回 PDF 文本内容

第三步 —— 扩展功能与 Skills

添加任何你希望 LLM 能够访问的脚本或文件夹。然后在SKILL.md文件中，为每个文件夹和脚本添加相应的功能说明与描述。例如，你可以添加用于生成或编辑 PDF 的脚本。请确保将这些附加文件放在你希望它们所属的具体 Skill 文件夹中。

你可以添加任意数量的 Skills，但每个 Skill 文件夹中都必须包含一个SKILL.md文件，Agent 才能识别该 Skill。此外，当 Skills 数量增多时，Agent 可能难以将用户意图与大量 Skill 的元数据准确匹配。因此，随着 Skill 数量的增加，可能需要引入额外的搜索功能，或使用向量嵌入来将用户请求匹配到正确的 Skill。

常见问题

Q：Skills 之间可以相互通信或调用其他 Skills 吗？应如何实现技能链（skill chaining）？

可以。Skills 可以调用其他 Skills。Agent 应能够识别在完成任务时是否需要多个 Skills，并将它们串联执行。此外，也可以在某个 Skill 的指令中直接引用其他 Skills。

Q：当 Skills 需要访问外部服务时，应该如何处理身份认证和APIKey？

切勿在 Skill 文件中硬编码任何凭据。应使用环境变量，或安全的密钥管理系统来存储和读取相关信息。

Q：在启动时加载大量 Skills 会对性能产生什么影响？是否有延迟加载策略？

在启动阶段加载数百个 Skill 的元数据可能会比较缓慢。可以考虑对已加载的 Skills 进行缓存，并使用索引机制来加快在大量 Skills 中的搜索速度。你还可以将“发现（discovery）”与“激活（activation）”步骤分离，在真正需要使用某个 Skill 之前，仅加载其元数据。

Q：如何测试和调试 Skills？

在集成之前，请确保单独测试每一个 Skill。同时，为 Skills 添加更详细的日志输出，以便观察哪些 Skills 被选中，以及被选中的原因。

写在最后

Agent Skills 是一种非常优秀的方式，用于标准化 LLM Agent 的功能能力。它们使用户能够以结构化的形式，为智能体添加和增强各类能力。具体的实现方式取决于你的 Agent 工作流，但目前已经有越来越多的 Agent 服务可以开箱即用地支持 Skills，其中包括 Claude Code、Codex 和 VS Code 等，这些都是已经采用该标准的 Agent 提供方。

接下来，你可以添加更多 Skills，并根据项目需求为它们扩展额外功能。随后，通过向量嵌入或其他搜索机制，进一步提升 Agent 工作流中 Skill 的匹配能力。