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

系列专栏：Agent Skills 开发实战・阶段 2 基础实操

这是「Agent Skills 开发实战」系列的 第 5 篇（第 5 周），定位：痛点解决、排错实操、手把手排查，正式进入阶段 2 实战模块。

回顾系列前文：第 1 篇建立核心认知，搞懂「什么是 Agent Skills」；第 2 篇快速落地，5 分钟写出 Hello World；第 3 篇深耕底层，拆解标准SKILL.md文件结构；第 4 篇澄清概念，彻底分清 Prompt、Rule、Skill 三兄弟。

一、90% 的新手，都卡在了 "第一步"

写完第一个 Hello World Skill 之后，你大概率会遇到这个灵魂拷问：

文件放进去了、格式也对、语法没报错，但 AI 就是完全不搭理它。 你明明说 "用需求分析 Skill 帮我拆解一下"，结果它自顾自聊起天来，跟没装过这个技能一样。

绝大多数人第一反应是：模型不行、平台有 bug、我写得不够长。

然后开始疯狂加字数、改措辞、重装软件、换模型…… 折腾一圈，问题依旧。

其实你搞错了方向。Skill 不生效，从来不是 "写得好不好" 的问题，而是 "有没有被看见" 的问题。

在排错之前，你必须先搞懂一个核心区分：

根本没加载成功 ≠ 加载了但不触发 ≠ 触发了但执行错了

这是三种完全不同的故障，排查路径天差地别。新手最大的通病：上来就改执行逻辑，结果问题出在第一行文件名拼错了。

本篇延续本系列零基础、重实战、全平台通用风格，用「四层排查法」带你从外到内、从易到难，系统性定位所有 Skill 失效问题。文末附赠可直接套用的万能排错清单，照着勾就能解决 99% 的问题。

二、先做一道判断题：你的 Skill 到底属于哪种 "不生效"

在动手排查之前，先用 30 秒做个自检，定位故障层级。

现象描述	故障层级	问题根源
完全没反应，AI 像没见过这个技能一样	第一层：文件层	路径错、文件名错、格式解析失败
手动叫它名字能生效，但 AI 从不主动用	第二层：触发层	description 写得烂，模型识别不到
偶尔生效偶尔失效，同一问题结果不一样	第三层：优先级层	Rule 冲突、Prompt 覆盖、上下文污染
换个项目 / 平台就失效，本机正常别处不行	第四层：环境层	模式不对、依赖缺失、平台差异

绝大多数新手栽在第一层。不要觉得 "这么低级的错误我不可能犯"—— 官方社区每天都有人因为把 skill 写成 skills（多了个 s）卡三天。

下面我们逐层拆解，从上到下排查。

三、第一层排查：文件层 —— 你的 Skill 根本没被 "看见"

这是最高频、也最容易被忽略的一层。症状就是：无论你怎么说，AI 完全不知道有这个技能存在。

就像你把一份员工手册塞在了会议室抽屉里，却指望前台主动照着执行 —— 它连文件在哪都不知道。

3.1 最坑第一名：目录名单数复数写错

现象：文件内容完美，但就是不加载。

根因：

• 不同平台、不同版本的目录名要求不同（有的用 skill，有的用 skills）

• 排查时请优先查阅对应平台的官方文档

• 目录层级也有要求（如 .trae/skills/技能名/SKILL.md），缺一层都不行

✅ 自检动作：去资源管理器里确认文件夹名，一个字母都不能差。

3.2 文件名大小写与编码问题

现象：Windows 上好好的，Mac/Linux 就失效了；或者复制别人的代码就不行。

根因：

• 标准文件名必须是 SKILL.md（全大写 + 点 md），写成 skill.md、Skill.md 在区分大小写的系统上都会失效

• 文件编码必须是 UTF-8，GBK 或带 BOM 的 UTF-8 会导致解析失败

