Loopal SkillHub Skill 操作指南

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

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

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

操作原则

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

搜索 Skill

loopal skill search <keyword> --json

可以按分类或标签过滤：

loopal skill search <keyword> --category <category-slug> --tag <tag-slug> --json

查看 Skill 详情

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

loopal skill info <slug> --json

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

安装 Skill

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

loopal skill install <slug> --dir <skills-directory> --json

最终安装位置为：

<skills-directory>/<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

下载 Skill 包

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

loopal skill download <slug> --dir <download-directory> --json

CLI 会保存为：

<download-directory>/<slug>-<version>.zip

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

loopal skill download <slug> --output <zip-file-path> --json

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

已存在的 Skill

如果 <skills-directory>/<slug> 已存在：

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

loopal skill install <slug> --dir <skills-directory> --force --json

验证安装结果

安装完成后确认：

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

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