7.2 SKILL.md 的结构与核心字段

面向经管学生、研究者与从业者的 AI 智能体设计教材

作者

李学恒、林建浩、严翊歆

发布于

2026-05-11

理解 Skill，不必先被复杂目录吓住。一个最小可用的 Skill，核心只需要一个文件：SKILL.md。

这个文件承担两件事。第一，告诉系统它是什么、什么时候该调用；第二，告诉智能体调用之后该按什么步骤工作。前者负责被发现，后者负责被执行。

两层结构

从教学角度看，Skill 可以分成两层。

层级	包含内容	是否必需	作用
最小层	`SKILL.md`（含 YAML frontmatter + 正文步骤）	必需	定义触发条件和执行规则
增强层	`scripts/`、`references/`、`assets/` 等	可选	提供脚本、参考文档、模板资源

只要 SKILL.md 写得清楚，一个 Skill 就已经成立。增强层可以让 Skill 更完整，但不是理解概念的前提。

词条：SKILL.md

定义：Skill 的核心说明文件，由 YAML frontmatter 和 Markdown 正文两部分组成。
常见误解：没有脚本就不算完整 Skill。
命名规则：必须严格写成 SKILL.md（大小写敏感），不接受 skill.md、SKILL.MD 等变体。

文件夹结构

一个完整的 Skill 文件夹结构如下：

financial-report-summary/
├── SKILL.md                  # 必需 - 核心说明文件
├── scripts/                  # 可选 - 可执行脚本
│   └── validate_format.py
├── references/               # 可选 - 参考文档
│   └── report-style-guide.md
└── assets/                   # 可选 - 模板和资源
    └── summary-template.md

文件夹命名有严格规则：

使用 kebab-case（短横线分隔小写字母）：financial-report-summary ✅
禁止空格：Financial Report Summary ❌
禁止下划线：financial_report_summary ❌
禁止大写字母：FinancialReportSummary ❌
禁止包含 claude 或 anthropic（保留词）

存储位置

Skill 有两个存储层级：

层级	路径	作用域
个人级	`~/.claude/skills/`	所有项目共享
项目级	`项目目录/.claude/skills/`	仅当前项目可用

个人级 Skill 适合通用工具，如会议纪要整理、日报生成。项目级 Skill 适合特定业务，如某基金公司的研报摘要模板。

YAML Frontmatter 字段规范

SKILL.md 的开头是 YAML frontmatter，用 --- 包裹。这是系统识别 Skill 的入口。

字段	是否必填	说明
`name`	必填	kebab-case 格式，应与文件夹名一致
`description`	必填	说明做什么、何时使用，不超过 1024 字符
`license`	可选	开源协议，如 MIT、Apache-2.0
`compatibility`	可选	环境要求，如依赖的系统包或网络条件，1-500 字符
`metadata`	可选	自定义键值对，如 author、version、mcp-server
`allowed-tools`	可选	限定 Skill 可使用的工具，如 `"Bash(python:*) Read Glob"`

安全限制

Frontmatter 中禁止使用 XML 尖括号（< 和 >），因为 frontmatter 会出现在系统提示中，尖括号可能被利用来注入指令。

description 写作方法

description 是 Skill 最关键的字段。它决定系统能否准确匹配当前任务。

写作公式：做什么 + 何时使用 + 关键能力

好的 description 示例：

# 具体且包含触发短语
description: >
  整理会议记录并生成结构化纪要。当用户要求总结会议、
  提炼行动项、生成会议纪要时使用。支持中英文会议内容，
  输出包含议题、结论、行动项和待确认事项。

# 明确触发场景和能力边界
description: >
  分析上市公司季度财报数据并生成对比摘要。当用户提到
  季报分析、财务指标对比、盈利能力评估时使用。覆盖
  营收、利润、现金流三大类指标。

不好的 description 示例：

# 太模糊，无法区分用途
description: 帮助处理文档。

# 缺少触发场景
description: 生成高质量多页面结构化文档系统。

# 过于技术化，没有用户视角
description: 实现层级关系实体模型的序列化与反序列化。

最小示例

一个教材式的最小 Skill：

▶ Skill

