# Loopal SkillHub 技能操作指南

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

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

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

## 操作原则

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

## 搜索技能

```bash
loopal skill search <关键词> --json
```

可以按分类或标签过滤：

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

## 查看技能详情

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

```bash
loopal skill info <slug> --json
```

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

## 安装技能

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

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

最终安装位置为：

```text
<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：

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

## 下载技能包

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

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

CLI 会保存为：

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

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

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

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

## 已存在的技能

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

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

```bash
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 无法动态发现新技能时，才建议重新加载或重启。