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

​
集成方法

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

​
概述

一个支持 skills 的 agent 需要：
  1. 发现 配置目录中的 skills
  2. 加载元数据（名称和描述）在启动时
  3. 匹配 用户任务到相关 skills
  4. 激活 skills 通过加载完整指令
  5. 执行 脚本并按需访问资源

​
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
    }

​
注入到上下文中

在系统提示中包含 skill 元数据，以便模型知道有哪些 skills 可用。 遵循你平台的系统提示更新指南。例如，对于 Claude 模型，推荐格式使用 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，包含 SKILL.md 文件的绝对路径的 location 字段。对于基于工具的 agent，可以省略位置。 保持元数据简洁。每个 skill 应该在上下文中添加大约 50-100 个 token。

​
安全考虑

脚本执行引入了安全风险。考虑：
  • 沙箱化：在隔离环境中运行脚本
  • 白名单：仅执行来自受信任 skills 的脚本
  • 确认：在运行可能危险的操作前询问用户
  • 日志记录：记录所有脚本执行以供审计

​
参考实现

skills-ref 库提供了用于处理 skills 的 Python 实用工具和 CLI。 例如： 验证 skill 目录： 
skills-ref validate <path>
为 agent 提示生成 <available_skills> XML： 
skills-ref to-prompt <path>...
使用库源代码作为参考实现。