若hermes skill install失败，需依次检查：一、技能源可达性（测github连接/换镜像）；二、~/.hermes/skills/目录权限与磁盘空间；三、python虚拟环境及pip完整性；四、git受限时改用离线zip安装；五、skill.yaml语法与必填字段是否合规。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试安装 Hermes Agent 社区技能（如 GitHub、Notion、Slack 等第三方 Skill），但执行 hermes skill install
一、验证技能仓库可访问性与镜像可用性
社区技能默认从 GitHub 仓库 https://github.com/Hermes-AI-Skills/ 拉取，若该域名解析失败、网络策略拦截或国内直连超时，将导致 fetch 步骤中断，表现为“Failed to clone skill repo”或空响应。
1、测试基础连接：运行 curl -I https://github.com/Hermes-AI-Skills，确认返回 HTTP 302 或 200。
2、若超时或拒绝连接，改用国内镜像源：执行 hermes config set skill.repo https://gitcode.com/GitHub_Trending/hermes-ai-skills。
3、手动验证镜像仓库结构：运行 curl -s https://gitcode.com/GitHub_Trending/hermes-ai-skills/tree/main | head -n 20，检查是否返回 HTML 片段含 skill 目录列表。
二、检查技能安装目录写入权限与磁盘空间
Hermes Agent 将技能解压至 ~/.hermes/skills/ 目录下对应子目录，若该路径所在分区满载、父目录不可写或 SELinux/AppArmor 限制，会导致 unpack 或 symlink 失败，错误信息含 “Permission denied” 或 “No space left on device”。
1、检查家目录剩余空间：运行 df -h ~ | awk 'NR==2 {print $5}'，确认输出值低于 90%。
2、验证 ~/.hermes/skills/ 可写：执行 touch ~/.hermes/skills/.test_write && rm ~/.hermes/skills/.test_write，无报错即通过。
3、若提示权限不足，修复目录所有权：运行 chown -R $USER:$USER ~/.hermes。
三、确认 Python 虚拟环境已激活且依赖完整
部分社区技能（如 notion-sync、slack-bot）需额外 Python 包支持，其安装流程依赖 Hermes 自身的 venv（通常位于 ~/.local/share/hermes/venv）。若该环境未初始化、被破坏或缺少 pip，将跳过依赖安装，导致技能 runtime 报错 ImportError。
1、定位 Hermes venv 路径：运行 hermes info | grep 'Python venv'，获取实际路径。
2、进入该 venv 并检查 pip 是否可用：执行 ~/.local/share/hermes/venv/bin/python -m pip --version。
3、若报错 “No module named pip”，手动引导：运行 ~/.local/share/hermes/venv/bin/python -m ensurepip --upgrade。
四、绕过 Git 克隆，采用离线包安装方式
当系统禁用 Git、SSH 端口受限或 git config 全局代理失效时，hermes skill install 命令无法调用 git clone，直接退出。此时可跳过自动拉取，使用本地 ZIP 包完成安装。
1、从镜像站下载目标技能 ZIP：例如 curl -L https://gitcode.com/GitHub_Trending/hermes-ai-skills/-/archive/main.zip -o skills-main.zip。
2、解压并提取指定技能目录：运行 unzip skills-main.zip "hermes-ai-skills-main/skills/
3、手动复制至技能目录：执行 cp -r /tmp/hermes-skill-tmp/hermes-ai-skills-main/skills/
4、触发注册：运行 hermes skill register
五、排查技能元数据格式与 YAML 解析错误
每个技能根目录下必须包含 skill.yaml 文件，若该文件存在语法错误（如缩进不一致、冒号后缺空格、中文引号）、字段缺失（如 name、version、entry），Hermes 在加载阶段会静默跳过该技能，且不报明确错误，仅在 hermes skill list 中不可见。
1、进入目标技能目录：运行 cd ~/.hermes/skills/
2、校验 YAML 格式：执行 python -c "import yaml; print(yaml.safe_load(open('skill.yaml')))" 2>/dev/null || echo 'YAML parse failed'。
3、检查必填字段：运行 grep -E '^(name|version|entry):' skill.yaml | wc -l，输出应为 3。
4、确认 entry 脚本存在且可执行：执行 test -f $(grep entry skill.yaml | cut -d' ' -f2) && test -x $(grep entry skill.yaml | cut -d' ' -f2)。
