Skill 编写指南：目录结构、参数与写法详解

应用场景

SKILL.md 规范是目前AI领域快速兴起的”技能包”标准。它可以帮你把日常的提示词和工作流程，封装成像App一样可复用的模块。

第一类：AI编程助手（开发者常用）

在开发工具中，Skill最广泛的应用是扩展AI的编码能力，比如自动化代码审查、生成项目文档等。

• Cursor：一款智能代码编辑器。它支持从项目中的 .cursor/skills/ 目录读取 SKILL.md 文件
• Claude Code：Anthropic 推出的命令行AI工具。它会读取项目或用户目录下的 .claude/skills/

 

第二类：AI智能体平台与社区（应用生态）

这类平台将SKILL.md作为其”应用商店”或”技能市场”的标准格式，让用户能发现和安装各种AI能力。

• ClawHub：一个专注于AI技能的市场，类似”Docker Hub”但针对Skill。目前已收录超过5.2万个技能，总下载量超1200万。
• 字节跳动、腾讯、飞书：旗下多闪、元宝、龙虾等平台也都有各自的”技能广场”或”智能体技能市场”

一、Skill 是什么？

Skill 是一套定义AI专属能力的标准化文件夹工程，核心作用是给AI设定明确的岗位职责、执行流程、输入输出规则与质量标准。

Skill = 一个文件夹 里面至少包含一个 SKILL.md 文件，用来定义 AI 的能力、流程和限制。

通俗类比：Skill = AI的岗位说明书 + 标准化操作手册 + 质量验收规范。

---

二、最小 Skill 结构

my-first-skill/
└── SKILL.md

✅ 只要一个文件，Skill 就能运行
✅ 先跑通，再逐步增强

---

三、目录结构解剖

my-skill/
├── SKILL.md          # 🧠 大脑：核心定义（必填），包含工作流与规则
├── agents/           # 🎭 人设：角色配置与展示信息（可选）
├── references/       # 📚 知识库：长文档、API 文档、背景资料（可选）
├── scripts/          # 🛠️ 工具：Python/Shell 脚本，处理确定性逻辑（可选）
└── assets/           # 📦 素材：模板文件、图片、字体、样例数据（可选）

各模块职责详解

模块	核心作用	最佳实践
SKILL.md	定义能力与流程。决定 AI 什么时候触发，以及触发后怎么做。	使用清晰的步骤和检查清单，避免模糊的自然语言。
agents/	定义交互体验。控制在 UI 中的显示名称和开场白。	编写 openai.yaml 或 anthropic.yaml，设定“资深专家”的人设。
references/	提供上下文。存放 AI 记不住的长篇文档（如 Style Guide）。	将大文档拆分为小模块，方便 AI 快速检索（RAG）。
scripts/	执行硬逻辑。处理计算、文件转换等 AI 容易出错的任务。	遵循“AI 编排，脚本执行”原则，脚本需自带验证功能。
assets/	标准化输出。提供 Markdown/JSON 模板，确保输出格式统一。	模板中用 {{variable}} 标记需替换的变量。

---

四、SKILL.md 编写规范详解

SKILL.md 是 Skill 的灵魂。它由 Frontmatter（元数据） 和 Body（执行指令） 两部分组成。

1. Frontmatter：身份与触发机制

这是 YAML 格式的配置区，决定了 Skill 的“身份ID”和“触发灵敏度”。

---
name: weekly-report-helper            # 唯一标识：小写+连字符
description: >                        # 触发核心：决定 AI 何时调用此 Skill
  帮助运营人员自动生成周报。
  适用于分析 CSV 数据、总结核心指标变化。
  当用户说“写周报”、“分析数据”、“出复盘”时触发。
author: chinapmcc.com
version: 1.0.0
tags: [数据分析, 周报, 自动化]
---

关键参数解析：

● name：Skill 的身份证。一旦发布，不要用下划线或大小写混用，尽量不要改名，否则会导致历史记录失效。

● description：最重要的字段。

○ 公式：做什么（能力） + 什么时候用（场景） + 用户会怎么说（触发词）。

○ 技巧：描述越具体，AI 误触发率越低。

参数	必填	说明
name	✅	唯一标识，小写+连字符
description	✅	能力+场景+触发词
author	否	作者名
version	否	版本号
tags	否	分类标签

2. Body：执行指令（Prompt Engineering）

Body 是 AI 的执行脚本（“操作手册”）。不要写空话，要写可执行的流程，要可操作、可检查。

推荐的正文结构

# 核心目标
生成一份结构清晰的周报，包含核心指标变化、问题诊断和下步建议。

# 工作流程 (Workflow)
1. **数据读取**：读取用户上传的 CSV 或粘贴的数据。
2. **数据计算**：调用 `scripts/calc_change.py` 计算环比、同比数据。
3. **异常检测**：识别波动超过 20% 的指标。
4. **内容生成**：参考 `references/style_guide.md` 的语气，填充 `assets/template.md`。

# 输入规则
- 必须包含日期、指标值。
- 至少需要 2 个时间周期的数据对比。

# 输出格式
- 使用 Markdown 表格展示数据。
- 结论部分包含：3 条核心结论 + 2 条可执行建议。

# 质量检查 (Self-Correction)
在输出前，请自查：
- [ ] 是否解释了所有异常波动？
- [ ] 建议是否具体可执行（非废话）？
- [ ] 数据计算是否与脚本输出一致？

