Agent Skill 编写规范与 Markdown 语法实战指南-Seo优化-塔城地区网站建设公司

📃个人主页：编程的一拳超人

⛺️ 欢迎关注：👍点赞 👂🏽留言 😍收藏 💞 💞
💞

于高山之巅，方见大河奔涌；于群峰之上，更觉长风浩荡。 ——《人民日报》

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]
本技能不具备合规审核能力，涉及法律、医疗等强合规领域的文档，仅做格式整理，内容准确性需用户自行核验¹。

兼容性说明

输出的 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	~~移除旧版模板~~，新增 HTML 导出能力

三、完整可复用模板

以下为空白模板，可直接复制填充内容：

--- 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是否非空
1. 若内容为空，提示用户粘贴待润色的文档内容
2. 若内容完整，进入结构解析步骤
解析文档原有结构，识别标题层级、列表、表格、代码块等元素
执行标准化润色处理
1. 标题修正：修正跳级问题，统一标题前后空行规范
2. 列表修正：统一缩进为 2 空格，统一无序列表符号为-
3. 表格修正：补全分隔线，按指定对齐方式统一格式
4. 代码块修正：为无语言标识的代码块补充通用标记，修正围栏格式
5. 其他修正：统一引用格式，规范链接写法
可选功能处理
1. 若enable_toc为 true，根据标题层级生成目录
2. 若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	初始版本，支持基础格式标准化、目录生成、标题编号三大核心能力

合规类文档建议交由对应领域的专业人员审核后发布。 ↩︎