关于作者：10 + 年项目管理与全栈开发经验，近半年专注 Agent Skills 实战落地，帮助团队实现项目交付效率提升 40%。本文所有示例均基于 Trae / Cursor / OpenClaw / Hemers 全环境测试通过。

系列专栏：Agent Skills 开发实战・阶段 1 入门认知 这是「Agent Skills 开发实战」系列的 第 3 篇（第 3 周），定位：夯实基础、吃透底层规范。

回顾系列前文：第 1 篇我们搞懂了「什么是 Agent Skills」，建立认知；第 2 篇我们 5 分钟上手，写出了第一个可运行的 Hello World 技能，完成从零落地。

很多新手实操后都会遇到共性问题：同样的需求，有的人写的技能 AI 精准执行、零报错，有的人写的技能不触发、乱执行、频繁出幻觉。

究其根本，差距不在于代码，而在于 SKILL.md 文件的编写规范。SKILL.md 是 AI 智能体的专属工作手册，也是智能体识别、理解、执行技能的唯一核心依据。

本篇将零基础、逐模块、全覆盖拆解标准 SKILL.md 完整结构，帮你吃透智能体技能的底层规范，彻底告别技能失效、AI 乱执行问题，写出全平台通用、稳定可落地的标准 Agent Skill。

一、先搞懂：SKILL.md 的底层逻辑

1.1 为什么 SKILL.md 是 Skill 的灵魂？

回顾我们前两篇讲的标准 Skill 结构：

Plain Text my-first-skill/          # Skill 专属独立文件夹 ├── SKILL.md             # 【必填·核心灵魂文件】 └── scripts/     └── main.py          # 【可选·执行脚本】

不管是 Trae、Cursor、OpenClaw 还是 Hemers，绝大多数 AI 智能体都遵循这套统一标准结构。AI 的运行逻辑是：先读 SKILL.md → 读懂规则 → 再决定是否调用脚本、怎么调用。没有规范的 SKILL.md，脚本写得再完善，AI 也无法识别和正常运行。

这里重点提醒新手：入门阶段无需依赖脚本，仅编写规范的 SKILL.md 纯文本规则，就可以实现大部分基础技能功能，脚本只是进阶自动化的可选拓展，不用因不会代码产生学习门槛。

1.2 两大核心符号：写 Skill 零报错关键

很多新手写 Skill 报错、AI 识别混乱，根本原因是不理解两个关键符号的底层逻辑。这里统一讲透全平台通用规则：

（1）--- 三横线：机器识别边界符

--- 是 Trae、Cursor、OpenClaw、Hemers 官方强制识别的标记，用于包裹 Skill 的机器可读元数据。

• 必须放在文件最顶部，成对出现

• 横线内部：存放 name 和 description，给智能体程序读取，用于技能列表展示和意图匹配

• 横线外部：是人工 + AI 共同读取的业务规则正文

通俗理解：--- 是给机器看的 “身份边框”，框内是技能身份证，框外是技能工作流程。

（2）#井号：模块层级分隔符

# 不是普通的排版样式，而是给 AI 区分功能模块的逻辑标记，防止 AI 混淆步骤、参数、规则。

• # 一级标题：全文仅用一次，统一填写「技能详细规则」

• ## 二级标题：所有功能模块统一使用，如触发条件、输入参数、执行步骤等

• ###三级标题可选，用于进一步细分模块内容，不影响 AI 理解

通俗理解：## 是给 AI 分区的 “栏目隔板”，让 AI 精准区分每一段功能，杜绝乱执行。

二、顶部元数据：Skill 的 “官方身份证”

这是智能体加载 Skill 时优先读取的部分，用于技能列表展示、智能匹配和技能归类，也是新手最容易写错的核心模块。

标准正确写法（严格适配全平台规范）：

markdown --- name: "hello-world-skill" description: "一个入门级别的测试Skill，当用户说‘测试一下我的第一个技能’或类似指令时触发，输出一句问候语验证调用流程" ---

写作强制规范：