• 不能用 Word、WPS 保存，必须用纯文本编辑器

✅ 自检动作：用 VS Code 打开，右下角看编码是不是 UTF-8；确认文件名完全匹配。

3.3 YAML 头格式错误：差一个空格都不行

现象：文件放对位置了，但技能列表里不显示。

根因：SKILL.md 顶部的 frontmatter（--- 包裹的元数据）格式错误，导致整个文件解析失败。

常见错误：

• --- 前面有空行（必须是文件第 0 字节）
• 缩进用了 Tab 而不是空格
• description 超长（部分平台有 1024 字符硬限制）

❌ 错误示例（--- 前有空行）：

Plain Text （这里空了一行） --- name: 需求分析 description: 分析用户需求并生成PRD ---

✅ 正确示例（顶格写）：

yaml --- name: 需求分析 description: 当用户提出产品需求时，将模糊需求拆解为结构化PRD文档 ---

✅ 自检动作：找一个官方确认能用的 Skill，逐行比对你的 frontmatter 格式。

3.4 第一层小结：文件层排错三板斧

1. 路径对不对 → 单数复数、层级深度

1. 文件名对不对 → 大小写、扩展名

1. 格式对不对 → YAML 头有没有解析报错

过了这一关，你的 Skill 至少能 "被系统看见" 了。如果还是不触发，往下走。

四、第二层排查：触发层 ——AI 看得见，但不知道 "什么时候用"

文件加载成功了，技能列表里也能看到，但 AI 就是不主动调用。你不提它名字，它永远不会自己出来。

这是第二层问题：触发描述写得太烂。

很多人写 description 的思路完全错了。他们写的是 "这个技能有多厉害"，但 AI 需要知道的是 "什么时候该用它"。

4.1 触发失败的核心原因：你写的是功能，不是场景

打个比方：你雇了一个厨师，告诉他 "我擅长做川菜"—— 这是功能描述。但厨师需要知道的是 "客人点了什么菜的时候，我出手"。

AI 每次接到用户请求，都会扫一遍所有 Skill 的 description，然后判断 "这个问题该不该用它"。你写得越模糊，它越不敢用。

❌ 反面教材（90% 的新手都这么写）：

yaml description: 一个强大的代码审查技能，能够发现代码中的问题，提升代码质量，支持多种编程语言

这种描述等于没说。AI 根本判断不出来 "用户让我看看这段代码" 到底算不算代码审查。

✅ 正确写法（场景 + 关键词 + 边界）：

yaml description: 当用户要求审查代码、检查bug、做代码评审或code review时使用。输入代码片段，输出问题清单和改进建议。不负责编写新功能代码。

核心三要素：

• 触发场景：当用户说什么话的时候用（"当用户要求审查代码时"）

• 关键词：审查、评审、code review、检查 bug

• 边界：不做什么（"不负责编写新功能代码"）

4.2 触发率提升技巧：给 AI 明确的 "扳机词"

优化 description 后，Skill 主动触发率通常会有明显提升。这里有三个立竿见影的技巧：

技巧一：开头就说 "当用户…… 时使用"

不要铺垫，第一句直接给触发条件。AI 扫读时第一时间就能匹配上。

技巧二：埋 3-5 个精准关键词

把用户最可能说的词写进去。比如代码审查 Skill 就埋：审查、评审、code review、查 bug、找问题。

技巧三：写明 "不做什么"

边界越清晰，AI 越敢调用。最怕的就是模棱两可，AI 为了不出错，干脆选择不用。

4.3 第二层验证：手动触发 vs 自动触发

判断是不是触发层问题，有个黄金测试法：

1. 手动指名道姓："使用需求分析 Skill 帮我拆解这个需求"

1. 自然提问："帮我看看这个需求怎么做"

如果 1 能生效、2 不能 → 百分之百是触发层问题，改 description 就行。

如果连 1 都不生效 → 回到第一层，文件根本没加载成功。

