如何用 Markdown 编写 AI Agent 的 SKILL.md 与工具描述

当 AI 助手能够遵循稳定的指令、加载特定领域的知识并安全地调用外部工具时，它们才会变得极其有用。Markdown 是编写这些配置和指令最理想的格式，因为它既能被人类轻松阅读和进行版本控制，又拥有能够被大语言模型精确解析的逻辑结构。

本文将详细探讨如何为 AI Agent 编写基于 Markdown 的 SKILL.md（技能描述文件）、Agent 系统指令文件以及工具使用描述。我们这么做的核心目的并不是为了把提示词写得更长，而是为了让 AI Agent 能够更加轻松地发现、理解并在正确的时机调用其拥有的能力。

什么是 SKILL.md 文件

SKILL.md 文件是一个专门描述某项可复用能力的 Markdown 指令文件。在 Anthropic 的 Claude Code 等 Agent 系统中，技能（Skills）作为文件系统中的特殊产物存储在专门的目录里，每一个技能都由一个对应的 SKILL.md 文件来定义。尽管在不同的 Agent 框架中，此类文件的具体名称可能有所不同，但其背后的核心理念是一致的：用一个简短、结构化的文档，清晰地告知 Agent在什么场景下应该使用该项能力、需要遵循什么样的工作流，以及相关的辅助脚本或参考资料存放在哪里。

我们可以建立一个非常简单直观的心智模型：

• 普通提示词（Prompt）：告诉 AI 此时此刻具体要做什么。
• 技能（Skill）：教会 AI 以后如何重复完成某一类特定的任务。
• 工具描述（Tool Description）：告诉 AI 何时以及如何去调用某个具体的外部函数或服务接口。

由于技能主要由行为指令、执行步骤、约束条件和相关参考文件组成，因此 Markdown 是承载这一内容最天然、最完美的格式。

为什么 Markdown 如此适合编写 Agent 技能

Agent 技能指令文件需要服务于两位读者：大语言模型（LLM）和人类维护者。Markdown 恰好能完美兼顾这两者。

对于 AI 来说，Markdown 的标题和列表能把触发条件、执行步骤、约束限制、few-shot 示例以及异常退路清晰地划分开。对于人类开发者来说，同样的文件可以在 Git 中进行版本对比评审（Review），在任意编辑器中轻松修改，并且可以直接作为项目文档的一部分与代码存放在一起。

这一点在设计技能和工具时尤为关键，因为含糊不清的指令极易导致自动化工作流出错。例如，一个定义模糊的技能可能会在错误的场景下被误触发；一个粗糙的工具描述可能会导致模型在调用 API 时传入错误的参数；而如果遗漏了安全提示，Agent 甚至可能在没有充足证据的情况下擅自执行高危操作。

技能（Skills）与工具描述（Tool Descriptions）的区别

技能与工具密切相关，但它们的分工和维度不同：

| 要素 | 核心目的 | 典型示例 | |---|---|---| | 技能 (Skill) | 传授一套可复用的工作流或特定领域的标准操作规程 | "如何评审并合并一个 Pull Request" | | 工具描述 (Tool) | 告知模型某个可调用函数的作用、入参格式及返回结果 | "通过查询语句搜索 GitHub Issues" | | 系统提示词 (System Prompt) | 设定助手的全局人设、语气风格和底层行为准则 | "回答请保持简明扼要，且必须验证事实" | | 项目指令文件 (Project Rules) | 阐述本地代码仓库的特有规范与运行限制 | "请使用 pnpm，且在未要求前不要执行构建" |

根据 OpenAI 的 Function Calling 以及各主流 Agent SDK 的官方文档，工具（Tools）是模型或 Agent 获取外部数据、调用第三方 API、执行代码或越过模型自身边界进行交互的手段。官方指南强烈建议：工具描述应当保持简短、精确，聚焦于“工具能干什么”以及“何时应该调用它”。这套准则同样适用于 Markdown 技能：务必对激活场景和核心用途做到极其具体和明确。

一个实用的 SKILL.md 模板结构

一个真正实用的技能描述文件应该清晰回答以下六个问题：

1. 这个技能能提供什么能力？
2. Agent 在什么情况下应当激活该技能？
3. 在什么情况下绝对不应该使用该技能？
4. Agent 执行该技能时需要遵循哪些具体步骤？
5. 有哪些现成的本地文件、脚本或参考资料可供配合使用？
6. 最终输出的内容应该是什么格式？

以下是一个可以直接套用的标准模板：

---
name: markdown-conversion-review
description: 当用户需要审查、优化或清理从 PDF、Office 格式或网页转换而来的 Markdown 文档时，请使用该技能。
---