• name：必须采用 kebab-case 格式（小写字母+连字符），纯英文无中文，作为技能唯一机器识别标识

• description：一句话闭环，写清「触发场景 + 核心功能 + 产出价值」，禁止模糊描述

补充说明：机器识别的 name 用英文短横线格式，正文展示名称可保留中文，兼顾机器适配性和人工可读性，二者不冲突。

⚠️ 错误写法（老旧格式，现已淘汰）：手动写标题、手动写 “技能名称、技能描述” 模块，或 name 字段使用中文命名，AI 无法自动解析，会导致技能识别不稳定、平台匹配失败、无法在技能列表展示。

三、触发条件：技能的核心开关

作用：精准告诉 AI 什么时候必须用这个技能、什么时候不用。

这是小白技能不生效最常见的核心原因！

核心写作原则：必须具象、必须直白、不能抽象

❌ 错误写法（AI 看不懂、无法精准匹配）：

• 用户需要问候时触发

• 用户测试技能时触发

✅ 标准正确写法（精准匹配，零歧义）：
当用户说出以下任意指令时，触发本技能：

• 测试一下我的第一个技能

• 运行 hello world 技能

• 让智能体打个招呼

进阶技巧：可以搭配模糊语义补充，比如 “当用户想要测试 AI 技能是否正常运行时触发”，搭配精准指令，适配更多口语化场景。

四、输入参数：技能的标准化接口规范

作用：定义技能需要哪些外部信息，区分必填 / 选填，让 AI 主动判断是否需要向用户索要信息，补齐技能执行条件。

固定表格格式（全平台通用）：统一包含参数名、类型、是否必填、说明四项，无参数需标注“无”，禁止空白。

标准示例：

参数名	类型	是否必填	说明
name	字符串	选填	打招呼的对象，不填默认使用 AI 世界

小白必记：没有参数就写 “无”，不要空着，避免 AI 解析报错、逻辑异常。

五、执行步骤：AI 的强制执行手册

作用：限制 AI 的自由发挥，杜绝 AI 幻觉、乱回答、流程混乱，让 AI 严格按照预设逻辑干活。

核心铁律：步骤越细，AI 越稳；步骤越笼统，AI 越乱

❌ 小白错误写法（过于笼统，极易乱执行）：
接收用户指令，处理参数，返回问候结果。

✅ 标准分步写法（指令式流程，AI 零脑补）：

        1. 接收用户触发指令，读取用户传入的 name 参数

        2. 判断是否存在有效 name 参数，无则使用默认值

        3. 进阶可选：调用当前目录下 main.py 脚本，传入对应参数（纯文本技能可省略此步）

        4. 接收脚本/规则逻辑返回的动态结果

        5. 整理结果并标准化回复用户

只要你的步骤是逐条命令式，AI 就会放弃自主脑补，严格按流程执行，从根源解决乱输出问题。

六、输出格式：结果的标准化展示规范

作用：统一技能最终输出样式，避免同一技能每次返回格式混乱、风格不一，提升输出专业性和可读性。

常用标准写法（按需选择）：

• 纯文本输出，简洁自然，无需代码块

• 以表格形式输出最终结果，附带简要总结

• 输出结构化 markdown 结果，保留规范排版格式

小白易错点：不定义输出格式，导致同一技能每次返回的样式都不一样，极其不规范，影响使用体验。

七、错误处理：技能的容错机制

真正可用、可落地的商用级 Skill，必须配备完善的错误处理逻辑，完美场景下能运行不算稳定，异常场景不崩溃才是标准技能。

作用：避免用户输入异常、参数为空、脚本报错时，AI 直接崩溃、乱报错、强制终止任务。

标准写法模板：

• 参数缺失：存在必填参数未传入时，友好提示用户补充对应信息

• 参数错误：参数格式、内容异常时，自动忽略异常参数，启用默认值兜底

• 执行失败：脚本/逻辑运行失败时，返回简洁友好提示，不暴露底层代码报错

八、使用示例：降低AI理解偏差

