Skip to main content
本指南解释了如何为 AI Agent 或开发工具添加 Skills 支持。

​
集成方法

集成 Skills 的两种主要方法是： 基于文件系统的 Agent (Filesystem-based agents) 在计算机环境（bash/unix）中运行，代表了最强大的选项。当模型发出类似 cat /path/to/my-skill/SKILL.md 的 Shell 命令时，Skills 被激活。捆绑的资源通过 Shell 命令访问。 基于工具的 Agent (Tool-based agents) 在没有专用计算机环境的情况下运行。相反，它们实现了一些工具，允许模型触发 Skills 并访问捆绑的资产。具体的工具实现由开发人员决定。

​
概览

一个兼容 Skills 的 Agent 需要：
  1. 在配置的目录中发现 (Discover) Skills
  2. 在启动时加载元数据 (Load metadata)（名称和描述）
  3. 将用户任务与相关的 Skills 匹配 (Match)
  4. 通过加载完整的指令来激活 (Activate) Skills
  5. 根据需要执行 (Execute) 脚本并访问资源

​
Skill 发现

Skills 是包含 SKILL.md 文件的文件夹。你的 Agent 应扫描配置的目录以查找有效的 Skills。

​
加载元数据

在启动时，仅解析每个 SKILL.md 文件的 Frontmatter。这可以保持较低的初始上下文占用。

​
解析 Frontmatter

function parseMetadata(skillPath):
    content = readFile(skillPath + "/SKILL.md")
    frontmatter = extractYAMLFrontmatter(content)

    return {
        name: frontmatter.name,
        description: frontmatter.description,
        path: skillPath
    }

​
注入到上下文中

在 System Prompt 中包含 Skill 元数据，以便模型知道有哪些可用的 Skills。 遵循你所用平台的 System Prompt 更新指南。例如，对于 Claude 模型，推荐的格式使用 XML： 
<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>Extracts text and tables from PDF files, fills forms, merges documents.</description>
    <location>/path/to/skills/pdf-processing/SKILL.md</location>
  </skill>
  <skill>
    <name>data-analysis</name>
    <description>Analyzes datasets, generates charts, and creates summary reports.</description>
    <location>/path/to/skills/data-analysis/SKILL.md</location>
  </skill>
</available_skills>
对于基于文件系统的 Agent，包含指向 SKILL.md 文件的绝对路径的 location 字段。对于基于工具的 Agent，可以省略 location。 保持元数据简洁。每个 Skill 应向上下文中添加大约 50-100 个 Token。

​
安全注意事项

执行脚本会带来安全风险。请考虑：
  • 沙箱化 (Sandboxing)：在隔离的环境中运行脚本
  • 白名单 (Allowlisting)：仅执行来自受信任 Skills 的脚本
  • 确认 (Confirmation)：在运行潜在危险操作前询问用户
  • 日志记录 (Logging)：记录所有脚本执行以供审计

​
参考实现

skills-ref 库提供了用于处理 Skills 的 Python 实用程序和 CLI。 例如： 验证 Skill 目录： 
skills-ref validate <path>
为 Agent Prompt 生成 <available_skills> XML： 
skills-ref to-prompt <path>...
使用该库的源代码作为参考实现。