qoderwake配置skill未生效是因为路径、命名或定义文件不符合规范。需将skill文件夹置于指定路径下，文件夹名与skill.yaml中id字段完全一致，且id、version、triggers字段必须正确填写并非空，最后重启服务并查看debug日志确认加载状态。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
QoderWake配置Skill后未生效，Quest模式中技能完全不识别，界面无报错、日志无加载记录，说明Skill根本未被加载引擎扫描到——这不是逻辑错误，而是路径或命名层面的硬性拦截。
确认Skill文件存放路径是否符合规范
QoderWake只扫描特定目录下的Skill，且路径层级不可省略。必须将Skill文件夹完整置于~/.config/qoderwake/skills/（Linux/macOS）或%USERPROFILE%\.config\qoderwake\skills\（Windows）下，不能放在子目录如skills/custom/或skills-backup/中。
打开终端或命令提示符，执行：ls -l ~/.config/qoderwake/skills/（macOS/Linux）或dir "%USERPROFILE%\.config\qoderwake\skills\"（Windows），确认目标Skill文件夹直接列在该目录下，而非嵌套在其他文件夹内。
【关键操作】若路径中含中文、空格或特殊符号（如括号、&、#），QoderWake会静默跳过整个文件夹——请立即将其重命名为纯英文+下划线组合，例如web_scraping_v2，不要用网页抓取_测试版或my-skill(1)。
检查Skill文件夹内部结构与命名一致性
每个Skill必须是一个独立文件夹，且文件夹名必须与内部skill.yaml（或skill.json）中定义的id字段值完全一致，包括大小写和连字符。
进入该Skill文件夹，用文本编辑器打开skill.yaml，查找id:行，例如：id: data_cleaner_pro；再确认当前文件夹名是否也叫data_cleaner_pro。二者任意一处拼写偏差（比如data-cleaner-pro或DataCleanerPro），Skill即无法注册。
这一步操作起来很简单，直接比对两处字符串是否逐字符相同即可。不一致就立刻重命名文件夹，别改yaml里的id——QoderWake强制以文件夹名为唯一标识。
验证Skill定义文件语法与必填字段
方法一：用YAML校验工具快速检测
将skill.yaml全文粘贴至在线YAML校验器（如yamllint.com），确认无缩进错误、冒号后缺失空格、布尔值未小写等基础语法问题。特别注意triggers和actions字段不能为空数组，至少保留一个合法条目，否则引擎判定为无效Skill而丢弃。
方法二：手动检查三个强制字段
打开skill.yaml，确保同时存在以下三项且非空：
① id：与文件夹名100%一致；
② version：格式为X.Y.Z，如1.0.0，不能是v1.0或1.0；
③ triggers：至少包含一个有效触发器对象，例如：- type: keyword, value: "清理数据"。若此处写成triggers: []或直接删掉该字段，Skill不会被加载。
重启QoderWake并观察加载日志
第一步：彻底终止所有QoderWake进程。Windows执行taskkill /f /im qoderwake.exe，macOS/Linux执行pkill -f qoderwake。
第二步：清空运行时缓存。删除~/.config/qoderwake/cache/（或%USERPROFILE%\.config\qoderwake\cache\）整个文件夹。
第三步：以调试模式启动服务，实时捕获加载行为：qoderwake start --debug。
第四步：在终端输出中搜索loading skill关键词。若看到loading skill data_cleaner_pro → OK，说明已成功加载；若完全没出现该行，或出现skip invalid skill: data_cleaner_pro，则回到前三个步骤逐项复查。