作用：给 AI 提供真实参考案例，进一步缩小语义理解偏差，大幅提升技能触发准确率和执行稳定性。

标准示例：
用户输入：测试一下我的第一个技能 → AI返回默认时间问候语
用户输入：运行hello world技能，我叫小明 → AI返回对应专属问候内容

九、全平台通用：可直接复用的标准版 SKILL.md 模板

结合系列前文知识点，整理出零报错、可直接落地、小白无脑复用的终极模板，后续所有自定义技能均可基于此修改，适配 Trae / Cursor / OpenClaw / Hemers 全平台。

markdown --- name: "自定义技能英文名称（kebab-case小写+连字符）" description: "此处一句话精准定义：技能用途、触发场景、核心能力，禁止模糊描述" --- # 技能详细规则 ## 1. 触发条件 用户说出以下任意指令时触发本技能： - 精准指令1 - 精准指令2 - 精准指令3 ## 2. 输入参数 | 参数名 | 类型 | 是否必填 | 说明 | |--------|------|----------|------| | 示例参数 | 字符串 | 选填/必填 | 参数作用说明 | ## 3. 执行步骤 1. 第一步：接收用户指令，读取对应参数 2. 第二步：判断参数有效性，处理默认值 3. 第三步：执行对应逻辑（进阶可新增脚本调用） 4. 第四步：整理执行结果 5. 第五步：按指定格式输出结果 ## 4. 输出格式 明确纯文本/表格/markdown/代码块等输出样式 ## 5. 错误处理 - 参数缺失：友好提示或启用默认值 - 参数错误：忽略异常，兜底执行 - 执行失败：返回简洁提示，不暴露底层报错 ## 6. 使用示例 用户输入：xxx AI输出：xxx

十、避坑指南与总结

10.1 五个高频结构坑

掌握标准结构后，避开以下误区，你的技能稳定性可超越绝大多数新手：

（1）文件名大小写错误

必须是 SKILL.md（固定大写开头），所有主流智能体严格区分大小写，skill.md 会直接识别失败、技能无法加载。

（2）触发条件过于抽象

禁止写“用户需要帮忙时触发”这类模糊语句，AI无法精准判定触发时机，必须罗列具体用户话术。

（3）执行步骤过于笼统

步骤不分步、一句话概括流程，会导致 AI 自由发挥、逻辑错乱，逐条拆分指令是技能稳定运行的核心。

（4）缺少错误处理机制

无容错逻辑的技能仅能在完美场景运行，真实使用中遇到参数异常、执行失败会直接崩溃失效。

（5）参数标注不规范

不标注参数类型、必填属性，会导致 AI 无法判断是否需要主动询问用户信息，出现漏执行、缺参数、运行异常等问题。

10.2 总结：写好 SKILL.md 的核心心法

读完本篇可以明确：Agent Skill 从来不是玄学，只是一套标准化的写作规范。

SKILL.md 的八大核心模块，本质是给 AI 建立完整的工作逻辑：

• 我是谁（名称+描述）

• 我什么时候干活（触发条件）

• 我需要什么信息（输入参数）

• 我怎么一步步干活（执行步骤）

• 我产出什么结果（输出格式）

• 出错了怎么办（错误处理）

只要结构标准、描述清晰、规范落地，写出的 Skill 可无缝适配 Trae / Cursor / OpenClaw / Hemers 所有主流智能体，真正实现一次编写、全平台通用。

关于 Agent Skills 开发实战系列

本文为「Agent Skills 开发实战 · 阶段1入门认知」系列第3篇，承接前文零基础入门实操，夯实底层规范。

系列往期文章：

1、什么是Agent Skills？AI智能体技能核心认知解析
2、从零开始：Hello World 标准 Skill 入门教程

下期预告：下一篇将进入概念澄清专项内容，带来系列第 4 篇：《Prompt、Rule、Skill 三者区别》。帮你彻底理清三者定位、适用场景与分工边界，解决新手最容易混淆的基础概念，为后续高阶实战打好底层认知。