文档导航

• 概览
• 规范
• 什么是 Skills？
• 在技能中使用脚本
• 集成 Skills

集成 Skills

如何为你的 AI 助手或开发工具添加 Agent Skills 支持。

本文面向客户端/产品实现方，说明在 agent 或工具中接入 Skills 的两种方式、必备流程及参考实现。

集成方式

两种常见做法：

• 基于文件系统的 agent：在具备本地环境（如 bash/Unix）时，模型通过 shell 命令（例如 cat /path/to/my-skill/SKILL.md）激活技能并访问脚本与资源，能力最完整。
• 基于工具的 agent：无独立「电脑环境」时，由你实现工具接口，让模型通过工具调用来触发技能、读取 SKILL.md 或资源。具体工具形态由实现方决定。

兼容 Skills 的 agent 需具备的能力

1. 发现：在配置的目录下扫描并识别有效技能（含 SKILL.md 的文件夹）。
2. 加载元数据：启动时仅解析每个 SKILL.md 的 frontmatter（name、description），控制上下文占用。
3. 匹配：根据用户任务与技能的 description 判断哪些技能相关。
4. 激活：在需要时将对应技能的完整 SKILL.md 内容读入上下文。
5. 执行：按说明执行脚本、访问 references/、assets/ 等资源（文件系统方式通过 shell；工具方式通过你实现的接口）。

技能发现

技能即包含 SKILL.md 的目录。在配置的技能根目录下递归或单层扫描，将每个含有效 SKILL.md 的子目录视为一个技能。

加载元数据

启动时只解析每个 SKILL.md 的 YAML frontmatter，避免把全文载入，保持初始 token 占用较低。

解析 frontmatter

逻辑可概括为：

function parseMetadata(skillPath):
    content = readFile(skillPath + "/SKILL.md")
    frontmatter = extractYAMLFrontmatter(content)
    return {
        name: frontmatter.name,
        description: frontmatter.description,
        path: skillPath
    }

注入到上下文

将技能列表（name、description，以及按需的 location）注入系统提示，让模型知道有哪些技能可用。格式可参考你所用模型的推荐方式；常见做法之一是用 XML 包裹技能列表，例如：

<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>从 PDF 提取文本与表格、填写表单、合并文档。</description>
    <location>/path/to/skills/pdf-processing/SKILL.md</location>
  </skill>
  <skill>
    <name>data-analysis</name>
    <description>分析数据集、生成图表与摘要报告。</description>
    <location>/path/to/skills/data-analysis/SKILL.md</location>
  </skill>
</available_skills>

基于文件系统的 agent 可提供 location（SKILL.md 的绝对路径），便于模型通过 shell 读取；基于工具的 agent 可省略 location，由工具实现按 name 返回内容。元数据尽量精简，每个技能约 50–100 token 为宜。

安全注意

脚本执行会带来风险，建议：

• 沙箱：在隔离环境中运行脚本。
• 白名单：仅执行来自可信技能目录的脚本。
• 确认：对可能危险的操作先征得用户确认。
• 审计：记录脚本执行日志便于追溯。

参考实现

skills-ref 提供 Python 工具与 CLI，可用于校验技能、生成注入 prompt 的 XML 等，例如：

• 校验技能目录：skills-ref validate <path>
• 生成 <available_skills> XML：skills-ref to-prompt <path>...

可将该库源码作为实现参考。完整规范见 agentskills.io。

← 返回技能包文档  ·  规范  ·  什么是 Skills？  ·  在技能中使用脚本  ·  概览