CocoLoop

SKILL.md

---
name: cocoloop
version: 0.5
description: 一个更快速、更安全的 Skill 管理器。CLI 只负责网络 API wrapper 和已知安装流程 wrapper；搜索判断、fallback 探索和复杂编排由 Agent 自己完成。
---

# Cocoloop Skill 管理器

Cocoloop 的目标很直接：先找到 skill 文件，再把它安装到当前 Agent 平台真正会读取的位置。搜索和安装是两段流程，来源可以变，落盘和校验流程保持一致。

## 核心原则

1. 先识别当前 Agent 平台，再决定安装目录和安装方式。
2. 搜索优先级固定为 `CocoLoop API -> ClawHub -> skills.sh -> GitHub -> 自由探索`。
3. 只要拿到 skill 文件或 skill 目录，就统一进入“标准化 -> 安装 -> 校验”流程。
4. 尽量保留原始目录结构：`SKILL.md`、`scripts/`、`references/`、`assets/`、`agents/`。
5. 来源越陌生，越要主动提醒用户执行 CLS 安全检查。
6. 默认先把 skill 内容安装到 `~/.cocoloop/skills/`，再通过软链接发布到目标平台目录；只有当前平台确实不支持软链接时，才退回复制。

## CLI 与 Agent 的分工

先把边界守住，再开始安装。

### CLI 只做两类事

1. 网络 API wrapper
2. 已知安装流程 wrapper

当前可以直接信任 CLI 的动作：

- `cocoloop search --query ...`
- `cocoloop featured`
- `cocoloop featured --categories`
- `cocoloop featured --category ...`
- `cocoloop inspect ...`
- `cocoloop paths`
- `cocoloop healthcheck`
- `cocoloop safescan ...`
- `cocoloop install ...`
- `cocoloop uninstall ...`
- `cocoloop update ...`

### Agent 负责粘合

下面这些都不要交给 CLI 自己做判断：

1. 搜索结果里哪一个才是用户真正想装的 skill
2. 官方没命中后要不要继续 fallback
3. 页面链接、GitHub 子目录、说明页、文章页该怎么继续追 source
4. 已知安装流程失败后怎么改走手工探索
5. 什么时候该让用户确认，什么时候可以直接继续
6. 当前环境不在已知平台名单里时，如何先确认正确安装方式和正确配置方法

### 推荐执行顺序

1. 先用 `search` 一次性读取官方结果和本地已知 Agent 结果
2. 如果本地已知 Agent 已经存在候选，先询问用户是否要移植到当前环境
3. 如果返回 `review-required` 或 `no-results`，由 Agent 判断或询问用户
4. 当 Agent 已经拿到明确 source，再决定要不要调用 `install`
5. 如果 `install` 返回 `handoff-to-agent`，说明 CLI 不该继续猜，Agent 需要自己完成后续探索和安装
6. 安装完成后，提醒用户立即测试 skill 是否能被当前 Agent 正确发现和调用

### 首次安装 Cocoloop 后的下一步引导

如果刚刚安装完成的是 `cocoloop` 自己，而且用户看起来是第一次在当前 Agent 环境里安装或启用 Cocoloop，不要只停在“请测试是否可用”。

这时追加一步轻量询问：

- 先提醒用户做一次实际调用测试
- 再询问用户现在要不要看主站热门 skill 推荐

推荐问法：

`如果你愿意，我也可以现在顺手给你看一组主站热门 skill 推荐，帮你继续补齐常用能力。`

如果用户同意，再调用：

- `bash scripts/cocoloop.sh featured`
- 需要分类时，再调用 `bash scripts/cocoloop.sh featured --categories`

如果用户暂时不需要，不继续主动展开推荐列表。

## 主站精选推荐路由

当用户意图是看主站当前推荐技能，而不是按名字搜索时，优先走独立精选入口：

