Trae Skill提示格式错误怎么办？

SKILL.md 文件解析失败导致 AI 无响应，通常需要从文件名大小写、路径规范、YAML Frontmatter 格式、Markdown 正文语法以及 Trae 运行模式匹配性这几个角度逐一排查。

在 Trae 中创建 Skill 后，如果 AI 完全没有响应、提示“格式错误”或直接跳过不加载，这通常意味着 SKILL.md 文件在解析阶段就出了问题——不是触发逻辑有误，而是文件本身无法被 Trae 识别为合法的 Skill。

检查 SKILL.md 文件名和位置

首先，确认文件名是否是全大写的

，而不是 skill.md、Skill.md 或 SKILL.MD。Trae 对大小写敏感，小写或混合大小写都会导致解析失败。

项目级 Skill 必须放在

；全局 Skill 则放在 或 。路径中任意一级目录名如果包含空格、中文或特殊符号（如括号、emoji），都会中断加载。

建议用终端执行 ls -la .trae/skills/your-skill-name/（Mac/Linux）或 dir .traeskillsyour-skill-name（Windows），确认输出中明确显示

文件存在且大小非零。

验证 YAML Frontmatter 格式是否合规

打开 SKILL.md 文件，确认最顶部严格以 --- 开始、--- 结束，且前后无空行、无缩进、无不可见字符（如 BOM 头）。任何多余的空格、制表符或隐藏 Unicode 字符都会让 Trae 拒绝解析。

name 字段必须只包含小写字母和短横线（-），不能有下划线、数字开头、空格或中文。例如

是合法的，而 、 或 都是非法的。

description 字段不能为空，且必须是自然语言句子，不能是列表、代码块或 Markdown 标题。如果写成 - 检查 Ja va 方法 或 ## 用途说明，Trae 会静默跳过整个文件。

排查 Markdown 正文中的致命语法冲突

这里提供两个实用的排查方法。

将 SKILL.md 正文部分全部替换为纯文本段落，删除所有表格、代码块（```）、嵌套列表、HTML 标签、自定义标题层级（如 ### 而非 ##）。只保留一级标题 # 角色与目标 和二级标题 ## 核心指令，其余内容用普通段落书写。Trae 的 Markdown 解析器对复杂结构兼容性较差，尤其是表格和多层缩进，很容易引发解析中断。

在正文开头插入 ，每写一段就加一个注释标记，保存后重启 Trae 并触发测试。当某段加入后 Skill 突然失效，该段就是冲突源。常见的雷区包括：、、（例如“1. 分析阶段”后跟空行再写“2. 审查维度”，中间缺少换行则解析失败）。

确认 Trae 当前运行模式与 Skill 类型匹配

第一步：打开 Trae 开发者工具（Ctrl+Shift+I），切换到 Network 标签页。

第二步：在聊天框输入任意触发词（如 “review code”），发送后观察请求 URL。

第三步：如果请求目标是 http://localhost:3000/skill/xxx，说明处于 SOLO 模式，此时只加载本地文件系统中的 Skill；如果目标是远程域名（如 https://model.mify.ai.srv/anthropic），说明处于 IDE 模式，

，只有全局 Skill 可能生效，且需要 Skill Server 显式注册。

第四步：如果你放置的是项目级 Skill 却在 IDE 模式下测试，Trae 根本不会扫描项目目录下的 .trae/skills，此时必须切换至 SOLO 模式，或者改用全局路径存放。