Agent Skills 为智能体集成技能

如何为你的智能体或工具添加智能体技能的支持功能 本文档介绍如何为AI智能体或开发工具，接入智能体技能的支持能力。

集成方式

集成智能体技能主要有两种实现方式：

1. 基于文件系统的智能体：运行在bash/UNIX等计算机环境中，是功能最完善的实现方案。当模型下达cat /path/to/my-skill/SKILL.md这类Shell命令时，技能即被激活，配套的资源文件也通过Shell命令访问。
2. 基于工具的智能体：无需专属的计算机运行环境，而是通过开发专属工具，让模型触发技能并访问技能包内的资源。具体的工具实现方式，由开发者自主设计。

概述

一个兼容智能体技能的智能体，需实现以下核心能力：

1. 在指定的配置目录中发现技能
2. 启动时加载技能的元数据（名称和描述）
3. 将用户的任务与相关的技能进行匹配
4. 加载技能的完整操作指引，完成技能激活
5. 根据任务需求，执行技能脚本并访问配套资源

技能发现

智能体技能是以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>

• 对于基于文件系统的智能体，需在<location>字段中填写SKILL.md文件的绝对路径；
• 对于基于工具的智能体，可省略<location>字段。

请保证元数据的简洁性，每项技能的元数据占用的令牌数，建议控制在50-100个左右。

安全考量

执行技能中的脚本会带来一定的安全风险，建议从以下方面做好防护：

• 沙箱隔离：在独立的隔离环境中运行脚本
• 白名单机制：仅允许执行可信技能中的脚本
• 用户确认：执行存在潜在风险的操作前，先向用户确认
• 日志记录：对所有脚本的执行操作进行记录，便于后续审计

参考实现

skills-ref参考库提供了用于操作智能体技能的Python工具库和命令行界面（CLI），可直接参考使用。

示例用法如下：

1. 验证技能目录的格式规范性：

   skills-ref validate <path>

2. 生成供智能体提示词使用的<available_skills>格式XML内容：

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

你也可以将该库的源代码，作为智能体技能集成的参考实现方案。