skill.md 文件解析失败导致 ai 无响应，需检查文件名大小写、路径规范、yaml frontmatter 格式、markdown 正文语法及 trae 运行模式匹配性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在 Trae 中创建 Skill 后，AI 完全没有响应、提示“格式错误”或直接跳过不加载，说明 SKILL.md 文件在解析阶段就已失败——这不是触发逻辑问题，而是文件本身无法被 Trae 识别为合法 Skill。
检查 SKILL.md 文件名和位置
确保文件名是全大写的 SKILL.md，不是 skill.md、Skill.md 或 SKILL.MD。Trae 对大小写敏感，小写或混合大小写均导致解析失败。
项目级 Skill 必须放在 项目根目录/.trae/skills/你的技能名/SKILL.md；全局 Skill 必须放在 ~/.traecli/skills/你的技能名/SKILL.md（Mac/Linux） 或 %USERPROFILE%\.traecli\skills\你的技能名\SKILL.md（Windows）。路径中任意一级目录名含空格、中文或特殊符号（如括号、emoji），都会中断加载。
用终端执行 ls -la .trae/skills/your-skill-name/（Mac/Linux）或 dir .trae\skills\your-skill-name\（Windows），确认输出中明确显示 SKILL.md 文件存在且大小非零。
验证 YAML Frontmatter 格式是否合规
打开 SKILL.md 文件，确认最顶部严格以 --- 开始、--- 结束，且前后无空行、无缩进、无不可见字符（如 BOM 头）。任何多余空格、制表符或隐藏 Unicode 字符都会让 Trae 拒绝解析。
name 字段必须仅含小写字母、短横线（-），不能有下划线、数字开头、空格或中文。例如 java-method-check 合法，java_method_check 或 1st-skill 或 代码审查 均非法。
description 字段不能为空，且必须是自然语言句子，不能是列表、代码块或 Markdown 标题。若写成 - 检查 Java 方法 或 ## 用途说明，Trae 会静默跳过整个文件。
排查 Markdown 正文中的致命语法冲突
方法一：禁用所有高级格式
将 SKILL.md 正文部分全部替换为纯文本段落，删除所有表格、代码块（```）、嵌套列表、HTML 标签、自定义标题层级（如 ### 而非 ##）。只保留一级标题 # 角色与目标 和二级标题 ## 核心指令，其余内容用普通段落书写。Trae 的 Markdown 解析器对复杂结构兼容性差，尤其表格和多层缩进极易引发解析中断。
方法二：逐段注释测试
在正文开头插入 <!-- DEBUG: start -->，每写一段就加一个注释标记，保存后重启 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 可能生效，且需 Skill Server 显式注册。
第四步：若你放置的是项目级 Skill 却在 IDE 模式下测试，Trae 根本不会扫描项目目录下的 .trae/skills，此时必须切换至 SOLO 模式或改用全局路径存放。
