技能（Skills）集成使用

本指南解释了如何为人工智能代理（Agent）或开发工具（IDE）添加技能（Skills）支持。

集成方法

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

基于文件系统的代理程序在计算机环境（bash/unix）中运行，是功能最强大的选择。当模型发出类似 sudo 的 shell 命令时，技能会被激活cat /path/to/my-skill/SKILL.md。捆绑的资源也通过 shell 命令访问。

基于工具的智能体无需专用计算机环境即可运行。它们通过实现各种工具，使模型能够触发技能并访问捆绑的资源。具体的工具实现方式由开发者决定。

简述

具备相应技能的代理需要：

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
    }

融入上下文(Context)

在系统提示中包含技能元数据，以便模型知道有哪些技能可用。请遵循平台提供的系统提示更新指南。例如，对于 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>

对于基于文件系统的代理，请包含locationSKILL.md 文件的绝对路径字段。对于基于工具的代理，可以省略此位置。保持元数据简洁。每项技能应在上下文中增加大约 50-100 个标记。

安全考量

脚本执行会带来安全风险。请考虑以下因素：

• 沙盒：在隔离的环境中运行脚本

• 允许列表：仅执行来自受信任技能的脚本

• 确认：在执行潜在危险操作前，请征得用户同意。

• 日志记录：记录所有脚本执行情况以进行审计

参考实现

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

例如：

验证技能目录：

skills-ref validate <path>

<available_skills>为代理提示生成XML：

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

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