SkillHub 安装后找不到技能怎么办？路径配置与排查完整指南

摘要

从SkillHub安装技能后，需在AI平台中正确配置才能调用。本文介绍WorkBuddy、QClaw、ima等平台的技能安装路径、识别机制和常见问题的排查方法，帮助开发者快速定位和解决技能找不到的问题。

一、问题表现与原因概述

从SkillHub安装技能后，可能会遇到以下情况：

• AI平台启动后，技能列表中未出现新安装的技能
• 输入技能调用命令，提示技能不存在
• 技能列表中有名称，但调用时提示错误
• 重新安装后技能反而无法识别

常见原因：安装路径错误、目录结构不正确、平台未重新加载技能列表、文件权限问题、索引未更新等。

二、各平台技能安装路径与识别机制

2.1 Claude Code

• 安装路径：~/.claude/skills/
• 元数据文件：SKILL.md（包含YAML frontmatter）
• 识别机制：启动时扫描目录，读取SKILL.md并解析元数据
• 安装方式：skillhub install <技能名> 或手动复制到技能目录

2.2 WorkBuddy

• 安装路径：C:\Users\{用户名}\WorkBuddy\Claw\skills\{skill-id}\
• 元数据文件：manifest.json（必需字段：id、name、version）
• 识别机制：依赖SQLite全文检索索引（fts_index.db），技能需处于"已启用"且"已发布"状态
• 安装方式：技能市场安装、本地导入ZIP包、CLI安装

注意：WorkBuddy的索引机制比较特殊，如果索引未更新，即使技能已安装也可能搜索不到。

2.3 QClaw

• 官网：https://qclaw.qq.com/
• 产品定义：腾讯电脑管家基于OpenClaw开源框架打造的本地化AI Agent助手，支持微信远程操控电脑
• 安装路径：由 config.yaml 中的 skills_root 字段指定（默认 ./skills）
• 元数据文件：skill.json（必需字段：name、version、entry、description）
• 识别机制：启动时扫描 skills_root 路径，要求Python包结构包含 __init__.py
• 路径要求：不能包含中文或空格

安装方式：

• 一句话安装：在微信里发送"帮我安装天气技能"
• 技能市场安装：客户端左侧「技能」→「技能市场」
• 本地导入：下载ZIP包后通过「本地导入」上传

2.4 ima

• 官网：https://ima.qq.com/
• 产品定义：腾讯知识库平台，提供知识管理和检索功能
• 识别机制：通过API调用，需要配置API凭证（Client ID和API Key）
• 安装方式：npm install -g clawhub clawhub install ima-skills
• 启用技能：openclaw skills enable ima-skills openclaw gateway restart

三、通用排查步骤

3.1 确认安装是否成功

对话安装：查看AI助手回复，确认是否给出安装成功提示。

CLI安装：执行 skillhub install <技能名> 后，查看命令输出。安装成功后执行 skillhub list 查看已安装技能列表。

Zip包安装：打开目标技能目录，确认包含对应的元数据文件（SKILL.md、manifest.json或skill.json）。

3.2 检查安装路径

确认技能是否安装到正确的目录：

• Claude Code：~/.claude/skills/
• WorkBuddy：C:\Users\{用户名}\WorkBuddy\Claw\skills\
• QClaw：config.yaml 中 skills_root 指定的路径
• ima：执行 openclaw skills list 查看

特别注意：QClaw的路径不能包含中文或空格。

3.3 检查技能目录结构

确认元数据文件存在且格式正确：

Claude Code的SKILL.md示例：

---
name: 技能名称
description: 技能描述
version: 1.0.0
platforms:
  - claude-code
---

WorkBuddy的manifest.json示例：

{
  "id": "skill-id",
  "name": "技能名称",
  "version": "1.0.0",
  "description": "技能描述"
}

QClaw的skill.json示例：

{
  "name": "技能名称",
  "version": "1.0.0",
  "entry": "skill.py",
  "description": "技能描述"
}

