Loopal SkillHub 技能操作指南

本文档供 AI Agent 执行 Loopal 技能市场操作。用户可以这样提出安装请求：

请根据 https://loopal.app/install/skillhub.md，安装 pdf-fast-handler-skill。

本文档只说明 loopal skill 相关操作。公共技能的搜索、详情、下载和安装不需要 API Key。

操作原则

• 只操作用户明确指定的技能，不安装其他推荐技能。
• 用户提供的技能名称优先作为精确 Slug 查询。
• 精确查询失败时才能搜索；只有相似结果时必须让用户确认，不能自行选择。
• --dir 必须指向当前 Agent 实际使用的 Skills 根目录。

搜索技能

loopal skill search <关键词> --json

可以按分类或标签过滤：

loopal skill search <关键词> --category <分类slug> --tag <标签slug> --json

查看技能详情

安装前先使用精确 Slug 查询：

loopal skill info <slug> --json

确认返回的 skill.slug 与用户指定值完全一致后再安装。

安装技能

先确定当前 Agent 使用的 Skills 根目录，再执行：

loopal skill install <slug> --dir <skills目录> --json

最终安装位置为：

<skills目录>/<slug>

常见目录：

• Codex：项目级 .agents/skills，用户级 ~/.codex/skills。
• Claude Code：项目级 .claude/skills，用户级 ~/.claude/skills。
• Cursor：项目级 .cursor/skills，用户级 ~/.cursor/skills。
• Windsurf：项目级 .windsurf/skills，用户级 ~/.codeium/windsurf/skills。
• Gemini CLI：项目级 .gemini/skills，用户级 ~/.gemini/skills。

优先使用当前项目已经配置的 Skills 目录。无法判断时向用户确认，不要猜测。

路径包含空格时必须加引号。例如 Windows PowerShell：

loopal skill install <slug> --dir "C:\Users\User Name\.codex\skills" --json

下载技能包

只下载原始 ZIP、不安装时，指定存放目录：

loopal skill download <slug> --dir <下载目录> --json

CLI 会保存为：

<下载目录>/<slug>-<version>.zip

需要自定义文件名时使用完整输出路径：

loopal skill download <slug> --output <ZIP文件路径> --json

--dir 和 --output 不能同时使用。

已存在的技能

如果 <skills目录>/<slug> 已存在：

• 版本相同且文件完整：报告技能已经安装，不重复覆盖。
• 用户明确要求更新、重装或修复：添加 --force。

loopal skill install <slug> --dir <skills目录> --force --json

验证安装结果

安装完成后确认：

1. 命令退出码为 0，JSON 中 success 为 true。
2. 返回的 installedPath 位于预期的 Skills 根目录。
3. <installedPath>/SKILL.md 存在。
4. <installedPath>/.loopal-skill.json 中的 slug 和 version 与安装结果一致。

最后向用户报告技能 Slug、版本和实际安装目录。只有当前 Agent 无法动态发现新技能时，才建议重新加载或重启。