---
name: meeting-summary
description: >
  整理会议记录并生成结构化纪要。当用户要求总结会议、
  提炼行动项、生成会议纪要时使用。
---

# 会议纪要整理

## 执行步骤

### 第 1 步：识别会议信息
确认会议主题、参与人和时间。

### 第 2 步：提炼核心内容
从原始记录中提取关键结论、分歧点和待办事项。

### 第 3 步：结构化输出
按以下格式输出纪要：

- 会议主题
- 关键结论
- 行动项（含负责人和截止日期）
- 待确认问题

带完整 Frontmatter 的经济金融示例

▶ Skill

---
name: quarterly-earnings-summary
description: >
  分析上市公司季度财报并生成结构化摘要。当用户提到
  季报分析、财务指标对比、盈利能力评估、季度业绩
  解读时使用。覆盖营收、利润率、现金流三大类指标。
license: MIT
compatibility: 需要访问本地文件系统读取财报 PDF 或 CSV
metadata:
  author: econ-finance-team
  version: 1.0.0
  category: financial-analysis
---

# 季度财报摘要生成

## 执行步骤

### 第 1 步：获取财报数据
读取用户提供的财报文件，确认报告期和公司名称。

### 第 2 步：计算核心指标
- 营收增长率（同比 / 环比）
- 毛利率、净利率变动
- 经营性现金流与净利润比值

### 第 3 步：生成对比分析
将本期数据与上期及去年同期对比，标注显著变动项。

### 第 4 步：输出结构化摘要
按固定格式输出：公司概况、核心指标表、重大变动说明、风险提示。

Skill 的质量不取决于文件夹有多丰富，而取决于规则是否稳定。有些 Skill 目录很复杂，但触发条件模糊、正文泛泛而谈，实际并不好用。反过来，一个只有 SKILL.md 的 Skill，只要触发明确、步骤清楚，也能稳定发挥作用。

