理解 Skill 的目录结构和运行机制，是构建可维护、可复用 AI Agent 能力的基础。
本文从零开始拆解一个标准 Skill 的目录结构、各文件作用和完整工作流程。
什么是 Skill
Skill 是一个独立的能力单元，用来完成某一类特定任务。
如果把 Agent 比作操作系统，Skill 就像应用程序；如果把 Agent 比作项目经理，Skill 就是可以被调用的专业能力。
Skill 的常见类型
以下是一些典型的 Skill 应用场景：
Skill 与 Agent 的关系
Skill 本身不负责决定什么时候使用，真正负责决策的是 Agent。
完整的工作流程如下：
Skill 工作流程
关键要点：Agent 不会一次性加载所有 Skill 的完整内容。它会先读取每个 Skill 的描述信息，命中目标 Skill 后再加载完整内容。这样做的原因是：如果有几百个 Skills，每次都全部加载会极其浪费 Token。
Skill 的标准目录结构
一个完整的 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 示例：
实例
常见的错误写法
很多初学者会写出过于简略的 SKILL.md，例如：
不推荐写法
这种写法的问题在于：不知道什么时候使用、不知道什么时候不用、输出格式不明确、容易和其他 Skill 冲突。
一个合格的 SKILL.md 应该让 Agent 一眼就能判断：这个 Skill 适不适合当前任务。
metadata.json：Skill 元信息
这个文件提供机器可读的结构化数据，帮助 Agent 快速筛选 Skill。
常见字段说明
其中 description 字段最为重要，因为 Agent 通常依靠它做匹配。
匹配过程大致如下：用户提出请求后，Agent 扫描所有 Skill 的 description，发现匹配的描述后加载完整的 Skill 内容并执行。
examples：示例目录
很多开发者忽略这一部分，但它实际上非常重要。
目录结构
examples/ ├── example1.md ├── example2.md
示例文件内容
examples 的作用
经验上，好的 examples 往往比增加提示词更有效。
scripts：可执行脚本
Skill 不仅仅是提示词，有时需要真正执行代码来完成实际工作。
常见需要脚本的场景包括：读取 PDF、执行 OCR、调用数据库、数据处理、生成图表等。
scripts/ ├── main.py └── utils.py
Python 脚本示例
Skill 的工作流程是：读取文件 → 执行脚本 → 获取结果，然后再将结果交给大模型处理。
resources：资源目录
用于保存辅助内容，将配置与代码分离。
resources/ ├── prompt.md ├── config.yaml
可能包含的资源类型
配置文件示例
将配置放在独立文件中，以后修改参数就不需要改动代码。
tests：测试目录
成熟项目通常都会包含测试，用于验证 Skill 的效果和稳定性。
tests/ ├── test_cases.md └── eval.yaml
测试用例示例
测试的作用
没有测试的 Skill 容易出现"改了一句话，旧功能突然失效"的问题。
README：使用说明
README 面向开发者，说明如何安装和使用这个 Skill。
它解决的核心问题是：以后自己都不知道怎么用自己写的 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 是把能力沉淀成资产。
学习助手