- 用户想看“主站最新推荐 skill”“精选推荐”“首页推荐 skill”时，调用 `bash scripts/cocoloop.sh featured`
- 用户想看“推荐分类”“精选分类”时，调用 `bash scripts/cocoloop.sh featured --categories`
- 用户已经拿到分类名，还想继续看“这个分类下面有哪些精选 skill”时，调用 `bash scripts/cocoloop.sh featured --category "<分类>"`

这个入口只做官方接口 wrapper 和结果展示，不负责替用户做安装判断。需要继续查看详情、比较候选或安装时，再由 Agent 决定是否调用 `inspect`、`search` 或 `install`

## 平台检测与安装目的地

先判断当前环境更接近哪个 Agent 生态，再选择项目级安装或用户级安装。

| 平台 | 项目级目录 | 用户级目录 | 兼容目录 | 配置示范 |
| --- | --- | --- | --- | --- |
| OpenCode | `.opencode/skills/<skill-name>/` | `~/.config/opencode/skills/<skill-name>/` | `.claude/skills/<skill-name>/`、`.agents/skills/<skill-name>/` 也可被 OpenCode 发现 | `opencode.json` / `~/.config/opencode/opencode.json` |
| Codex | `.agents/skills/<skill-name>/` | `$HOME/.agents/skills/<skill-name>/` | `$HOME/.codex/skills/<skill-name>/` | `~/.codex/config.toml` |
| Claude Code | `.claude/skills/<skill-name>/` | `~/.claude/skills/<skill-name>/` | 无必需兼容目录 | `~/.claude/settings.json` / `.claude/settings.json` |
| OpenClaw | `skills/<skill-name>/` 或 `.agents/skills/<skill-name>/` | `~/.agents/skills/<skill-name>/` 或 `~/.openclaw/skills/<skill-name>/` | `~/.openclaw/skills/<skill-name>/` | `~/.openclaw/openclaw.json` |
| Molili | 无独立项目级目录，直接使用用户级 active skills 目录 | macOS/Linux: `~/.molili/workspaces/default/active_skills/<skill-name>/`；Windows: `\\.molili\\workspaces\\default\\active_skills\\<skill-name>\\` | 无额外兼容目录 | 以 `active_skills` 目录为准 |

安装选择规则：

1. 用户明确要求“当前仓库可用”或“团队共享”时，优先装到项目级目录。
2. 用户明确要求“全局可用”或“所有项目都能用”时，优先装到用户级目录。
3. 如果来源平台自带原生安装器，而且安装目标与当前 Agent 兼容，可以优先使用原生命令。
4. 如果原生安装器不兼容或无法确认落点，回退到手动落盘安装。

统一实现规则：

1. 真实 skill 内容默认先写入 `~/.cocoloop/skills/<skill-name>/`
2. 目标平台目录默认放软链接
3. 当前平台确实不支持软链接时，才直接复制到目标平台目录

Molili 例外说明：

1. Molili 当前按用户级目录安装
2. 安装动作就是把 skill 目录移动到 `active_skills` 目录
3. 这一步可以直接用 Bash 完成，不需要额外注册

## 单个 Skill 安装流程

用户输入通常分成四类：

### 1. 直接文件或 URL

输入示例：

- `https://example.com/skill.zip`
- `https://example.com/downloads/cocoloop.skill`
- `/tmp/my-skill/`

处理步骤：

1. 用 `curl -L` 或等价方式下载文件，或直接读取本地目录。
2. 如果是压缩包，解压到临时目录。
3. 自动寻找包含 `SKILL.md` 的 skill 根目录。
4. 读取 frontmatter，确定 `name`、`description` 和可选 `version`。
5. 进入“统一安装步骤”。

### 2. Skill 名称搜索

输入示例：

- `pdf`
- `rsshub`
- `github-trending`

处理步骤：

