Skills 基本结构
Skills 的核心本质，是给 AI 制定标准化执行流程的操作指引，规则一经编写完成，就能像程序函数一样，被反复调用、直接复用。
Skills 以 Markdown 文本载体存储，本身不直接执行功能。
Skills 按需加载、渐进式调用的特性，高效沉淀工作经验，实现能力快速复用与精准传递。
Skill 的核心结构
Skills 的核心就是：一个文件夹 + 一个 SKILL.md 文件。
SKILL.md 文件包含：
- 元数据（至少要有名称和描述）
- 告诉 AI 如何完成某一特定任务的指令
一个 Skill 本质上就是一个 Markdown 文件（文件名固定为 SKILL.md）
my-skill/ └── SKILL.md （唯一必需）
SKILL.md 基本模板:
--- name: your-skill-name description: Brief description of what this Skill does and when to use it --- # Your Skill Name ## Instructions [Clear, step-by-step guidance for Claude to follow] ## Examples [Concrete examples of using this Skill]
整个 SKILL.md 分为上下两部分：用 --- 包裹的 YAML frontmatter（头部配置），以及下方的 Markdown 正文（执行说明）。
接下来我们逐一拆解每个部分:
Frontmatter：两个必填字段
Frontmatter 是 SKILL.md 顶部用 --- 包裹的 YAML 配置块，是整个 Skill 的身份信息。
官方只规定两个必填字段：
字段一：name（技能名称）
name 字段最多 64 个字符，只能包含小写字母、数字和连字符。
name: processing-pdfs # 好：动名词形式，清晰描述功能 name: analyzing-spreadsheets # 好：一眼知道用途 name: my-brand-guidelines # 好：组织专属知识 name: helper # 差：太模糊 name: MySkill # 差：包含大写字母（不合规） name: data files # 差：包含空格（不合规）
推荐使用动名词形式（动词 + -ing）来命名，如 processing-pdfs、analyzing-spreadsheets，这样能清晰描述 Skill 提供的活动或能力。
字段二：description（触发条件描述）
这是最重要的字段。启动时，系统只会把所有 Skills 的 name 和 description 预加载进系统提示词。
只有当 description 被 AI 判断与当前任务相关时，才会进一步读取完整的 SKILL.md 内容。
description 应该同时包含两部分：这个 Skill 做什么，以及什么时候 Claude 应该使用它。
description: | Use when the user needs to create, read, edit, or generate Word documents (.docx). Triggers include: 'Word doc', 'word document', '.docx', 'report', 'letter', 'memo', or any request to produce a formatted document for sharing or printing.
Markdown 正文：执行说明的内部结构
Frontmatter 之后是 Markdown 正文，告诉 AI 具体怎么做。
至少包含两个区块：
SKILL.md 实例
SKILL.md 基本模板:
--- name: pdf-processing description: 从 PDF 中提取文本和表格，填写表单，并合并文档 --- # PDF 处理 ## 使用场景 当需要对 PDF 文件进行操作时使用，例如： - 提取 PDF 文本或表格数据 - 填写 PDF 表单 - 合并多个 PDF 文件 ## 提取文本 - 使用 `pdfplumber` 提取文本型 PDF 内容 - 扫描版 PDF 需配合 OCR 工具 ## 填写表单 - 读取 PDF 表单字段 - 按输入数据填充并生成新文件
最小必填示例:
--- name: skill-name description: 说明该 Skill 的功能以及适用场景 ---
含可选字段示例:
--- name: pdf-processing description: 从 PDF 中提取文本和表格，填写表单，并合并文档 license: Apache-2.0 metadata: author: example-org version: "1.0" ---
字段说明：
| 字段 | 必需 | 说明 |
|---|---|---|
| name | 是 | Skill 名称，最长 64 字符，只能使用小写字母、数字和 -，且不能以 - 开头或结尾 |
| description | 是 | 功能与使用场景说明，最长 1024 字符，不能为空 |
| license | 否 | 许可证名称或指向随 Skill 附带的许可证文件 |
| compatibility | 否 | 环境与依赖说明（产品、系统包、网络权限等），最长 500 字符 |
| metadata | 否 | 自定义键值对，用于扩展元数据（如作者、版本号） |
| allowed-tools | 否 | 允许使用的工具列表（空格分隔，实验性功能） |
Skill 的文件目录结构
一个技能就是一个文件夹，至少包含一个 SKILL.md 文件，根据需要，还可以包含其他目录和文件。
为避免上下文膨胀：
- 核心规则 →
SKILL.md - 详细资料 → 单独文件
- 实用逻辑 → 脚本执行（不加载）
推荐结构:
my-skill/
├── SKILL.md # 必需：元数据 + 指令
├── scripts/ # 可选：可执行代码
└── helper.py
├── references/ # 可选：参考文档
├── assets/ # 可选：模板、资源
└── ... # 其他文件或目录
各目录的作用如下：
- SKILL.md：必需文件，包含技能的元数据和执行指令
- scripts/：可选目录，包含代理可以执行的可执行代码
- references/：可选目录，包含详细的参考资料
- assets/：可选目录，包含静态资源如模板、图片等
