编写 SKILL.md 文档时，核心在于理解它的双重身份：它既是 AI 识别技能的“名片”（元数据），又是 AI 执行任务的“操作手册”（指令）。
基于目前的最佳实践和主流标准（如 Anthropic 的 Agent Skills 规范），我为你总结了必须遵守的格式规范和需要重点描述的方面。
📝 核心格式规范
SKILL.md 文件必须严格遵循 YAML Frontmatter（元数据） + Markdown Body（正文） 的结构。
1. YAML Frontmatter（头部元数据）
这是文件的最顶部，用 --- 包裹。它是 AI 在决定是否调用该技能时唯一会读取的部分，因此至关重要。
| 字段 | 是否必需 | 描述与规范 |
|---|---|---|
| name | 必需 | 技能的唯一标识符。通常使用小写字母和连字符（如 pdf-form-filler）。 |
| description | 必需 | 核心中的核心。用 1-2 句话描述技能的功能、适用场景和触发条件。AI 仅凭此判断是否加载技能。 |
| version | 可选 | 版本号（如 1.0.0），用于管理迭代。 |
| author | 可选 | 作者或团队名称。 |
| allowed-tools | 可选 | 定义技能可自动使用的工具列表（如 Bash, Read），无需用户每次确认。 |
YAML 示例：
---
name: meeting-auditor
description: 用于分析商务会议录音文本，提取关键决策，并根据合规手册审计预算风险。当用户要求“检查会议记录合规性”或“总结会议并审计”时触发。
version: 1.0.0
---
2. Markdown Body（正文指令）
这是技能被触发后，AI 才会读取的详细内容。它指导 AI 如何一步步完成任务。
🎯 需要重点描述的方面（正文内容）
在 Markdown 正文中，你需要从以下几个方面来构建 AI 的“思维链”和“行动指南”：
1. 角色定义 (Role Definition)
明确告诉 AI 它现在的身份。
- 描述方面：赋予 AI 一个具体的专家人设。
- 示例：“你是一名严谨的财务审计员”或“你是一名资深的 Python 代码审查专家”。
2. 核心指令与步骤 (Instructions & Steps)
这是文档的主体，必须使用祈使句（命令式语气），清晰、分步骤地描述操作流程。
- 描述方面：
- 任务拆解：将复杂任务分解为步骤 1、2、3。
- 逻辑判断：告诉 AI 在不同情况下该如何选择（例如：“如果 PDF 有密码，先调用解密脚本；如果没有，直接读取”）。
- 工具调用：明确指示何时运行
scripts/中的脚本或查阅references/中的文档。
3. 输出规范 (Output Format)
规定 AI 最终呈现给用户的内容格式。
- 描述方面：
- 结构：例如“必须包含：摘要、风险点、建议措施三个部分”。
- 风格：例如“使用表格展示数据对比”或“代码块必须包含注释”。
4. 示例 (Examples)
提供“少样本学习”（Few-Shot Prompting）的案例，帮助 AI 理解意图。
- 描述方面：
- 输入/输出对：展示一个用户提问的例子，以及你期望的标准回答格式。
- 触发词示例：明确列出哪些用户语句会触发此技能（如“帮我打包这个项目”）。
5. 资源引用 (References & Assets)
指导 AI 如何使用技能包内的外部文件。
- 描述方面：
- 何时读取：例如“在执行审计前，必须先阅读
references/compliance_rules.md”。 - 如何使用：例如“使用
assets/template.pptx作为生成报告的模板”。
- 何时读取：例如“在执行审计前，必须先阅读
🚀 需求分析与编写清单
如果你有一个新需求，在动笔之前，请从以下 4 个维度 进行思考，这将决定你的 SKILL.md 怎么写：
-
触发机制 (Trigger)：
- 思考：用户说什么话时，我应该跳出来帮忙？
- 落实：写在
description中。例如：“当用户提到‘打包’、‘部署’或发送 GitHub 链接时”。
-
确定性 vs. 自由度 (Determinism)：
- 思考：这个任务是必须严格按步骤来（如填写税务表单），还是可以灵活发挥（如写营销文案）？
- 落实：如果是前者，在
Instructions中写死步骤，并配合scripts/脚本执行；如果是后者，给予 AI 更多基于文本的指导。
-
上下文管理 (Context Management)：
- 思考：完成任务需要大量参考资料吗（如 API 文档、公司制度）？
- 落实：不要把这些长文本塞进
SKILL.md！将它们放入references/文件夹，并在SKILL.md中指示 AI“按需读取”。
-
容错与边界 (Error Handling)：
- 思考：如果任务失败了（如文件找不到、格式错误），AI 该怎么办？
- 落实：在
Instructions中加入错误处理指南，例如“如果脚本执行报错，请将错误日志完整返回给用户，不要尝试自行修复”。
📌 总结：一个优秀的 SKILL.md 结构模板
---
name: [技能标识名]
description: [一句话描述功能 + 触发场景 + 核心价值]
version: 1.0.0
---# [技能名称]## 角色定义
你是一名 [具体角色]，擅长 [核心能力]。## 核心指令
请严格按照以下步骤执行任务：
1. **分析意图**：[步骤说明]
2. **查阅资料**：如果需要，读取 `references/[文件名]` 获取详细信息。
3. **执行操作**：运行 `scripts/[脚本名]` 处理数据。
4. **输出结果**：按照下方的输出格式要求生成回答。## 输出格式
- 必须包含：[要素 A]、[要素 B]
- 风格：[专业/幽默/简洁]## 示例
**用户输入**：[示例提问]
**你的回答**：[示例回答]## 错误处理
如果遇到 [某种错误]，请 [执行某种操作]。