1. 先调用 CocoLoop search API 搜索。
2. 如果 CocoLoop 没找到，CLI 到这里先停住。
3. 接下来由 Agent 按 ClawHub、skills.sh、GitHub、公开网页的顺序继续找 source。
4. 一旦 Agent 拿到明确 skill 文件、压缩包或仓库目录，再进入“统一安装步骤”。

### 3. GitHub 仓库链接或短链

输入示例：

- `owner/repo`
- `https://github.com/owner/repo`
- `https://github.com/owner/repo/tree/main/skills/foo`

处理步骤：

1. 获取仓库信息，确认是否存在 `SKILL.md`。
2. 如果仓库根目录就是 skill 根目录，可以交给 `install` 处理。
3. 如果需要继续判断子目录、分支或额外文件结构，交给 Agent 探索。
4. 当 source 已经清晰，再进入“统一安装步骤”。

### 4. 平台页面或文章页

输入示例：

- `https://skills.sh/...`
- `https://clawhub.ai/...`
- 某篇博客、说明页、发布页

处理步骤：

1. 先判断页面里是否直接给出安装命令、下载链接或仓库地址。
2. 页面解析、按钮跟踪、release 资产定位都由 Agent 完成。
3. CLI 不负责解析说明页或文章页。
4. Agent 拿到明确文件后，再进入“统一安装步骤”。

## 未识别环境处理

如果当前环境没有命中已知平台，不要先安装。

正确做法：

1. 先根据当前 Agent 环境去探索正确的 skill 安装目录和发现机制
2. 再确认这个环境如何判断“skill 已被正确配置”
3. 只有弄清楚正确安装方式和正确配置方法后，再继续安装
4. 安装完成后，提醒用户立刻做一次实际调用测试

## 搜索优先级

### 第一优先级：CocoLoop API

名称搜索时先查 CocoLoop。优先使用命令行 HTTP 请求工具，例如：

```bash
curl -L "https://api.cocoloop.com/api/v1/store/skills?page=1&page_size=10&keyword=${KEYWORD}&sort=downloads"
```

预期目标：

- 拿到官方候选列表
- 把搜索结果交给 Agent 判断
- 如果返回多个候选，让 Agent 或用户先确认，再继续

### 第二优先级：ClawHub、skills.sh、GitHub

如果 CocoLoop 搜不到，按下面顺序继续：

1. ClawHub
2. skills.sh
3. GitHub

这里的继续探索由 Agent 执行，不由 CLI 直接编排。

每个来源都遵守同一个原则：

- 能直接拿到 skill 文件，就下载文件
- 能直接拿到仓库，就下载仓库
- 能直接调用平台原生安装器，并且安装结果与当前 Agent 平台兼容，就优先用原生命令
- 如果原生命令不可用，退回手动落盘安装

### 第三优先级：自由探索

如果前面都失败，就继续探索公开网页、发布页、文档站和搜索结果。

自由探索的目标不是“找到一个网页”，而是“拿到一个可安装的 skill 目录或压缩包”。这一步由 Agent 完成。只要拿到文件，就回到统一安装流程。

## 统一安装步骤

所有来源最终都要走下面这套流程：

1. 在临时目录中整理出 skill 根目录。
2. 确认根目录包含 `SKILL.md`。
3. 保留并复制同级资源目录：`scripts/`、`references/`、`assets/`、`agents/`。
4. 按当前平台选择目标目录。
5. 如果目标目录已存在：
   - 安装请求：覆盖前提醒用户
   - 更新请求：视为就地更新
6. 复制 skill 目录到目标路径。
7. 进行一次安装后校验：
   - 目标目录存在
   - `SKILL.md` 可读
   - 关键资源目录没有丢失
8. 需要时提醒用户重启或刷新当前 Agent。

## 平台安装示范

### Codex

推荐落点：

- 仓库共享：`.agents/skills/<skill-name>/`
- 用户全局：`$HOME/.agents/skills/<skill-name>/`
- 兼容社区安装器：`$HOME/.codex/skills/<skill-name>/`

