导入失败时需依次检查skill.yaml/json是否存在、路径是否合规（默认skills/子目录或手动添加父文件夹）、权限是否开放，再验证文件编码为UTF-8无BOM、YAML语法正确、version字段匹配平台版本。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
超级麦吉AI技能文件导入失败时，无法调用自定义能力处理会议纪要、PPT生成或数据分析任务，导致工作流卡在准备阶段，必须立刻定位是加载缺失、路径错误还是结构冲突。
确认技能文件是否被系统识别
打开超级麦吉工作台 → 点击左下角「设置」→ 进入「技能市场」→ 切换到「本地技能」标签页。若列表为空或未出现你刚放入的技能名称，说明文件未被识别。
此时不要重试导入，先检查技能包根目录是否存在 【skill.yaml 或 skill.json】 文件——这是超级麦吉识别技能的唯一入口，缺一不可。没有该文件，整个文件夹会被跳过扫描。
这一步操作起来很简单，直接在资源管理器中展开你放置技能的文件夹就能看到。
验证技能文件存放路径是否合规
方法一：使用默认路径自动加载
确保技能文件夹放在超级麦吉安装目录下的 skills/ 子目录中（Windows常见路径为 C:\Program Files\SuperMagic\skills\，macOS为 ~/Library/Application Support/SuperMagic/skills/）。
方法二：手动指定路径
在「设置 → 技能市场 → 本地技能 → 添加路径」中，点击「浏览」选择你存放技能的父级文件夹。注意：只能添加文件夹，不能添加.zip或单个.yaml文件。
方法三：检查权限与隔离状态
若你在企业版中启用了沙盒隔离，需确认当前账号所属部门已获得该路径的读取权限。无权限时，即使路径正确，文件也会静默跳过。
排查技能结构是否触发加载失败
第一步：检查文件编码
用VS Code或Notepad++打开 skill.yaml，确认编码格式为UTF-8无BOM。若为GBK或UTF-8 with BOM，超级麦吉解析器会直接终止加载，且不报错。
第二步：校验YAML语法有效性
复制全部内容到 https://yamlchecker.com/ 在线校验。常见错误包括缩进混用空格与Tab、末尾多出冒号、布尔值写成true却漏了引号导致被识别为变量名。
第三步：确认version字段是否匹配当前平台
打开超级麦吉右下角「关于」，查看版本号（如v3.0.2）。若skill.yaml中声明 version: "2.1"，而平台最低要求为3.0，则该技能被强制忽略——不会提示兼容性警告，也不会出现在列表中。
