将技能集成到您的智能体中

本指南解释了如何将技能支持添加到 AI 智能体或开发工具中。

集成方法

集成技能的两种主要方法是：

基于文件系统的智能体 在计算机环境（bash/unix）中运行，代表最强大的选项。当模型发出 cat /path/to/my-skill/SKILL.md 等 shell 命令时，技能被激活。通过 shell 命令访问捆绑的资源。

基于工具的智能体 无需专用计算机环境即可运行。相反，它们实现工具，允许模型触发技能并访问捆绑的资产。具体工具实现由开发人员决定。

概述

兼容技能的智能体需要：

发现配置目录中的技能
加载元数据（名称和描述）在启动时
匹配用户任务与相关技能
激活技能，加载完整指令
执行脚本并根据需要访问资源

技能发现

技能是包含 SKILL.md 文件的文件夹。您的智能体应扫描配置目录以查找有效技能。

加载元数据

在启动时，仅解析每个 SKILL.md 文件的前置元数据。这保持了初始上下文使用较低。

解析前置元数据

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

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

注入到上下文中

将技能元数据包含在系统提示中，以便模型知道可用的技能。

遵循平台的系统提示更新指南。例如，对于 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>

对于基于文件系统的智能体，包含带有 SKILL.md 文件绝对路径的 location 字段。对于基于工具的智能体，可以省略位置。

保持元数据简洁。每个技能应向上下文添加约 50-100 个令牌。

安全考虑

脚本执行引入了安全风险。考虑：

沙箱化：在隔离环境中运行脚本
允许列表：仅执行来自可信技能的脚本
确认：在运行潜在危险操作前询问用户
日志记录：记录所有脚本执行以进行审计

参考实现

skills-ref 库提供了用于处理技能的 Python 实用程序和 CLI。

例如：

验证技能目录：

skills-ref validate <path>

为智能体提示生成 <available_skills> XML：

skills-ref to-prompt <path>...

使用库源代码作为参考实现。