禁用某个 skill 的配置示范：

```toml
[[skills.config]]
path = "/Users/you/.agents/skills/cocoloop/SKILL.md"
enabled = false
```

说明：

- 官方文档当前主推 `.agents/skills`。
- 如果来源是 `skills.sh` 一类社区安装器，可能仍会把全局 skill 放到 `~/.codex/skills/`。
- 当两套目录同时存在时，应优先告诉用户真实写入位置。

### Claude Code

推荐落点：

- 仓库共享：`.claude/skills/<skill-name>/`
- 用户全局：`~/.claude/skills/<skill-name>/`

配置说明：

- Claude Code 的 skill 发现主要依赖目录本身，不需要额外登记一个 skill 清单。
- 如果用户还要同步团队级设置，再写 `.claude/settings.json`。
- 如果只想本地生效，使用 `~/.claude/skills/` 或 `.claude/settings.local.json` 相关配置。

### OpenClaw

推荐落点：

- 仓库共享：`skills/<skill-name>/` 或 `.agents/skills/<skill-name>/`
- 用户全局：`~/.agents/skills/<skill-name>/` 或 `~/.openclaw/skills/<skill-name>/`

常见配置示范：

```json
{
  "skills": {
    "load": {
      "extraDirs": [
        "/Users/you/.agents/skills",
        "/Users/you/.openclaw/skills"
      ]
    }
  }
}
```

说明：

- OpenClaw 环境常见多目录并存。
- 如果项目里已经有 `skills/` 或 `.agents/skills/`，优先复用现有结构。
- 如果用户想把多个个人 skill 统一托管，优先使用用户级目录，再通过配置补充额外扫描路径。

## 平台原生安装器示范

这些命令只能作为优先尝试项，执行前仍要判断它们是否真的适合当前 Agent 平台。

### ClawHub

如果当前环境已经依赖 ClawHub 工作流，可以优先尝试：

```bash
npx clawhub@latest install <skill-name>
```

如果命令成功，但无法确认安装到了哪里，要继续检查真实落点，再向用户汇报。

### skills.sh

如果 skills.sh 页面已经给出明确仓库和 skill 名称，可以优先尝试：

```bash
npx skills add https://github.com/owner/repo --skill <skill-name>
```

如果 skills.sh 把 skill 安装到了社区兼容目录，也要在结果里明确写出真实路径。

## 批量安装

批量安装时，把每个 skill 当成独立任务执行：

1. 逐个搜索
2. 逐个获取文件
3. 逐个安装
4. 汇总结果

一个 skill 失败，不影响其他 skill 继续安装。

## 更新与卸载

### 更新

1. 先找到当前 skill 的真实安装目录。
2. 再走一次同名 skill 搜索与获取文件流程。
3. 用统一安装步骤覆盖已有目录。
4. 保留旧目录备份是加分项，不是必须项。

### 卸载

详见 [references/uninstall-guide.md](references/uninstall-guide.md)。

关键点：

1. 先在当前平台的全部候选目录中定位 skill。
2. 删除真正安装的那一份。
3. 如果有额外配置引用了该路径，也要提醒用户同步清理。

## 安全检查

详见 [references/safety-check-guide.md](references/safety-check-guide.md) 和 [references/cocoloop-safe-check.md](references/cocoloop-safe-check.md)。

安装类任务里建议这样做：

1. T1/T2 来源：默认提示可选检查
2. T3 或自由探索来源：默认建议先检查再安装
3. 如果发现动态代码加载、多层网络执行或高危命令，优先阻断并说明原因

## 资源引用

- [安装流程详细指南](references/install-guide.md)
- [搜索流程详细指南](references/search-guide.md)
- [卸载流程详细指南](references/uninstall-guide.md)
- [安全检查流程指南](references/safety-check-guide.md)
- [Cocoloop Safe Check 安全检查标准](references/cocoloop-safe-check.md)