# 技能名称：Markdown 转换质量评审

## 激活场景 (Use This Skill When)
- 用户要求对转换后的 Markdown 进行清理或润色。
- 用户需要将某份文档转换为适合 README、官方文档、博客或 AI 提示词使用的格式。
- 源文本中包含排版残缺的表格、混乱的标题层级、丢失的链接或闭合错误的代码块。

## 排除场景 (Do Not Use This Skill When)
- 用户只是在询问 Markdown 语法的概念或基础教学。
- 任务需要修改当前处理文档之外的其他不相关源文件。

## 标准执行工作流 (Workflow)
1. **第一步：结构审查**。检查转换后的 Markdown 是否存在层级混乱、表格变形、链接失效和代码块闭合错误等问题。
2. **第二步：意图保护**。在清理过程中必须严格保留作者的原始逻辑和表达顺序，除非用户明确要求你进行重写。
3. **第三步：规范化排版**。使用简洁、标准的 Markdown 语法规范标题、列表、超链接和表格的格式。
4. **第四步：局限性标注**。如果发现某些源文件的排版格式实在无法可靠还原，必须在文档末尾予以标注。
5. **第五步：输出成果**。向用户返回清理规范后的 Markdown 正文以及简短的修改备注。

## 质量要求与约束 (Quality Bar)
- 严禁捏造源文档中不存在的信息。
- 除非用户特别要求，否则必须完整保留原始代码块的内容。
- 优先选用简洁的纯 Markdown 语法，尽量避免嵌套复杂的 HTML 标签。

## 期望输出格式 (Output Format)
按以下顺序返回：
1. 规范清理后的 Markdown 文本。
2. 修改备注与转换决策说明。
3. 遗留或无法解决的排版问题清单。

上面的 Frontmatter（前置元数据）字段可以根据你使用的具体 Agent 系统（例如 Claude Code 的 skills 规范）进行调整。文档主体的逻辑框架（触发条件、排除场景、执行工作流、质量边界、输出格式）则是完全通用的。

如何撰写高质量的描述（Description）字段

在技能或工具的定义中，description 描述字段往往是最核心的要素，因为 Agent 通常正是基于该字段来进行语义路由，从而决定是否加载某项能力。

糟糕的描述写法：

description: 帮助处理 Markdown。

优秀的描述写法：

description: 当用户需要对转换后的 Markdown 文档进行清理、排版规范化，或者将其整理用于技术文档、项目 README、博客文章及 AI 提示词上下文时，请调用该技能。

一个合格的描述应该包含：

• 触发时机：“当用户需要……时”
• 核心操作：“清理、排版规范化，或者将其整理用于……”
• 处理对象：“转换后的 Markdown 文档”
• 适用场景：“技术文档、项目 README、博客文章及 AI 提示词上下文”

如何编写工具使用描述（Tool Descriptions）

相比于技能文件，工具（Tool）的描述应该更加短小精悍。工具是一种具体的 API 操作，因此大语言模型只需要三个极其明确的答案：

• 该工具具体做什么？
• 什么时候该用它（以及什么时候不该用）？
• 它需要什么样格式的输入参数？

JSON 格式的工具定义示例：

{
  "name": "convert_file_to_markdown",
  "description": "当用户上传了 PDF、DOCX、PPTX、XLSX、HTML 或图片文件，并希望将其转换为可编辑的文本或适合 AI 读取的结构化内容时，使用该工具将其转换为 Markdown 格式。",
  "parameters": {
    "type": "object",
    "properties": {
      "file_id": {
        "type": "string",
        "description": "已上传文件的唯一标识 ID。"
      },
      "preserve_tables": {
        "type": "boolean",
        "description": "是否尝试将文档中的表格提取并转换为 Markdown 格式的表格，默认为 true。"
      }
    },
    "required": ["file_id"]
  }
}

上面的描述没有假大空的修饰词，而是直奔主题地写清了支持的文件类型、触发意图和参数细节。这样可以显著降低 AI 的误用率，并提升传参的准确度。

技能文档化：用 Markdown 记录工具手册

如果你的项目中有许多在代码中定义的 API 工具，用 Markdown 为它们编写一份面向 AI 的“使用手册”是一个非常聪明的做法：

# 工具参考手册：convert_file_to_markdown

## 核心功能
将支持的文档文件转换为 Markdown 格式。

## 推荐调用场景
- 用户上传了文件，并直接要求转换为 Markdown。
- 用户希望对某份文档的内容进行 LLM 分析、生成 README、编写官方文档或博客。

## 禁用场景
- 用户仅仅是在咨询关于 Markdown 的概念性问题。
- 输入数据已经是干净的 Markdown，不需要做任何二次转换。

