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

URL: https://caijiao.org/agent-skills/integrate-skills
Source: docs/agent-skills/integrate-skills.md
Description: 如何将智能体技能支持添加到您的智能体或工具中。

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

## 集成方法

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

**基于文件系统的智能体** 在计算机环境（bash/unix）中运行，代表最强大的选项。当模型发出 `cat /path/to/my-skill/SKILL.md` 等 shell 命令时，技能被激活。通过 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
    }
```

### 注入到上下文中

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

遵循平台的系统提示更新指南。例如，对于 Claude 模型，推荐的格式使用 XML：

```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](https://github.com/agentskills/agentskills/tree/main/skills-ref) 库提供了用于处理技能的 Python 实用程序和 CLI。

例如：

**验证技能目录：**

```
skills-ref validate <path>
```

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

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

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