Agent Skill 编写规范与 Markdown 语法实战指南
·
📃个人主页：编程的一拳超人
⛺️ 欢迎关注：👍点赞 👂🏽留言 😍收藏 💞 💞
💞
于高山之巅，方见大河奔涌；于群峰之上，更觉长风浩荡。 ——《人民日报》
Agent Skill 编写规范与 Markdown 语法实战指南
本文档融合 Agent Skill 编写标准与 Markdown 语法规则，既是编写规范，也是可直接复用的模板手册，可直接用于编写标准化的 Skill 文件。
一、概述
1.1 核心定义
Agent Skill 是指导智能体完成特定任务的标准化指令文档，默认以 SKILL.md 为文件名，采用 Markdown 语法编写。编写 Skill 文件的过程，本质是 Markdown 语法在「技术指令文档」场景下的专项应用。
1.2 文档用途
- 统一 Skill 文件的结构与格式规范，确保可读性与可执行性
- 同步讲解对应 Markdown 语法的写法与适用场景，边用边学
- 提供可直接复制的完整模板，降低编写门槛
1.3 标准 Skill 文件结构
一个完整的 Skill 文件固定包含以下模块，按顺序排列：
- 元数据区（Front Matter）
- 技能概述
- 触发规则
- 输入参数说明
- 执行流程
- 输出规范
- 示例与模板
- 注意事项与边界
- 自检清单与版本记录
二、分模块编写指南（含对应 Markdown 语法）
2.1 元数据区（Front Matter）
编写要求
放在文件最开头，用于声明技能的基础信息，由系统读取识别，不参与正文渲染。采用 YAML 键值对格式，字段可扩展，核心字段不可缺失。
对应 Markdown 语法
Front Matter 元数据语法：以 --- 包裹的 YAML 代码块，位于文件首行。
代码示例
---
name: skill-demo-document
version: 1.0.0
description: 用于生成标准化技术文档的技能，支持结构化排版与格式校验
trigger: 当用户需要编写技术文档、规范文档、接口文档时触发
tags: [文档编写, 格式规范, Markdown]
author: 系统开发组
date: 2024-01-01
---
2.2 技能概述
编写要求
用简洁的语言说明技能的核心功能、解决的问题、适用范围，让使用者快速理解技能定位。
对应 Markdown 语法
- 分级标题：用
#####划分层级 - 段落与换行：空行分段，行尾双空格强制换行
- 字体样式：加粗标注核心关键词，
行内代码标注专有名词 - 引用块：
>用于标注核心定位一句话总结
代码示例
## 技能概述
本技能用于标准化输出技术类说明文档，统一文档结构与排版格式，确保输出内容专业、规范、可读性强。
> 核心定位：结构化文档生成 + 格式自动校验
### 能力范围
- 支持技术方案、接口文档、操作手册三类文档生成
- 自动套用标准排版规范，统一标题层级与代码格式
- 自动生成文档目录与章节锚点
2.3 触发规则与适用场景
编写要求
明确列出技能的触发条件、适用场景、不适用场景，避免技能被误用。
对应 Markdown 语法
- 无序列表：并列项使用
-罗列 - 有序列表：有先后顺序的规则用
1. 2. 3. - 任务列表：
- [ ]用于勾选式判断条件
代码示例
## 触发规则
### 触发条件
满足以下任意一项即可触发本技能：
1. 用户明确提出「写技术文档、接口文档、操作手册」等需求
2. 用户提供零散的技术要点，要求整理成正式文档
3. 用户提到「规范格式、统一排版」等文档优化需求
### 适用场景
- [ ] 项目技术方案编写
- [ ] API 接口说明文档整理
- [ ] 系统操作手册输出
### 不适用场景
- 创意文案、营销软文类写作
- 纯表格数据整理
- 法律、医疗等专业领域合规文档
----
效果：
触发规则
触发条件
满足以下任意一项即可触发本技能：
- 用户明确提出「写技术文档、接口文档、操作手册」等需求
- 用户提供零散的技术要点，要求整理成正式文档
- 用户提到「规范格式、统一排版」等文档优化需求
适用场景
- 项目技术方案编写
- API 接口说明文档整理
- 系统操作手册输出
不适用场景
- 创意文案、营销软文类写作
- 纯表格数据整理
- 法律、医疗等专业领域合规文档
2.4 输入参数说明
编写要求
清晰列出技能所需的输入参数，包含参数名、数据类型、是否必填、说明，是技能执行的核心依据。
对应 Markdown 语法
- 表格语法：
| 列名 | 列名 |配合分隔线实现表格排版 - 对齐方式：通过冒号控制表格列左对齐、居中、右对齐
- 行内代码：参数名用 ``` 包裹，与文本区分
代码示例
## 输入参数说明
| 参数名 | 类型 | 必填 | 说明 |
|:-------|:-----|:-----|:-----|
| `doc_type` | string | 是 | 文档类型，可选值：`solution` / `api` / `manual` |
| `doc_title` | string | 是 | 文档主标题 |
| `content_points` | array | 是 | 文档核心要点数组，按章节顺序排列 |
| `output_format` | string | 否 | 输出格式，默认 `markdown`，可选 `markdown` / `html` |
效果
输入参数说明
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
doc_type |
string | 是 | 文档类型，可选值：solution / api / manual |
doc_title |
string | 是 | 文档主标题 |
content_points |
array | 是 | 文档核心要点数组，按章节顺序排列 |
output_format |
string | 否 | 输出格式，默认 markdown，可选 markdown / html |
2.5 执行流程
编写要求
按步骤描述技能的执行逻辑，包含判断分支、异常处理，确保执行路径清晰可追溯。
对应 Markdown 语法
- 有序列表 + 嵌套列表：实现分步流程与子步骤
- 加粗：标注关键判断节点
代码示例
## 执行流程
1. 接收用户输入，校验必填参数
1. 若参数缺失，主动询问补充
2. 若参数完整，进入下一步
2. 根据 `doc_type` 匹配对应的文档模板
3. 将 `content_points` 按模板结构填充到对应章节
4. 统一格式校验
- 标题层级是否规范
- 代码块是否指定语言
- 表格是否完整对齐
5. 输出最终文档，并附上格式说明
2.6 示例与模板
编写要求
提供可直接复用的模板、完整的输入输出示例，是 Skill 中最核心的参考内容。
对应 Markdown 语法
- 围栏代码块：用三个反引号包裹，指定语言实现语法高亮
- diff 代码块：用于展示版本变更、内容增减对比
- 引用式链接：示例中的链接可采用引用式写法保持整洁
代码示例
## 示例与模板
### 标准文档模板
```markdown
# 文档标题
## 一、概述
### 1.1 背景
### 1.2 目标
## 二、核心方案
### 2.1 整体架构
### 2.2 详细设计
## 三、注意事项
版本变更对比示例
- 旧版本：仅支持 Markdown 格式输出
+ 新版本：新增 HTML 格式导出能力
保留原有 Markdown 排版逻辑
2.7 执行逻辑可视化
编写要求
复杂的分支判断、多轮交互流程，用图表直观展示，降低理解成本。
对应 Markdown 语法
Mermaid 图表语法：代码块指定语言为 mermaid，自动渲染流程图/时序图。
代码示例
## 执行流程图
```mermaid
flowchart LR
A[接收用户请求] --> B{参数校验}
B -->|缺失| C[询问补充信息]
C --> B
B -->|完整| D[匹配文档模板]
D --> E[内容填充与排版]
E --> F{格式校验}
F -->|不通过| G[自动修正格式]
G --> F
F -->|通过| H[输出最终文档]
效果：
2.8 注意事项与边界
编写要求
标注技能的能力边界、风险提示、兼容性说明，避免超范围使用。
对应 Markdown 语法
- Callout 提示框：区分不同级别的提示（注意/警告/技巧）
- HTML 折叠块：
<details>收起冗长补充内容 - 高亮语法：
==内容==标记重点警告 - 脚注：补充额外说明信息
代码示例
## 注意事项与边界
> [!WARNING]
> ==本技能不具备合规审核能力==，涉及法律、医疗等强合规领域的文档，仅做格式整理，内容准确性需用户自行核验[^1]。
[^1]: 合规类文档建议交由对应领域的专业人员审核后发布。
<details>
<summary>兼容性说明</summary>
- 输出的 Mermaid 图表仅支持在支持 Mermaid 渲染的 Markdown 编辑器中正常显示
- Callout 语法在 GitHub 原生环境无法渲染，会降级为普通引用块
</details>
效果：
✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨
注意事项与边界
兼容性说明[!WARNING]
本技能不具备合规审核能力，涉及法律、医疗等强合规领域的文档，仅做格式整理，内容准确性需用户自行核验1。
- 输出的 Mermaid 图表仅支持在支持 Mermaid 渲染的 Markdown 编辑器中正常显示
- Callout 语法在 GitHub 原生环境无法渲染，会降级为普通引用块
2.9 自检清单与版本记录
编写要求
发布前的检查项、版本迭代记录，便于维护和追溯。
对应 Markdown 语法
- 任务列表：
- [x]标记已完成项，- [ ]标记待完成项 - 删除线：
~~内容~~标记废弃的功能 - 表格：版本记录用表格清晰展示
代码示例
## 自检与版本记录
### 发布前自检清单
- [x] 元数据字段完整且格式正确
- [x] 触发规则清晰，无歧义
- [x] 所有参数均有说明与示例
- [x] 执行流程覆盖正常路径与异常场景
- [ ] 最终输出经过实际测试验证
### 版本记录
| 版本号 | 发布日期 | 更新内容 |
|:-------|:---------|:---------|
| v1.0.0 | 2024-01-01 | 初始版本，支持三类文档生成 |
| v1.1.0 | 2024-02-15 | ~~移除旧版模板~~，新增 HTML 导出能力 |
效果：
自检与版本记录
发布前自检清单
- 元数据字段完整且格式正确
- 触发规则清晰，无歧义
- 所有参数均有说明与示例
- 执行流程覆盖正常路径与异常场景
- 最终输出经过实际测试验证
版本记录
| 版本号 | 发布日期 | 更新内容 |
|---|---|---|
| v1.0.0 | 2024-01-01 | 初始版本，支持三类文档生成 |
| v1.1.0 | 2024-02-15 |
三、完整可复用模板
以下为空白模板，可直接复制填充内容：
---
name: 技能唯一标识
version: 版本号
description: 一句话描述技能核心功能
trigger: 触发条件说明
tags: [标签1, 标签2]
author: 作者/团队
date: YYYY-MM-DD
---
# 技能名称
## 一、技能概述
### 1.1 核心功能
> 一句话核心定位
### 1.2 能力范围
-
-
### 1.3 适用场景
-
-
## 二、触发规则
### 2.1 触发条件
1.
2.
### 2.2 不适用场景
-
-
## 三、输入参数说明
| 参数名 | 类型 | 必填 | 说明 |
|:-------|:-----|:-----|:-----|
| `param1` | string | 是 | 参数说明 |
| `param2` | number | 否 | 参数说明 |
## 四、执行流程
1.
2.
1.
2.
3.
## 五、输出规范
### 5.1 输出格式
### 5.2 质量要求
## 六、示例与模板
### 6.1 输入示例
### 6.2 输出示例
七、执行流程图
flowchart TB
八、注意事项与边界
[!NOTE]
[!WARNING]
九、自检与版本记录
发布自检
- 元数据完整
- 触发规则清晰
- 参数说明齐全
- 流程覆盖异常场景
- 示例可运行
版本记录
| 版本 | 日期 | 更新内容 |
|---|---|---|
| v1.0 | 初始版本 |
四、语法兼容性速查
针对 Agent 平台常见的 Markdown 渲染环境，语法支持情况如下：
| 语法类别 | 通用Agent平台 | GitHub | Typora/Obsidian |
|---|---|---|---|
| 基础语法（标题/列表/代码块） | ✅ | ✅ | ✅ |
| 表格 | ✅ | ✅ | ✅ |
| 任务列表 | ✅ | ✅ | ✅ |
| 删除线 | ✅ | ✅ | ✅ |
| 高亮 | ❌ | ❌ | ✅ |
| 脚注 | 部分 | ✅ | ✅ |
| Mermaid 图表 | 部分 | ✅ | ✅ |
| Callout 提示框 | ❌ | ❌ | ✅ |
| HTML 折叠块 | 部分 | ✅ | ✅ |
| Front Matter | 支持 | 忽略 | ✅ |
编写通用 Skill 时，优先使用基础语法 + 表格 + 代码块 + 任务列表，确保全平台兼容。
五、编写最佳实践
- 结构优先：严格遵循标准模块顺序，层级不超过 4 级标题，确保逻辑清晰
- 示例先行：核心能力必须配可运行的示例，用代码块包裹，避免纯文字描述
- 边界明确：明确写清「不做什么」，和「能做什么」同等重要
- 兼容优先：无特殊需求时，优先使用通用兼容语法，减少平台专有扩展
- 格式统一：同一份 Skill 内语法风格保持一致，缩进、符号统一
✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨手动分割✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨
Markdown 技术文档标准化润色技能的Skill.md的文件示例
---
name: skill-markdown-doc-polish
version: 1.0.0
description: 对输入的技术类 Markdown 文档进行格式标准化、结构优化与排版统一，输出符合工程规范的文档内容
trigger: 当用户提出文档润色、格式规范、Markdown 排版优化、README 整理、技术笔记标准化需求时触发
tags: [文档润色, Markdown, 格式规范, 技术文档]
author: 技能开发组
date: 2024-02-20
---
一、技能概述
1.1 核心功能
不修改原文核心语义，仅对 Markdown 文档的格式、结构、排版进行标准化修正，统一写作风格，提升可读性与专业度。
本技能专注于技术类文档的格式层面优化，覆盖标题层级、列表、表格、代码块、引用、链接等全量基础语法，自动修正不规范写法，输出符合 GFM 标准的通用 Markdown 文档。
1.2 能力范围
- 统一标题层级规范，修正跳级、格式混乱问题
- 标准化列表缩进与符号，统一有序/无序列表写法
- 自动对齐表格，补全分隔线，统一列对齐方式
- 为代码块补充缺失的语言标识，修正代码块格式错误
- 统一链接、图片、引用的书写格式
- 可选生成自动目录、为标题添加数字编号
- 输出润色前后的格式变更说明
1.3 适用场景
- 项目 README 文档排版优化
- 技术学习笔记格式标准化
- API 接口文档、操作手册排版统一
- 多人协作文档的格式一致性修正
二、触发规则
2.1 触发条件
满足以下任意一项即可触发本技能：
- 用户明确提出「润色文档、规范格式、优化排版、整理 Markdown」等需求
- 用户粘贴一段格式混乱的 Markdown 文本，要求调整格式
- 用户提到「统一文档风格、符合 GFM 标准」等格式类诉求
2.2 不适用场景
- 文档内容的事实性纠错、专业内容审核
- 全文翻译、文案改写、创意润色
- 纯文本文档（非 Markdown 格式）的重排
- 复杂 LaTeX 公式、化学结构式的重绘
三、输入参数说明
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
input_content |
string | 是 | 待润色的 Markdown 文档全文内容 |
doc_type |
string | 否 | 文档类型，可选值：readme / note / api / general，默认 general |
enable_toc |
boolean | 否 | 是否在文档开头生成自动目录，默认 false |
heading_number |
boolean | 否 | 是否为标题添加层级数字编号，默认 false |
align_style |
string | 否 | 表格对齐风格，left 全左对齐 / center 表头居中，默认 left |
四、执行流程
- 接收输入内容，校验
input_content是否非空- 若内容为空，提示用户粘贴待润色的文档内容
- 若内容完整，进入结构解析步骤
- 解析文档原有结构，识别标题层级、列表、表格、代码块等元素
- 执行标准化润色处理
- 标题修正：修正跳级问题，统一标题前后空行规范
- 列表修正：统一缩进为 2 空格，统一无序列表符号为
- - 表格修正：补全分隔线，按指定对齐方式统一格式
- 代码块修正：为无语言标识的代码块补充通用标记，修正围栏格式
- 其他修正：统一引用格式，规范链接写法
- 可选功能处理
- 若
enable_toc为 true，根据标题层级生成目录 - 若
heading_number为 true，为各级标题添加数字编号
- 若
- 格式合规性自检
- 检查是否存在语法错误、格式不统一问题
- 确认未修改原文核心语义与内容
- 输出最终结果，附带格式变更说明
五、输出规范
5.1 输出结构
输出内容固定分为两部分，按顺序排列：
- 润色后文档全文：直接输出完整的标准化 Markdown 内容
- 格式变更说明：分点列出本次润色的主要修改项，便于用户核对
5.2 质量要求
- 严格保留原文所有核心信息与语义，仅做格式层面调整
- 标题层级最多 4 级，禁止出现 5 级及以下标题
- 所有代码块必须指定语言，无法识别时统一标注
text - 表格必须完整闭合，列数对齐，无语法错误
- 输出格式符合 GFM 标准，确保全平台兼容
六、示例与模板
6.1 输入示例（不规范文档）
# 测试文档
## 功能介绍
这是一段测试文本。
### 核心功能
1. 功能A
- 子功能1
- 子功能2
2. 功能B
### 接口说明
| 接口名 | 方法 | 说明
|------|------|------
| /user | GET | 获取用户信息
| /order | POST | 创建订单
### 代码示例
def get_user():
return user_info
> 这是一段引用
> 第二行引用
6.2 输出示例（标准化后）
# 测试文档
## 功能介绍
这是一段测试文本。
### 核心功能
1. 功能A
- 子功能1
- 子功能2
2. 功能B
### 接口说明
| 接口名 | 方法 | 说明 |
|:--------|:-----|:-------------|
| /user | GET | 获取用户信息 |
| /order | POST | 创建订单 |
### 代码示例
```python
def get_user():
return user_info
这是一段引用
第二行引用
### 6.3 变更对比示例
```diff
- 标题与正文之间无空行
+ 统一所有标题前后保留空行
- 列表子项缩进 1 空格
+ 统一列表子项缩进 2 空格
- 表格语法不完整，缺少右侧竖线
+ 补全表格边框，统一左对齐
- 代码块未指定语言
+ 为 Python 代码块补充语言标识
七、执行流程图
flowchart TB
A[接收文档内容] --> B{内容非空校验}
B -->|为空| C[提示用户补充内容]
C --> A
B -->|有效| D[解析文档结构]
D --> E[基础格式标准化]
E --> F{可选功能开启?}
F -->|生成目录| G[插入自动目录]
F -->|标题编号| H[添加层级编号]
F -->|无| I[格式合规自检]
G --> I
H --> I
I --> J{自检通过?}
J -->|不通过| K[修正格式问题]
K --> I
J -->|通过| L[输出润色结果+变更说明]
八、注意事项与边界
[!WARNING]
本技能仅处理格式排版，不负责内容的准确性、专业性与事实校验。若文档存在数据错误、逻辑漏洞、专业术语错误，本技能不会修正，也不承担相关责任。
[!NOTE]
润色过程中会尽可能保留原文结构；若存在严重的标题跳级（如一级标题后直接四级标题），会自动平滑调整层级，并在变更说明中告知。
兼容性说明
- 输出文档严格遵循 GFM 标准，在 GitHub、掘金、CSDN、Typora 等主流平台均可正常渲染
- 生成的自动目录为静态 Markdown 列表，非
@[toc]语法，确保全平台可用 - 不输出
==高亮==、Callout 等非通用语法，保证最大兼容性
九、自检与版本记录
发布自检清单
- 元数据字段完整且格式正确
- 触发规则清晰，无歧义
- 所有参数均有类型、必填项与说明
- 执行流程覆盖正常路径与异常场景
- 提供完整的输入输出对比示例
- 明确标注能力边界与风险提示
- 经过 5 份以上真实文档测试验证
版本记录
| 版本号 | 发布日期 | 更新内容 |
|---|---|---|
| v1.0.0 | 2024-02-20 | 初始版本，支持基础格式标准化、目录生成、标题编号三大核心能力 |
-
合规类文档建议交由对应领域的专业人员审核后发布。 ↩︎
Agent 垂直技术社区，欢迎活跃、内容共建。
更多推荐
11
0- 0
已为社区贡献4条内容
所有评论(0)