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_typestring是文档类型可选值solution/api/manualdoc_titlestring是文档主标题content_pointsarray是文档核心要点数组按章节顺序排列output_formatstring否输出格式默认markdown可选markdown/html2.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.02024-01-01初始版本支持三类文档生成v1.1.02024-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平台GitHubTypora/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_contentstring是待润色的 Markdown 文档全文内容doc_typestring否文档类型可选值readme/note/api/general默认generalenable_tocboolean否是否在文档开头生成自动目录默认falseheading_numberboolean否是否为标题添加层级数字编号默认falsealign_stylestring否表格对齐风格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.02024-02-20初始版本支持基础格式标准化、目录生成、标题编号三大核心能力合规类文档建议交由对应领域的专业人员审核后发布。 ↩︎