五、第三层排查：优先级层 —— 触发了，但执行结果不对

最让人头疼的一种情况：Skill 明明调用了，但输出结果和你写的完全不一样。

时而精准、时而跑偏、同一句话两次结果不同。这就是我们第 4 篇讲过的优先级冲突问题。

5.1 重温优先级法则：谁的权限大

再复习一遍这条铁律（排错全靠它）：

临时 Prompt（最高） > Skill 内置规则 > 全局 Rule（底线兜底）

很多时候不是 Skill 不生效，而是被更高优先级的东西覆盖了。

5.2 常见冲突场景一：全局 Rule 与 Skill 打架

现象：Skill 要求输出 JSON 格式，但出来的永远是 Markdown。

根因：全局 rules.md里写了 "所有输出使用 Markdown 格式"，而 Skill 里的要求优先级不够强。

✅ 解决方法：在 Skill 执行流程的第一条明确写 "本技能输出优先使用 JSON 格式，覆盖全局规则"。主动声明优先级，AI 就不会纠结了。

5.3 常见冲突场景二：用户 Prompt 覆盖了 Skill

现象：明明调用了需求分析 Skill，但用户加了一句 "简单说说就行"，结果输出就只剩三行字，完全不按 Skill 流程走。

根因：用户临时指令优先级最高，一句话就能废掉整个 Skill 的规范。

✅ 解决方法：在 Skill 开头加一句容错说明："即使用户要求简化，也至少输出核心三要素，不得省略关键步骤"。

5.4 常见冲突场景三：多个 Skill 边界重叠

现象：同时装了 "代码审查" 和 "Bug 修复" 两个 Skill，用户说 "帮我看看代码有啥问题"，AI 不知道该调用哪个，最后两个都不用，自己瞎答。

根因：Skill 之间职责边界不清，AI 陷入选择困难。

✅ 解决方法：

• 每个 Skill 的 description 里明确区分场景

• 代码审查 = 看问题、给建议、不改代码

• Bug 修复 = 定位错误、直接修正、输出修复后代码

• 重叠区域写清楚："简单问题用审查，需要实际改代码用修复"

5.5 第三层排查口诀

输出不对不要急，先看优先级：

• 是不是用户说了什么盖过去了？

• 是不是全局规则冲突了？

• 是不是别的 Skill 抢活了？

六、第四层排查：环境层 —— 换个地方就失效

前三层都没问题，但换个项目、换台电脑、换个平台就挂了。这是环境依赖问题。

6.1 模式不对：不是所有模式都支持 Skill

现象：同一个项目，有时候能用有时候不能。

根因：很多平台的高级 Skill 只在特定模式下生效。比如 Trae 的 SOLO 模式才能完整调用技能链，普通聊天模式只支持基础能力。

✅ 检查：确认你是在 SOLO / Agent 模式下对话，不是普通编辑器聊天窗口。

6.2 依赖缺失：Skill 调用的工具不存在

现象：Skill 触发了，但执行到一半报错，或者输出空结果。

根因：Skill 里写了调用 Python 脚本、Node 命令、外部 API，但运行环境里没有装。

就像你给厨师一份菜谱，但厨房里缺盐少锅，菜肯定做不出来。

✅ 检查：

• Skill 用到的 CLI 工具装了吗？

• Node / Python 版本对吗？

• 网络能访问调用的 API 吗？

• 文件读写权限够吗？

6.3 平台差异：没有真正的 "一次编写到处运行"

虽然我们一直强调全平台通用，但不同 Agent 对 SKILL.md的支持度确实有差异：

平台	frontmatter 字段	工具调用能力	自动触发能力
Trae	完整支持	强	强
Cursor	部分支持	中	中
OpenClaw	完整支持	强	强
Hemers	完整支持	强	中

有些字段在 A 平台是标配，到 B 平台就不识别。跨平台开发时，建议只用最通用的字段：name、description、triggers，其他高级特性做降级兼容。

