第二章：Skill 结构¶
标准目录结构¶
一个标准的 Skill 是一个目录，包含必需的 SKILL.md 文件和可选的捆绑资源：
skill-name/
├── SKILL.md # 主文件（必需）
├── references/ # 参考资源（可选）
│ ├── schema.md # 数据结构说明
│ ├── api-docs.md # API 文档
│ └── examples.md # 详细示例
├── scripts/ # 脚本文件（可选）
│ ├── helper.py # Python 脚本
│ └── process.sh # Shell 脚本
└── assets/ # 输出资源（可选）
├── template.html # 模板文件
└── logo.png # 图片资源
必需文件：SKILL.md¶
SKILL.md 是 Skill 的核心，包含元数据和指令：
---
name: my-skill
description: 简洁描述 Skill 的功能和触发条件
---
# Skill 名称
简要描述这个 Skill 的用途。
## 工作流程
1. 第一步
2. 第二步
3. 第三步
## 使用示例
[具体示例]
YAML Frontmatter¶
---
name: skill-name # 必需：Skill 名称
description: | # 必需：描述和触发条件
详细描述 Skill 功能。
包含何时使用的说明。
这是触发机制的关键。
---
# 注意：只包含 name 和 description
# 不要添加其他字段
描述字段的重要性¶
description 是 Skill 触发的主要机制：
# 好的描述示例
description: |
PDF 文档创建、编辑和分析技能。支持：
(1) 创建新文档
(2) 修改现有内容
(3) 提取文本和表格
(4) 添加水印和签名
当用户需要处理 PDF 文件时使用。
# 不好的描述示例
description: PDF 技能 # 太简短，无法有效触发
可选目录详解¶
references/ - 参考文档¶
存放需要加载到上下文的文档：
references/
├── schema.md # 数据库/数据结构说明
├── api-reference.md # API 规范文档
├── policies.md # 公司政策文档
├── domain-knowledge.md # 领域知识
└── examples.md # 详细使用示例
使用场景： - 数据库 Schema 说明 - API 规范文档 - 公司政策和规范 - 领域专业知识 - 详细工作流指南
最佳实践： - 大文件（>10k 词）在 SKILL.md 中提供搜索模式 - 信息放在 SKILL.md 或 references，不要重复 - 保持 SKILL.md 精简，详细内容放 references
scripts/ - 可执行脚本¶
存放可执行代码，用于需要确定性可靠性或重复执行的任务：
scripts/
├── rotate_pdf.py # PDF 旋转
├── merge_files.py # 文件合并
├── validate.py # 数据验证
└── process.sh # Shell 处理脚本
使用场景： - 相同代码被反复重写 - 需要确定性可靠性 - 复杂的数据处理 - 系统操作
优势： - Token 高效 - 确定性执行 - 可不加载到上下文直接执行
assets/ - 输出资源¶
存放用于输出的文件，不加载到上下文：
assets/
├── template.html # HTML 模板
├── report.docx # 报告模板
├── logo.png # 品牌图片
├── fonts/ # 字体文件
└── boilerplate/ # 样板代码
使用场景： - 模板文件 - 图片和图标 - 样板代码 - 字体文件 - 示例文档
不应包含的文件¶
Skill 应只包含必要文件，不要创建：
skill-name/
├── README.md # ❌ 不需要
├── INSTALLATION.md # ❌ 不需要
├── CHANGELOG.md # ❌ 不需要
├── QUICK_REFERENCE.md # ❌ 不需要
├── CONTRIBUTING.md # ❌ 不需要
└── tests/ # ❌ 不需要
原因：Skill 是给 AI Agent 使用的，不是给人阅读的开源项目。
命名规范¶
Skill 名称¶
# 规则
- 只使用小写字母、数字和连字符
- 长度 < 64 字符
- 使用动词短语描述动作
- 按工具命名空间提高清晰度
# 好的命名
pdf-editor
image-processor
gh-address-comments # GitHub 相关
linear-address-issue # Linear 相关
# 不好的命名
PDF_Editor # 大写和下划线
pdfEditor # 驼峰命名
my-awesome-pdf-tool # 太长
目录命名¶
# Skill 目录名必须与 Skill 名称一致
pdf-editor/
└── SKILL.md # name: pdf-editor
# 不一致会导致问题
pdf-editor/
└── SKILL.md # name: pdf-tool ❌ 不一致
多变体组织¶
当 Skill 支持多种变体时，按变体组织：
cloud-deploy/
├── SKILL.md # 工作流 + 选择指南
└── references/
├── aws.md # AWS 部署模式
├── gcp.md # GCP 部署模式
└── azure.md # Azure 部署模式
# SKILL.md
## 选择云服务商
- AWS: 见 [aws.md](references/aws.md)
- GCP: 见 [gcp.md](references/gcp.md)
- Azure: 见 [azure.md](references/azure.md)
多领域组织¶
当 Skill 覆盖多个领域时，按领域组织：
bigquery-skill/
├── SKILL.md # 概述和导航
└── references/
├── finance.md # 财务指标
├── sales.md # 销售数据
├── product.md # 产品数据
└── marketing.md # 营销数据
结构验证清单¶
创建 Skill 时，检查以下项：
structure-checklist:
required:
- [ ] SKILL.md 文件存在
- [ ] SKILL.md 包含 YAML frontmatter
- [ ] frontmatter 包含 name 字段
- [ ] frontmatter 包含 description 字段
- [ ] 目录名与 name 一致
optional:
- [ ] references/ 目录结构合理
- [ ] scripts/ 脚本可执行
- [ ] assets/ 资源文件有效
forbidden:
- [ ] 无 README.md
- [ ] 无 CHANGELOG.md
- [ ] 无 tests/ 目录
- [ ] 无符号链接
小结¶
本章介绍了 Skill 的目录结构：
- SKILL.md 是必需的核心文件
- references/ 存放参考文档
- scripts/ 存放可执行脚本
- assets/ 存放输出资源
- 命名要遵循规范
- 不要创建不必要的文档文件
下一章将详细介绍如何编写 SKILL.md。