--- title: "7.2 SKILL.md 的结构与核心字段" --- ![7.2 配图](images/img_02_skill_structure.png) 理解 Skill，不必先被复杂目录吓住。一个最小可用的 Skill，核心只需要一个文件：`SKILL.md`。这个文件承担两件事。第一，告诉系统它是什么、什么时候该调用；第二，告诉智能体调用之后该按什么步骤工作。前者负责被发现，后者负责被执行。 ### 两层结构从教学角度看，Skill 可以分成两层。 | 层级 | 包含内容 | 是否必需 | 作用 | |:---|:---|:---:|:---| | 最小层 | `SKILL.md`（含 YAML frontmatter + 正文步骤） | 必需 | 定义触发条件和执行规则 | | 增强层 | `scripts/`、`references/`、`assets/` 等 | 可选 | 提供脚本、参考文档、模板资源 | 只要 SKILL.md 写得清楚，一个 Skill 就已经成立。增强层可以让 Skill 更完整，但不是理解概念的前提。 ::: {.callout-note} ## 词条：SKILL.md - **定义**：Skill 的核心说明文件，由 YAML frontmatter 和 Markdown 正文两部分组成。 - **常见误解**：没有脚本就不算完整 Skill。 - **命名规则**：必须严格写成 `SKILL.md`（大小写敏感），不接受 `skill.md`、`SKILL.MD` 等变体。 ::: ### 文件夹结构一个完整的 Skill 文件夹结构如下： ```txt financial-report-summary/ ├── SKILL.md # 必需 - 核心说明文件 ├── scripts/ # 可选 - 可执行脚本 │ └── validate_format.py ├── references/ # 可选 - 参考文档 │ └── report-style-guide.md └── assets/ # 可选 - 模板和资源 └── summary-template.md ``` 文件夹命名有严格规则： - 使用 kebab-case（短横线分隔小写字母）：`financial-report-summary` ✅ - 禁止空格：`Financial Report Summary` ❌ - 禁止下划线：`financial_report_summary` ❌ - 禁止大写字母：`FinancialReportSummary` ❌ - 禁止包含 claude 或 anthropic（保留词） ### 存储位置 Skill 有两个存储层级： | 层级 | 路径 | 作用域 | |:---|:---|:---| | 个人级 | `~/.claude/skills/` | 所有项目共享 | | 项目级 | `项目目录/.claude/skills/` | 仅当前项目可用 | 个人级 Skill 适合通用工具，如会议纪要整理、日报生成。项目级 Skill 适合特定业务，如某基金公司的研报摘要模板。 ### YAML Frontmatter 字段规范 SKILL.md 的开头是 YAML frontmatter，用 `---` 包裹。这是系统识别 Skill 的入口。 | 字段 | 是否必填 | 说明 | |:---|:---:|:---| | `name` | 必填 | kebab-case 格式，应与文件夹名一致 | | `description` | 必填 | 说明做什么、何时使用，不超过 1024 字符 | | `license` | 可选 | 开源协议，如 MIT、Apache-2.0 | | `compatibility` | 可选 | 环境要求，如依赖的系统包或网络条件，1-500 字符 | | `metadata` | 可选 | 自定义键值对，如 author、version、mcp-server | | `allowed-tools` | 可选 | 限定 Skill 可使用的工具，如 `"Bash(python:*) Read Glob"` | ::: {.callout-warning} ## 安全限制 Frontmatter 中禁止使用 XML 尖括号（`<` 和 `>`），因为 frontmatter 会出现在系统提示中，尖括号可能被利用来注入指令。 ::: ### description 写作方法 description 是 Skill 最关键的字段。它决定系统能否准确匹配当前任务。写作公式：**做什么 + 何时使用 + 关键能力** 好的 description 示例： ```yaml # 具体且包含触发短语 description: > 整理会议记录并生成结构化纪要。当用户要求总结会议、提炼行动项、生成会议纪要时使用。支持中英文会议内容，输出包含议题、结论、行动项和待确认事项。 ``` ```yaml # 明确触发场景和能力边界 description: > 分析上市公司季度财报数据并生成对比摘要。当用户提到季报分析、财务指标对比、盈利能力评估时使用。覆盖营收、利润、现金流三大类指标。 ``` 不好的 description 示例： ```yaml # 太模糊，无法区分用途 description: 帮助处理文档。 # 缺少触发场景 description: 生成高质量多页面结构化文档系统。 # 过于技术化，没有用户视角 description: 实现层级关系实体模型的序列化与反序列化。 ``` ### 最小示例一个教材式的最小 Skill： ```skill --- name: meeting-summary description: > 整理会议记录并生成结构化纪要。当用户要求总结会议、提炼行动项、生成会议纪要时使用。 --- # 会议纪要整理 ## 执行步骤 ### 第 1 步：识别会议信息确认会议主题、参与人和时间。 ### 第 2 步：提炼核心内容从原始记录中提取关键结论、分歧点和待办事项。 ### 第 3 步：结构化输出按以下格式输出纪要： - 会议主题 - 关键结论 - 行动项（含负责人和截止日期） - 待确认问题 ``` ### 带完整 Frontmatter 的经济金融示例 ```skill --- name: quarterly-earnings-summary description: > 分析上市公司季度财报并生成结构化摘要。当用户提到季报分析、财务指标对比、盈利能力评估、季度业绩解读时使用。覆盖营收、利润率、现金流三大类指标。 license: MIT compatibility: 需要访问本地文件系统读取财报 PDF 或 CSV metadata: author: econ-finance-team version: 1.0.0 category: financial-analysis --- # 季度财报摘要生成 ## 执行步骤 ### 第 1 步：获取财报数据读取用户提供的财报文件，确认报告期和公司名称。 ### 第 2 步：计算核心指标 - 营收增长率（同比 / 环比） - 毛利率、净利率变动 - 经营性现金流与净利润比值 ### 第 3 步：生成对比分析将本期数据与上期及去年同期对比，标注显著变动项。 ### 第 4 步：输出结构化摘要按固定格式输出：公司概况、核心指标表、重大变动说明、风险提示。 ``` Skill 的质量不取决于文件夹有多丰富，而取决于规则是否稳定。有些 Skill 目录很复杂，但触发条件模糊、正文泛泛而谈，实际并不好用。反过来，一个只有 SKILL.md 的 Skill，只要触发明确、步骤清楚，也能稳定发挥作用。