核心目标

明确要达成什么结果

• 解决什么问题？
• 达到什么效果？
• 成功的标准是什么？

工作流程

按顺序拆解可执行的步骤

• 一步步做什么？
• 每一步的产出是什么？
• 需要用到哪些工具？

输入规则

明确输入要求与使用条件

• 需要哪些输入信息？
• 输入格式是什么？
• 有哪些限制条件？

输出格式

定义输出结构与呈现方式

• 输出什么内容？
• 用什么格式呈现？
• 包含哪些字段/模块？

质量检查

确保结果达标与可用

• 如何自检？
• 检查哪些关键点？
• 不符合怎么办？

1.少讲背景，多讲流程
2.用清单和步骤更清晰
3.具体可执行，AI才靠谱

---

“外挂装备库”

它们的核心作用是将非自然语言的任务（如计算、格式化）从 AI 的大脑中剥离出来，交由更可靠的工具处理。

🎭 1. agents/ —— 角色配置与展示信息

📌 核心作用：
定义 AI 的“人设”和交互体验。它决定了用户在界面上看到的名称、简介，以及 AI 首次开口时的语气。这个目录通常包含配置文件（如 openai.yaml 或 anthropic.yaml）。

💡 典型内容：
显示名称（Display Name）、简短描述（Short Description）、默认系统提示词（Default Prompt）。

🛠️ 使用示例：
假设你在做一个代码审查助手，你可以创建一个 agents/openai.yaml 文件：

interface:
  display_name: 资深架构师老王
  short_description: 专注高并发系统的代码审查与性能调优建议。
  default_prompt: >
    你好！我是你的专属架构师老王。我拥有 10 年分布式系统经验。
    请把代码发给我，我会重点检查内存泄漏、锁竞争和 SQL 慢查询问题。
    我的点评风格直接犀利，不讲废话。

---

📚 2. references/ —— 知识库与背景资料

📌 核心作用：
存放长篇文档、规范指南或 API 手册。当任务涉及大量上下文时，AI 无法靠记忆记住所有细节。将这些资料放在这里，AI 可以在执行过程中按需检索（RAG），从而保持回答的专业性和准确性。

💡 典型内容：
公司代码规范（Style Guide）、产品需求文档（PRD）、API 接口说明、历史复盘报告。

🛠️ 使用示例：
你希望 AI 按照公司的严格标准写 PR，可以在该目录下放入 company_pr_rules.md。然后在 SKILL.md 中这样引用：

## 工作流程
1. 接收用户的开发需求。
2. 读取 `references/company_pr_rules.md`，确保生成的 PR 描述符合团队规范。
3. 根据规范模板生成 Markdown 格式的 PR 文本。

---

🛠️ 3. scripts/ —— 确定性逻辑与自动化工具

📌 核心作用：
处理 AI 不擅长的“硬逻辑”。大模型本质上是概率预测机，做数学计算、正则提取或文件转换时极易出错（幻觉）。将这类任务写成 Python 或 Shell 脚本，让 AI 充当“指挥官”，只负责调用脚本并解读结果。

💡 典型内容：
数据清洗脚本、格式转换工具、环境依赖安装器、单元测试运行器。

🛠️ 使用示例：
用户要求分析一份 50MB 的 CSV 销售日志，找出异常订单。不要让 AI 去读 CSV，而是写一个 scripts/find_anomalies.py。在 SKILL.md 中编排：

## 工作流程
1. 获取用户提供的 CSV 文件路径。
2. 执行命令：`python scripts/find_anomalies.py --input <file_path>`。
3. 捕获脚本的标准输出（JSON 格式的异常订单列表）。
4. 用通俗易懂的语言向用户解释这些异常订单的原因。

---

📦 4. assets/ —— 静态素材与标准化模板

📌 核心作用：
提供标准化的输出骨架或多媒体资源。当你需要 AI 每次输出的格式都完全一致（例如固定的邮件模板、特定的 JSON 结构），或者需要附带图片/字体时，这个目录是最佳选择。

💡 典型内容：
Markdown 模板、JSON/YAML 结构样例、占位图、品牌 Logo。

🛠️ 使用示例：
你需要 AI 帮你给客户发送标准化的周报邮件。在 assets/ 下放置 weekly_email_template.md：

# {{client_name}} 项目周报 ({{date}})

## 🚀 本周进展
- {{progress_1}}
- {{progress_2}}

## ⚠️ 风险与阻碍
- {{risks}}

在 SKILL.md 中指示 AI 填空：

## 输出规则
1. 收集本周的项目进度和风险点。
2. 打开 `assets/weekly_email_template.md`。
3. 将收集到的信息填入对应的 `{{variable}}` 变量中。
4. 仅输出最终的完整邮件正文，不要包含任何解释性废话。

这四个目录并不是孤立的，它们通常在 SKILL.md 的工作流中被串联起来。一个完整的自动化流程通常是这样的：

“以 agents/ 中的专家身份，参考 references/ 中的规范文档，调用 scripts/ 完成数据处理，最后套用 assets/ 中的模板输出最终结果。”

---

五、最终建议

• ✅ 从最小结构开始
• ✅ 先写清楚 description
• ✅ Body 用流程 + 清单
• ✅ 资源按目录分开
• ✅ 给一个真实示例测试

一个好的 Skill，不是堆字数，而是让 AI 一看就懂、一跑就对。