技能文件加载失败需排查五方面：一、路径是否为~/.hermes/skills/且命名合规；二、模块结构是否合法（含__init__.py、register()函数等）；三、依赖是否安装在Hermes虚拟环境中；四、文件权限与属主是否正确；五、是否存在name冲突或重复加载。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在启动或运行 Hermes Agent 时发现自定义技能文件未被识别、执行时报错“Skill not found”或日志中出现“Failed to load skill module”，则很可能是技能文件加载失败所致。以下是针对该问题的多种排查与修复路径：
一、技能文件路径配置错误
Hermes Agent 仅从预设目录加载技能模块，若文件未置于正确路径下，系统将完全忽略其存在。默认技能搜索路径为 ~/.hermes/skills/ 及其子目录，且要求文件名符合 Python 模块命名规范（仅含字母、数字、下划线，不以数字开头）。
1、确认技能文件实际存放位置是否为 ~/.hermes/skills/your_skill_name.py 或 ~/.hermes/skills/your_skill_name/__init__.py。
2、检查该路径是否存在，执行 ls -l ~/.hermes/skills/ 验证文件可读性与权限。
3、若使用符号链接，请确保链接目标有效且未跨文件系统；Hermes 不支持相对路径引用或位于 /tmp 等临时挂载点的技能文件。
二、Python 模块结构不合法
技能文件必须构成一个可被 Python 导入的有效模块。缺失 __init__.py、语法错误、顶层 import 失败或未定义 register() 函数，均会导致加载中断。
1、在终端中手动尝试导入该模块：python3 -c "import your_skill_name"（需先 cd 到 ~/.hermes/skills/ 目录或将其加入 PYTHONPATH）。
2、检查技能文件首行是否为合法 Python 代码，排除 BOM 字节、隐藏控制字符或 UTF-8 编码外的其他编码格式。
3、确认文件内是否正确定义了 register() 函数，且该函数返回值为 Skill 实例或字典格式的技能元数据。
三、依赖包未在 Hermes 虚拟环境中安装
Hermes Agent 运行于独立 Python 虚拟环境，即使系统或用户级 pip 已安装所需库，技能仍会因 ImportError 加载失败。典型报错包含 ModuleNotFoundError: No module named 'xxx'。
1、进入 Hermes 的虚拟环境：source ~/.hermes/venv/bin/activate（Linux/macOS）或 ~\.hermes\venv\Scripts\activate.bat（Windows WSL2）。
2、执行 pip list | grep -i xxx 检查缺失依赖是否已安装。
3、若未安装，使用该虚拟环境下的 pip 安装：pip install requests pydantic（替换为实际所需包名）。
四、技能文件权限或所有权异常
当技能文件属主非当前运行用户、或缺少读取权限时，Hermes 在初始化阶段会静默跳过该文件，不报错但也不加载。
1、运行 ls -l ~/.hermes/skills/*.py 查看所有技能文件的权限位与所有者。
2、确保每项输出中包含 -rw-r--r-- 或更宽松权限，且第三列所有者为当前用户（如 ubuntu 或 $USER）。
3、修正权限：chmod 644 ~/.hermes/skills/*.py；修正属主：chown $USER:$USER ~/.hermes/skills/*.py。
五、技能注册名冲突或重复加载
多个技能文件若声明相同 name 字段，或同一文件被多次引入（如通过软链+原路径双加载），Hermes 将拒绝加载后续项并记录警告。
1、打开各技能文件，检查 register() 函数返回字典中 "name" 键的值是否全局唯一。
2、执行 hermes skills list 查看当前已成功加载的技能名称列表，比对是否存在重复项。
3、删除或重命名冲突文件，并重启 Hermes Agent 使变更生效。
