什么是 SKILL.md 文件？AI 技能规范完整解析

摘要

SKILL.md 是 AI Skill 的核心文件，定义了 Skill 的元数据和执行指令。本文介绍 SKILL.md 的文件结构、必填和选填字段的含义，以及如何编写一个规范的 SKILL.md 文件。

一、SKILL.md 文件的作用

SKILL.md 文件是 AI Skill 的核心文件，它定义了 Skill 的基本信息、功能说明和使用方法。

当用户安装一个 Skill 后，AI 智能体会读取 SKILL.md 文件，了解这个 Skill 的功能和使用方法，从而为用户提供相应的服务。

一个完整且规范的 SKILL.md 文件，可以让 AI 智能体准确地理解 Skill 的功能，为用户提供符合预期的服务。

二、SKILL.md 文件的结构

SKILL.md 文件由两部分组成：

2.1 第一部分：YAML frontmatter

YAML frontmatter 是 SKILL.md 文件开头的元数据部分，用 --- 标记开始和结束。

YAML frontmatter 包含 Skill 的基本信息，如名称、描述、版本、分类、支持的平台等。

YAML frontmatter 示例：

---
name: 财报分析
description: 分析上市公司财报，提取关键财务指标
version: 1.0.0
category: 金融分析
platforms: [WorkBuddy, QClaw, ima]
---

2.2 第二部分：Markdown 正文

Markdown 正文是 SKILL.md 文件的主要部分，位于 YAML frontmatter 之后。

Markdown 正文包含 Skill 的功能说明、使用方法、示例等内容，使用 Markdown 格式编写。

Markdown 正文示例：

# 财报分析 Skill

## 功能说明
本 Skill 可以分析上市公司财报，提取关键财务指标。

## 使用方法
1. 输入上市公司股票代码
2. 等待分析结果
3. 查看提取的财务指标

## 示例
输入：000001
输出：营业收入、净利润、资产负债率等指标

三、必要元数据字段

在 YAML frontmatter 中，以下字段是必需的：

3.1 name

Skill 的名称，用于标识这个 Skill。

要求：

• 名称应简洁明了
• 名称应反映 Skill 的功能
• 名称在平台上应唯一

示例：

name: 财报分析

3.2 description

Skill 的描述，简要说明 Skill 的功能。

要求：

• 描述应简洁明了
• 描述应说明 Skill 的主要功能
• 描述应帮助用户理解 Skill 的用途

示例：

description: 分析上市公司财报，提取关键财务指标

3.3 version

Skill 的版本号，遵循语义化版本规范。

要求：

• 版本号格式：主版本号.次版本号.修订号（如 1.0.0）
• 当 Skill 有重大变更时，增加主版本号
• 当 Skill 有新增功能时，增加次版本号
• 当 Skill 有 Bug 修复时，增加修订号

示例：

version: 1.0.0

3.4 category

Skill 的分类，用于平台对 Skills 进行分类管理。

常见分类：

• 金融分析
• 科技开发
• 内容创作
• 数据分析
• 跨境电商

示例：

category: 金融分析

3.5 platforms

Skill 支持的平台列表，表示这个 Skill 可以在哪些 AI 平台上使用。

支持的平台：

• WorkBuddy
• QClaw
• ima
• Claude Code
• Cursor

示例：

platforms: [WorkBuddy, QClaw, ima]

四、Markdown 正文编写规范

Markdown 正文应使用清晰的标题层级和格式，方便阅读和解析。

4.1 标题层级

使用 # 表示标题层级：

• # 表示一级标题
• ## 表示二级标题
• ### 表示三级标题

4.2 功能说明

在 Markdown 正文中，应详细说明 Skill 的功能。

建议包含的内容：

• Skill 的主要功能
• Skill 适用的场景
• Skill 的输入和输出

4.3 使用方法

详细说明如何使用这个 Skill。

建议包含的内容：

• 使用步骤
• 需要的输入
• 预期的输出

4.4 示例

提供使用示例，帮助用户理解如何使用 Skill。

建议包含的内容：

• 输入示例
• 输出示例
• 使用场景示例

五、TRACE 评测体系中的规范性维度

SkillHub 首发 TRACE 评测体系，其中 "C — Convention（规范性）" 维度评估 Skill 的规范性。

5.1 渐进式披露

Skill 的文档应循序渐进地披露信息，先介绍基本功能，再介绍高级功能。

5.2 文档结构清晰度

SKILL.md 文件应有清晰的结构，使用标题、列表、代码块等格式元素。

5.3 限制说明完整性

Skill 的文档应说明其能力和限制，帮助用户了解 Skill 的适用范围。

5.4 示例充分性

Skill 的文档应提供充分的示例，帮助用户理解如何使用 Skill。

六、如何编写 SKILL.md 文件

如果你是 Skill 开发者，想要编写 SKILL.md 文件，可以参考以下步骤：

6.1 第一步：创建文件

创建一个名为 SKILL.md 的文件。

6.2 第二步：编写 YAML frontmatter

在文件开头编写 YAML frontmatter，包含必要字段。

6.3 第三步：编写 Markdown 正文

在 YAML frontmatter 之后，编写 Markdown 正文，包含功能说明、使用方法、示例等内容。

6.4 第四步：检查规范性

检查 SKILL.md 文件是否符合规范性要求，包括文档结构、限制说明、示例等。

6.5 第五步：测试

在 AI 平台上测试 Skill，检查 AI 智能体是否能正确读取和理解 SKILL.md 文件。

七、SKILL.md 文件示例

以下是一个完整的 SKILL.md 文件示例：

---
name: 财报分析
description: 分析上市公司财报，提取关键财务指标
version: 1.0.0
category: 金融分析
platforms: [WorkBuddy, QClaw, ima]
---

# 财报分析 Skill

## 功能说明
本 Skill 可以分析上市公司财报，提取关键财务指标，包括营业收入、净利润、资产负债率等。

## 适用场景
- 分析上市公司财务状况
- 比较不同公司的财务表现
- 辅助投资决策

## 使用方法
1. 输入上市公司股票代码
2. 等待分析结果
3. 查看提取的财务指标

## 输入要求
- 输入应为有效的股票代码
- 支持 A 股、港股、美股股票代码

## 输出内容
- 营业收入
- 净利润
- 资产负债率
- 其他关键财务指标

## 示例

### 示例一
输入：000001
输出：
- 营业收入：1000 亿元
- 净利润：100 亿元
- 资产负债率：50%

### 示例二
输入：AAPL
输出：
- 营业收入：500 亿美元
- 净利润：100 亿美元
- 资产负债率：30%

## 限制说明
- 本 Skill 只能分析公开披露的财报数据
- 本 Skill 不提供投资建议
- 分析结果仅供参考

## 注意事项
- 确保输入正确的股票代码
- 财报数据有滞后性，最新数据可能未披露

八、总结

SKILL.md 文件是 AI Skill 的核心文件，它定义了 Skill 的基本信息、功能说明和使用方法。一个完整且规范的 SKILL.md 文件，可以让 AI 智能体准确地理解 Skill 的功能，为用户提供符合预期的服务。

无论你是 Skill 开发者还是使用者，了解 SKILL.md 文件的结构和规范，都有助于更好地理解和使用 AI 技能。

如果你想了解更多关于 AI 技能的信息，可以访问 SkillHub 官网 https://skillhub.cn 进行探索。