免责声明：本内容来自https://www.cnblogs.com/liuyanhang/p/19678364,本站系信息发布平台，仅提供信息存储空间服务。

#编写 SKILL.md 文档时，核心在于理解它的双重身份：它既是 AI 识别技能的“名片”（元数据），又是 AI 执行任务的“操作手册”（指令）。

基于目前的最佳实践和主流标准（如 Anthropic 的 Agent Skills 规范），我为你总结了必须遵守的格式规范和需要重点描述的方面。

📝 核心格式规范#

SKILL.md 文件必须严格遵循 YAML Frontmatter（元数据） + Markdown Body（正文） 的结构。

1. YAML Frontmatter（头部元数据）#

这是文件的最顶部，用 --- 包裹。它是 AI 在决定是否调用该技能时唯一会读取的部分，因此至关重要。

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 怎么写：

1. 触发机制 (Trigger)：

   • 思考：用户说什么话时，我应该跳出来帮忙？

   • 落实：写在 description 中。例如：“当用户提到‘打包’、‘部署’或发送 GitHub 链接时”。

2. 确定性 vs. 自由度 (Determinism)：

   • 思考：这个任务是必须严格按步骤来（如填写税务表单），还是可以灵活发挥（如写营销文案）？

   • 落实：如果是前者，在 Instructions 中写死步骤，并配合 scripts/ 脚本执行；如果是后者，给予 AI 更多基于文本的指导。

3. 上下文管理 (Context Management)：

   • 思考：完成任务需要大量参考资料吗（如 API 文档、公司制度）？

   • 落实：不要把这些长文本塞进 SKILL.md！将它们放入 references/ 文件夹，并在 SKILL.md 中指示 AI“按需读取”。

4. 容错与边界 (Error Handling)：

   • 思考：如果任务失败了（如文件找不到、格式错误），AI 该怎么办？

   • 落实：在 Instructions 中加入错误处理指南，例如“如果脚本执行报错，请将错误日志完整返回给用户，不要尝试自行修复”。

📌 总结：一个优秀的 SKILL.md 结构模板#

复制---
name: [技能标识名]
description: [一句话描述功能 + 触发场景 + 核心价值]
version: 1.0.0
---

# [技能名称]

## 角色定义
你是一名 [具体角色]，擅长 [核心能力]。

## 核心指令
请严格按照以下步骤执行任务：
1. **分析意图**：[步骤说明]
2. **查阅资料**：如果需要，读取 `references/[文件名]` 获取详细信息。
3. **执行操作**：运行 `scripts/[脚本名]` 处理数据。
4. **输出结果**：按照下方的输出格式要求生成回答。

## 输出格式
- 必须包含：[要素 A]、[要素 B]
- 风格：[专业/幽默/简洁]

## 示例
**用户输入**：[示例提问]
**你的回答**：[示例回答]

## 错误处理
如果遇到 [某种错误]，请 [执行某种操作]。