如何编写自己的 AI Skill？从零开始创建 SKILL.md

摘要

编写自己的 AI Skill 可以让 AI 助手学习个人特有的工作流程。本文介绍从零开始创建 SKILL.md 文件的完整流程，包括确定使用场景、编写指令、测试效果和改进迭代的四个步骤。

一、什么是 AI Skill

AI Skill 是为 AI 智能体提供特定能力的技能包。每个 Skill 都是一个独立的功能模块，可以完成特定的任务。

例如，一个"财报分析"Skill 可以让 AI 智能体具备分析上市公司财报的能力；一个"Bug 排查"Skill 可以让 AI 智能体协助开发者排查代码问题。

二、编写 AI Skill 的准备工作

在编写 AI Skill 之前，需要明确以下几点：

2.1 确定 Skill 的功能

首先明确你想要开发的 Skill 的功能。你的 Skill 要解决什么问题？提供什么功能？

功能定位越清晰，后续编写 SKILL.md 文件就越有针对性。

2.2 确定 Skill 的应用场景

明确你的 Skill 适用于哪些应用场景。是金融分析、科技开发、内容创作，还是数据分析？

明确应用场景，有助于用户对 Skill 进行分类和搜索。

2.3 确定 Skill 支持的平台

明确你的 Skill 支持哪些 AI 平台。SkillHub 支持的平台包括：

• WorkBuddy
• QClaw
• ima
• Claude Code
• Cursor

三、创建 SKILL.md 文件

SKILL.md 文件是 AI Skill 的核心文件，由两部分组成：YAML frontmatter 和 Markdown 正文。

3.1 第一步：创建文件

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

3.2 第二步：编写 YAML frontmatter

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

完整示例：

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

字段说明：

• name：Skill 的名称，应简洁明了，反映 Skill 的功能。
• description：Skill 的描述，简要说明 Skill 的功能。
• version：Skill 的版本号，遵循语义化版本规范（如 1.0.0）。
• category：Skill 的分类，如金融分析、科技开发、内容创作等。
• platforms：Skill 支持的平台列表，如 WorkBuddy, QClaw, ima。

3.3 第三步：编写 Markdown 正文

在 YAML frontmatter 之后，编写 Markdown 正文。

Markdown 正文应包含以下内容：

功能说明

详细说明 Skill 的功能，包括主要功能、适用场景、输入和输出。

使用方法

详细说明如何使用这个 Skill，包括使用步骤、需要的输入、预期的输出。

示例

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

限制说明

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

完整示例：

# 财报分析 Skill

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

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

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

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

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

## 示例

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

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

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

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

四、SKILL.md 文件编写规范

在编写 SKILL.md 文件时，应遵循以下规范：

4.1 标题层级规范

使用清晰的标题层级：

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

4.2 内容完整性

确保 SKILL.md 文件包含完整的信息，包括功能说明、使用方法、示例、限制说明等。

4.3 示例充分性

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

4.4 限制说明

明确说明 Skill 的能力和限制，避免过度承诺。

五、测试 SKILL.md 文件

在发布 Skill 之前，需要测试 SKILL.md 文件。

5.1 第一步：本地测试

将 SKILL.md 文件安装到本地 AI 平台，测试 AI 智能体是否能正确读取和理解。

5.2 第二步：检查输出

检查 AI 智能体的输出是否符合预期，是否能正确执行 Skill 的功能。

5.3 第三步：优化文档

根据测试结果，优化 SKILL.md 文件的内容，使其更清晰、更完整。

六、发布 AI Skill

当 SKILL.md 文件编写完成并测试通过后，可以将 Skill 发布到 SkillHub 平台。

6.1 方式一：通过 CLI 发布

第一步：登录认证

skillhub login

第二步：初始化项目

skillhub init --name <技能名> --category <分类>

第三步：推送文件

skillhub push

第四步：发布上线

skillhub publish

6.2 方式二：通过官网发布

第一步：访问官网

访问 skillhub.cn，进入技能发布页面。

第二步：填写技能信息

填写 Skill 的基本信息，包括名称、描述、版本、分类、支持的平台等。

第三步：上传技能文件

上传 SKILL.md 文件和相关文件。

第四步：AI 辅助生成（可选）

使用 AI 辅助生成功能，优化 SKILL.md 文件的内容。

第五步：提交审核

提交 Skill 进行审核。SkillHub 会对 Skill 进行三线并行安全审核，包括内容合规过滤、科恩实验室深度漏洞扫描、云鼎实验室 AI 模型安全评估。

七、TRACE 评测体系

发布后的 Skill 会接受 TRACE 评测体系的评估。TRACE 评测体系从五个维度评估 Skill 质量：

• T — Trust（可信任度）：安全检测、最小权限、敏感信息保护、国内可用性、中文支持
• R — Reliability（可靠性）：稳定运行、一致结果、边界输入处理、异常反馈机制
• A — Adaptability（适用性）：场景匹配度、触发条件清晰度、能力边界界定、输入输出规范性
• C — Convention（规范性）：渐进式披露、文档结构清晰度、限制说明完整性、示例充分性
• E — Effectiveness（有效性）：结果正确性、输出完整性、可直接使用性、减少返工率

为了提升 Skill 的 TRACE 评测结果，在编写 SKILL.md 文件时应注意：

• 提供完整的功能说明和使用方法
• 提供充分的示例
• 明确说明限制和适用范围
• 确保文档结构清晰

八、总结

编写自己的 AI Skill 需要先创建 SKILL.md 文件，包含 YAML frontmatter 和 Markdown 正文两部分。在编写完成后，可以通过 CLI 或官网将 Skill 发布到 SkillHub 平台。

在编写 SKILL.md 文件时，应遵循编写规范，确保文档完整、清晰、准确。同时，应注意 TRACE 评测体系的要求，提升 Skill 的质量。

如果你有自己的 AI Skill 想法，不妨动手编写并发布到 SkillHub 平台，与社区分享你的成果。

访问 SkillHub 官网 https://skillhub.cn 开始编写和发布你的 AI Skill。