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

# 将 Skills 集成到你的 Agent

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

本指南解释了如何为 AI Agent 或开发工具添加 Skills 支持。

## 集成方法

集成 Skills 的两种主要方法是：

**基于文件系统的 Agent (Filesystem-based agents)** 在计算机环境（bash/unix）中运行，代表了最强大的选项。当模型发出类似 `cat /path/to/my-skill/SKILL.md` 的 Shell 命令时，Skills 被激活。捆绑的资源通过 Shell 命令访问。

**基于工具的 Agent (Tool-based agents)** 在没有专用计算机环境的情况下运行。相反，它们实现了一些工具，允许模型触发 Skills 并访问捆绑的资产。具体的工具实现由开发人员决定。

## 概览

一个兼容 Skills 的 Agent 需要：

1. 在配置的目录中**发现 (Discover)** Skills
2. 在启动时**加载元数据 (Load metadata)**（名称和描述）
3. 将用户任务与相关的 Skills **匹配 (Match)**
4. 通过加载完整的指令来**激活 (Activate)** Skills
5. 根据需要**执行 (Execute)** 脚本并访问资源

## 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
    }
```

### 注入到上下文中

在 System Prompt 中包含 Skill 元数据，以便模型知道有哪些可用的 Skills。

遵循你所用平台的 System Prompt 更新指南。例如，对于 Claude 模型，推荐的格式使用 XML：

```xml theme={null}
<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>
```

对于基于文件系统的 Agent，包含指向 `SKILL.md` 文件的绝对路径的 `location` 字段。对于基于工具的 Agent，可以省略 `location`。

保持元数据简洁。每个 Skill 应向上下文中添加大约 50-100 个 Token。

## 安全注意事项

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

* **沙箱化 (Sandboxing)**：在隔离的环境中运行脚本
* **白名单 (Allowlisting)**：仅执行来自受信任 Skills 的脚本
* **确认 (Confirmation)**：在运行潜在危险操作前询问用户
* **日志记录 (Logging)**：记录所有脚本执行以供审计

## 参考实现

[skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) 库提供了用于处理 Skills 的 Python 实用程序和 CLI。

例如：

**验证 Skill 目录：**

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

**为 Agent Prompt 生成 `<available_skills>` XML：**

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

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