## 入参说明
| 参数名 | 类型 | 是否必填 | 备注与说明 |
|---|---|---:|---|
| file_id | string | 是 | 上传文件的唯一标识符 |
| preserve_tables | boolean | 否 | 是否尽可能保留表格结构 |

## 期望输出
转换后的 Markdown 纯文本以及转换备注。

## 异常与失败处理
- 如果传入了不支持的文件类型，向用户友好地提示所支持的格式列表。
- 如果无法还原原始布局，返回最佳的文本提取结果，并如实注明格式局限性。

这种做法在工具定义写在代码里，但 Agent 需要额外的“操作指南”来避免犯错时非常管用。

什么样的技能才是真正高效的

一个写得好的技能应该是极具实操性的，能够切实帮助 Agent 在复杂的执行过程中做出正确的决策。

1. 触发界限极其清晰

不要使用宽泛、抽象的标题，明确告知触发的时机。

糟糕的触发定义：

# SEO 技能

优秀的触发定义：

## 激活场景
- 用户要求优化某个页面以提升其在搜索引擎中的表现。
- 内容需要补充 Meta 标题、Meta 描述、清晰的 H2/H3 标题、内部链接或常见问题解答（FAQ）。
- 用户提到了 E-E-A-T 原则、搜索引擎有用内容（Helpful Content）评估或低质量内容整改。

2. 明确划定非目标（Non-Goals）

明确写出“不该做什么”往往和“该做什么”一样重要，这能有效防止 Agent 越界或滥用能力。

## 禁用场景
- 用户在咨询法律、医疗或财务等需要专业资质的建议。
- 任务要求虚构用户好评、捏造统计数据、伪造参考文献或用户留存数据。
- 目标页面与我们的产品线或用户实际意图毫无关联。

3. 提供可落地的步骤

技能中应该包含在复杂或高压环境下也清晰可执行的工作流程。步骤应当具体到能指导行为，但又不至于细碎到容易让 Agent 失去弹性。

4. 提供“好”与“坏”的具体样例

在与 AI 沟通时，具体的示例（Example）往往胜过一万个形容词。

## 文案风格示例

- **避免使用（糟糕的写法）**：
  “我们革命性的转换器保证能完美无瑕地转换任何类型的文档。”
  *(原因：措辞夸张虚浮，容易引起不信任感。)*

- **推荐使用（优秀的写法）**：
  “该转换器能够将文档内容提取为 Markdown 格式。当源文件拥有清晰的标题、规则的表格和纯文本内容时，转换效果最佳。”
  *(原因：实事求是，同时指明了价值和局限性。)*

5. 明确安全与权限的边界

如果你的技能涉及运行本地脚本、调用 API 或修改敏感文件，务必确立安全边界：

## 安全边界与权限
- 在对任何文件进行编辑写入前，必须先完整读取其内容。
- 绝不主动删除用户的本地文件，除非收到了非常明确的删除指令。
- 在向外部不受信任的 API 发送数据前，必须征得用户的确认。

常见设计误区

• 误区 1：把一个技能塞得太满：一个技能应当只聚焦于一件连贯的事。如果把 SEO 优化、流量分析、文案撰写、广告政策审核和邮件分发都塞进一个“营销技能”里，Agent 很容易在理解上发生混乱。
• 误区 2：使用假大空的修饰词：避免在指令中写“请写出世界一流的代码”或“让文案看起来惊艳”。AI 根本无法量化这些形容词。使用可观测的指标代替，例如“确保包含来源超链接”、“列出核心假设”、“字数少于 150 字”。
• 误区 3：把关键规则藏在长篇大论中：如果一条规则至关重要，请用无序列表（Bullet points）单独列出。AI 和人类一样，对于列表的关注度远远高于冗长段落中间的句子。
• 误区 4：缺失异常与失败处理：工具会超时，输入会残缺，文件会损坏。确保在技能中包含一条“如果失败了，下一步该怎么办”的指示。

总结

基于 Markdown 的 SKILL.md 和工具描述，是教导 AI Agent 掌握专业技能、同时避免其偏离轨道的最佳方案。最优秀的描述文档往往简短、聚焦且完全以执行为导向。

如果你正在围绕文档转换、知识库构建或自动化工具开发 AI 工作流，编写规范的 SKILL.md 将是连接人类流程经验与 AI 稳定执行之间最稳固的桥梁。

参考资料与延伸阅读

• Claude 官方文档：Agent Skills 技能设计
• Claude Code 开发指南：Agent SDK 中的 Skills
• OpenAI API：Function Calling 函数调用指南
• OpenAI Agents SDK：工具设计规范