> ## Documentation Index
> Fetch the complete documentation index at: https://agentskills.ooos.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 将 skills 集成到你的 agent 中

> 如何为你的 agent 或工具添加 Agent Skills 支持。

本指南解释了如何为 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：

```xml theme={null}
<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](https://github.com/agentskills/agentskills/tree/main/skills-ref) 库提供了用于处理 skills 的 Python 实用工具和 CLI。

例如：

**验证 skill 目录：**

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

**为 agent 提示生成 `<available_skills>` XML：**

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

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