七、万能排错四步法：照着做就能解决 99% 的问题

说了这么多，给你一套可以直接套用的排查流程。遇到 Skill 不生效，按这个顺序走，从上到下排查，找到问题就停。

第一步：验证加载状态（文件层）

1. 确认目录路径和文件名完全正确

1. 检查 YAML 头格式，找一个能跑的 Skill 逐行对比

1. 重启客户端 / 重新加载技能

1. 去技能列表里看，有没有显示出来

这一步过不了 → 问题在第一层，不要往下看了

第二步：手动强制调用（触发层）

直接在对话里说："使用 XXX Skill 来处理这个问题"。

• 能正常执行 → 触发层问题，回去改 description

• 还是没反应 → 回到第一步，根本没加载成功

第三步：对比输出差异（优先级层）

手动调用成功了，但输出不对：

1. 看是不是和全局 Rule 冲突

1. 看是不是用户 Prompt 里有覆盖性指令

1. 关掉其他 Skill 单独测试，排除互相干扰

第四步：检查运行环境（环境层）

前三步都没问题但还是报错：

1. 确认运行模式（SOLO / 普通）

1. 检查依赖工具是否安装

1. 查看日志 / 控制台有没有报错信息

1. 换个平台测试，确认是不是平台兼容性问题

经验数据：80% 的问题在第一步就能解决，15% 在第二步，剩下 5% 在后两层。

八、新手避坑清单：打印出来勾着查

最后整理一份极简避坑清单，下次遇到问题直接对照打勾。

文件层检查清单

• 目录名是 skill 还是 skills？和平台要求一致吗？

• 文件名是 SKILL.md 吗？大小写完全正确吗？

• 文件编码是 UTF-8 吗？

• YAML 头的 --- 顶格写了吗？前面没有空行吗？

• name 和 description 字段拼写正确吗？

触发层检查清单

• description 第一句写了 "当用户…… 时使用" 吗？

• 埋了 3-5 个用户常用关键词吗？

• 写明了适用边界和不适用场景吗？

• 手动指名道姓调用能生效吗？

优先级层检查清单

• 和全局 rules.md有冲突吗？

• 用户的临时指令会不会覆盖 Skill 规则？

• 和其他 Skill 的职责有重叠吗？

环境层检查清单

• 是在支持 Skill 的模式下运行吗（如 SOLO）？

• Skill 依赖的工具 / 脚本都安装了吗？

• 换个项目 / 平台能复现问题吗？

九、写在最后

很多人觉得 Skill 不稳定、容易出 bug，是 AI 技术不成熟。

但真实情况是：90% 的问题，都是低级错误 + 认知偏差。

文件名拼错、路径多一个字母、描述写得太模糊、规则互相打架…… 这些问题跟 AI 能力没关系，纯粹是开发习惯和认知不到位。

入门阶段最容易犯的错误，就是看不起基础问题。总觉得 "我不可能犯这么蠢的错"，然后在高级问题里死磕三天三夜。

排错的黄金法则永远是：从最简单的地方查起。

先确认文件放对了，再谈写得好不好。先确认 AI 能看见，再谈它愿不愿意用。

关于 Agent Skills 开发实战系列

系列往期文章：

1、《一文读懂 Agent Skills》：AI智能体技能核心认知解析

2、《从零开始：Hello World 标准 Skill 入门教程》：零基础快速建立开发信心

3、《Skill.md 文件结构拆解》：夯实Agent技能底层编写规范

4、《Prompt、Rule、Skill 区别一篇讲透》：90%的 Skill 不稳定，都是因为分不清

下一篇我们正式进入实战模板开发 —— 第 6 周《实战：写一个「需求分析」Skill》，手把手带你从零封装一个可直接用于生产的专业技能模板，把前 5 周学到的所有知识落地成可复用的成品。