AI Agent Skills 目录结构详解

在构建 AI Agent 技能体系时，理解 Skill 的目录结构和运行机制是最基础也最重要的一步。只有掌握了 Skill 的组织方式，才能设计出可维护、可复用的 AI Agent 能力单元。

本文将系统拆解一个标准 Skill 的目录结构，逐一说明每个文件和目录的作用，并通过完整案例展示整个工作流程。

什么是 Skill

Skill 是一个独立的能力单元，专门用于完成某一类特定任务。可以将 Agent 理解为一个操作系统，而 Skill 就是安装在系统上的应用程序；或者把 Agent 看作项目经理，Skill 则是它能够调用的各项专业能力。

Skill 的常见类型

以下是一些典型的 Skill 应用场景：

Skill 与 Agent 的关系

Skill 只负责完成具体任务，不决定"什么时候用哪个 Skill"——这个决策权完全在 Agent 手中。

完整的工作流程如下图所示：

关键要点：Agent 不会一次性加载所有 Skill 的完整内容。它会先读取每个 Skill 的描述信息，命中目标 Skill 后再加载完整内容。如果系统中有几百个 Skills，每次全部加载会极其浪费 Token。

Skill 的标准目录结构

一个完整的 Skill 不是单个文件，而是一个包含多个文件的目录。

标准目录结构如下：

my-skill/
│
├── SKILL.md          ← 核心执行文件
├── metadata.json     ← 元信息
├── examples/         ← 示例目录
│   ├── example1.md
│   └── example2.md
│
├── scripts/          ← 可执行脚本
│   ├── main.py
│   └── utils.py
│
├── resources/        ← 资源目录
│   ├── prompt.md
│   └── config.yaml
│
├── tests/            ← 测试目录
│   ├── test_cases.md
│   └── eval.yaml
│
├── README.md         ← 使用说明
│
└── CHANGELOG.md      ← 变更日志

下面逐一拆解每个文件和目录的职责。

SKILL.md：核心执行文件

这是 Skill 中最重要的文件，定义了 Skill 的所有执行逻辑，包含以下关键信息：

规范的 SKILL.md 示例

# PDF 分析 Skill

## Description
用于分析 PDF 内容并生成摘要。

## When to use
适用于：
- PDF 阅读
- 摘要提取
- 内容分析

## When NOT to use
不适用于：
- 图片编辑
- 视频处理

## Input
PDF 文件

## Instructions
1. 提取文本
2. 识别章节结构
3. 总结主要内容
4. 输出重点

## Output
Markdown 格式摘要

常见错误写法

很多初学者会写出过于简略的 SKILL.md：

# PDF Skill
读取 PDF
总结内容
返回结果

这种写法的问题在于：Agent 不知道什么时候该用这个 Skill，不知道什么时候不该用，输出格式不明确，还容易和其他 Skill 产生冲突。

一个合格的 SKILL.md 应该让 Agent 一眼就能判断：这个 Skill 到底适不适合当前任务。

metadata.json：Skill 元信息

这个文件提供机器可读的结构化数据，帮助 Agent 快速筛选 Skill。

{
    "name": "pdf-analyzer",
    "version": "1.0.0",
    "description": "分析 PDF 并生成摘要",
    "tags": ["pdf", "summary"],
    "category": "document"
}

常见字段说明

其中 description 字段最为重要，因为 Agent 通常依靠它做匹配。匹配过程大致是：用户提出请求后，Agent 扫描所有 Skill 的 description，发现匹配项后加载完整的 Skill 内容并执行。

examples：示例目录

很多开发者忽视这一部分，但它的重要性不亚于 SKILL.md 本身。

examples/
├── example1.md
├── example2.md

示例内容

输入：
帮我分析这个 PDF

输出：
# 文档总结

## 核心内容
1. ...
2. ...
3. ...

examples 的重要作用

经验上，设计良好的 examples 往往比增加提示词长度更有效。

scripts：可执行脚本

Skill 不仅仅是提示词，有时需要真正执行代码来完成实际工作，比如读取 PDF、执行 OCR、调用数据库、数据处理、生成图表等。

scripts/
├── main.py
└── utils.py

Python 脚本示例

# 文件路径：scripts/extract.py
# 功能：从 PDF 文件中提取文本内容

from pypdf import PdfReader

# 打开 PDF 文件
reader = PdfReader("demo.pdf")

# 存储提取的文本
text = ""

# 遍历每一页并提取文本
for page in reader.pages:
    text += page.extract_text()

# 输出全部文本内容
print(text)

Skill 的工作流程是：读取文件 → 执行脚本 → 获取结果，然后再将结果交给大模型进一步处理。

resources：资源目录

用于保存辅助内容，将配置与代码分离，便于后期维护。

resources/
├── prompt.md
├── config.yaml

常见资源类型

配置文件示例

# 文件路径：resources/config.yaml
# 摘要相关配置

max_length: 1000    # 摘要最大长度（字符数）
language: zh        # 输出语言：zh=中文, en=英文

将配置放在独立文件中，以后修改参数就不需要改动代码，降低维护成本。

tests：测试目录

成熟项目通常包含测试，用于验证 Skill 的效果和稳定性。

tests/
├── test_cases.md
└── eval.yaml

测试用例示例

测试：
输入：帮我分析 PDF
期望：
- 输出摘要
- 包含关键点

测试的作用

没有测试的 Skill 容易出现"改了一句话，旧功能突然失效"的问题。

README：使用说明

README 面向开发者，说明如何安装和使用这个 Skill。

# 安装
复制到 skills 目录

# 使用方法
上传 PDF

# 输出格式
Markdown

它解决的核心问题很现实：过一段时间后，连自己都可能忘记当初设计的 Skill 该怎么用。

完整案例：PDF 分析 Skill

下面用一个完整的例子串联以上所有概念。

目录结构总览

pdf-analyzer/
├── SKILL.md
├── metadata.json
├── examples/
│   └── summary.md
├── scripts/
│   └── extract.py
├── tests/
│   └── eval.md
└── README.md

完整调用流程

用户：上传 PDF 并总结
        ↓
Agent：扫描所有 Skills
        ↓
发现：description: 分析 PDF 并生成摘要
        ↓
命中 pdf-analyzer
        ↓
读取 SKILL.md
        ↓
调用 extract.py
        ↓
提取 PDF 内容
        ↓
生成摘要
        ↓
返回结果

为什么 Skill 要设计成目录结构

很多人会问：为什么不用一个 prompt.txt 搞定所有事情？原因很简单——规模一大就会失控。

单文件方案的问题

目录化方案的优势

总结

Skill 本质上不是一段提示词，而是一套完整的软件能力包。

核心文件关系

SKILL.md         → 定义行为
metadata.json    → 定义信息
examples/        → 定义示例
scripts/         → 定义能力
tests/           → 定义质量
README           → 定义使用方式

Prompt 只能解决一次问题，而 Skill 是把能力沉淀成资产。当你把 AI Agent 的能力从"一次性对话"升级为"可复用的能力单元"，才能真正发挥 Agent 的效率优势。

作者：admin

TTF的家园-www.ttfde.top 个人博客以便写写东西，欢迎喜欢互联网的朋友一起交流!

TTF的家园 站点 QQ交谈