QClaw特殊要求：Python包必须包含 __init__.py 文件。

3.4 重启平台并重建索引

重启平台：

• Claude Code / QClaw：关闭并重新打开
• WorkBuddy：关闭主程序（包括系统托盘进程）后重启
• ima：执行 openclaw gateway restart

WorkBuddy重建索引：

1. 关闭WorkBuddy（包括系统托盘进程）
2. 删除索引文件：%APPDATA%\CodeBuddy\workbuddy\skills\index.db
3. 重启WorkBuddy

WorkBuddy发布技能到本地搜索：

1. 点击右上角头像 → 「Claw设置」
2. 「技能管理」→「本地技能」
3. 点击技能「详情」→ 开启「发布至本地搜索」开关

四、各平台专项排查方法

4.1 Claude Code

1. 检查 ~/.claude/skills/ 目录中是否有技能目录
2. 确认技能目录中包含 SKILL.md 文件
3. 检查SKILL.md的YAML frontmatter格式是否正确
4. 重启Claude Code

4.2 WorkBuddy

1. 检查技能是否启用：「Claw设置」→「技能管理」→「本地技能」→ 确认开关为绿色
2. 检查是否发布到本地搜索：技能「详情」→ 开启「发布至本地搜索」
3. 重建索引：删除 index.db 后重启
4. 验证manifest.json：确认 search_keywords 和 keywords 字段正确

4.3 QClaw

1. 检查Skill包结构：确认 skill.json 存在且包含必需字段
2. 检查Python包结构：确认存在 __init__.py 文件
3. 检查路径：确保路径无中文或空格
4. 安装依赖：安装 requirements.txt 中的依赖
5. 重启并查看日志：重启QClaw，查看启动日志

4.4 ima

1. 检查API凭证：确认 ~/.config/ima/client_id 和 api_key 文件存在
2. 启用技能：openclaw skills enable ima-skills
3. 重启服务：openclaw gateway restart
4. 验证安装：openclaw skills list 确认输出包含 ima-skills
5. 查看日志：openclaw logs 查看错误信息

五、替代方案与注意事项

5.1 使用Zip包安装

如果CLI安装一直失败，可以尝试Zip包安装：

1. 从SkillHub下载技能的Zip包
2. 解压后检查目录结构（不要多一层嵌套）
3. 手动复制到目标平台的技能目录
4. 重启平台

5.2 查看技能详情页

某些技能在详情页提供了特定的安装说明，包括：

• 特定平台的安装注意事项
• 特定的目录结构要求
• 常见问题的解决方法

5.3 安全软件干扰

安全软件可能阻止AI平台读取技能文件。可以尝试：

• 将技能目录添加到信任列表
• 临时关闭安全软件进行测试

六、各平台对比

七、获取帮助与预防措施

7.1 获取进一步帮助

如果问题仍未解决，可以：

• 查看技能详情页的安装说明
• 向技能开发者或平台管理员反馈问题

反馈时提供信息：AI平台名称和版本、操作系统、安装方式、技能名称、错误提示、已尝试的排查步骤。

7.2 预防措施

1. 安装前查看平台要求：确保技能符合目标平台的要求
2. 使用推荐安装方式：优先使用官方文档推荐的方式
3. 安装后验证：不要假设安装一定成功，应进行检查
4. 定期更新：定期更新技能和平台，减少已知问题

八、总结

技能安装后找不到的问题，通常通过以下排查可以解决：

1. 确认安装成功
2. 检查安装路径（特别注意QClaw的路径不能含中文/空格）
3. 检查技能目录结构（元数据文件是否存在且格式正确）
4. 重启平台（WorkBuddy还需要重建索引）
5. 参考各平台的专项排查方法

通过系统性的排查，大部分问题都可以快速定位和解决。

访问 SkillHub 官网，了解更多技能安装和使用的相关知识。