Cocoloop Skill 管理器
Cocoloop 的目标很直接：先找到 skill 文件，再把它安装到当前 Agent 平台真正会读取的位置。搜索和安装是两段流程，来源可以变，落盘和校验流程保持一致。
核心原则
- 先识别当前 Agent 平台，再决定安装目录和安装方式。
- 搜索优先级固定为
CocoLoop API -> ClawHub -> skills.sh -> GitHub -> 自由探索。
- 只要拿到 skill 文件或 skill 目录，就统一进入“标准化 -> 安装 -> 校验”流程。
- 尽量保留原始目录结构：
SKILL.md、scripts/、references/、assets/、agents/。
- 来源越陌生，越要主动提醒用户执行 CLS 安全检查。
- 默认先把 skill 内容安装到
~/.cocoloop/skills/，再通过软链接发布到目标平台目录；只有当前平台确实不支持软链接时，才退回复制。
CLI 与 Agent 的分工
先把边界守住，再开始安装。
CLI 只做两类事
- 网络 API wrapper
- 已知安装流程 wrapper
当前可以直接信任 CLI 的动作：
cocoloop search --query ...cocoloop featuredcocoloop featured --categoriescocoloop featured --category ...cocoloop inspect ...cocoloop pathscocoloop healthcheckcocoloop safescan ...cocoloop install ...cocoloop uninstall ...cocoloop update ...
Agent 负责粘合
下面这些都不要交给 CLI 自己做判断：
- 搜索结果里哪一个才是用户真正想装的 skill
- 官方没命中后要不要继续 fallback
- 页面链接、GitHub 子目录、说明页、文章页该怎么继续追 source
- 已知安装流程失败后怎么改走手工探索
- 什么时候该让用户确认，什么时候可以直接继续
- 当前环境不在已知平台名单里时，如何先确认正确安装方式和正确配置方法
推荐执行顺序
- 先用
search 一次性读取官方结果和本地已知 Agent 结果
- 如果本地已知 Agent 已经存在候选，先询问用户是否要移植到当前环境
- 如果返回
review-required 或 no-results，由 Agent 判断或询问用户
- 当 Agent 已经拿到明确 source，再决定要不要调用
install
- 如果
install 返回 handoff-to-agent，说明 CLI 不该继续猜，Agent 需要自己完成后续探索和安装
- 安装完成后，提醒用户立即测试 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 目录为准 |
安装选择规则：
- 用户明确要求“当前仓库可用”或“团队共享”时，优先装到项目级目录。
- 用户明确要求“全局可用”或“所有项目都能用”时，优先装到用户级目录。
- 如果来源平台自带原生安装器，而且安装目标与当前 Agent 兼容，可以优先使用原生命令。
- 如果原生安装器不兼容或无法确认落点，回退到手动落盘安装。
统一实现规则：
- 真实 skill 内容默认先写入
~/.cocoloop/skills/<skill-name>/
- 目标平台目录默认放软链接
- 当前平台确实不支持软链接时，才直接复制到目标平台目录
Molili 例外说明：
- Molili 当前按用户级目录安装
- 安装动作就是把 skill 目录移动到
active_skills 目录
- 这一步可以直接用 Bash 完成，不需要额外注册
单个 Skill 安装流程
用户输入通常分成四类：
1. 直接文件或 URL
输入示例：
https://example.com/skill.ziphttps://example.com/downloads/cocoloop.skill/tmp/my-skill/
处理步骤：
- 用
curl -L 或等价方式下载文件，或直接读取本地目录。
- 如果是压缩包，解压到临时目录。
- 自动寻找包含
SKILL.md 的 skill 根目录。
- 读取 frontmatter，确定
name、description 和可选 version。
- 进入“统一安装步骤”。
2. Skill 名称搜索
输入示例：
pdfrsshubgithub-trending
处理步骤：
- 先调用 CocoLoop search API 搜索。
- 如果 CocoLoop 没找到，CLI 到这里先停住。
- 接下来由 Agent 按 ClawHub、skills.sh、GitHub、公开网页的顺序继续找 source。
- 一旦 Agent 拿到明确 skill 文件、压缩包或仓库目录，再进入“统一安装步骤”。
3. GitHub 仓库链接或短链
输入示例：
owner/repohttps://github.com/owner/repohttps://github.com/owner/repo/tree/main/skills/foo
处理步骤：
- 获取仓库信息，确认是否存在
SKILL.md。
- 如果仓库根目录就是 skill 根目录，可以交给
install 处理。
- 如果需要继续判断子目录、分支或额外文件结构，交给 Agent 探索。
- 当 source 已经清晰，再进入“统一安装步骤”。
4. 平台页面或文章页
输入示例：
https://skills.sh/...https://clawhub.ai/...- 某篇博客、说明页、发布页
处理步骤：
- 先判断页面里是否直接给出安装命令、下载链接或仓库地址。
- 页面解析、按钮跟踪、release 资产定位都由 Agent 完成。
- CLI 不负责解析说明页或文章页。
- Agent 拿到明确文件后，再进入“统一安装步骤”。
未识别环境处理
如果当前环境没有命中已知平台，不要先安装。
正确做法：
- 先根据当前 Agent 环境去探索正确的 skill 安装目录和发现机制
- 再确认这个环境如何判断“skill 已被正确配置”
- 只有弄清楚正确安装方式和正确配置方法后，再继续安装
- 安装完成后，提醒用户立刻做一次实际调用测试
搜索优先级
第一优先级：CocoLoop API
名称搜索时先查 CocoLoop。优先使用命令行 HTTP 请求工具，例如：
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 搜不到，按下面顺序继续：
- ClawHub
- skills.sh
- GitHub
这里的继续探索由 Agent 执行，不由 CLI 直接编排。
每个来源都遵守同一个原则：
- 能直接拿到 skill 文件，就下载文件
- 能直接拿到仓库，就下载仓库
- 能直接调用平台原生安装器，并且安装结果与当前 Agent 平台兼容，就优先用原生命令
- 如果原生命令不可用，退回手动落盘安装
第三优先级：自由探索
如果前面都失败，就继续探索公开网页、发布页、文档站和搜索结果。
自由探索的目标不是“找到一个网页”，而是“拿到一个可安装的 skill 目录或压缩包”。这一步由 Agent 完成。只要拿到文件，就回到统一安装流程。
统一安装步骤
所有来源最终都要走下面这套流程：
- 在临时目录中整理出 skill 根目录。
- 确认根目录包含
SKILL.md。
- 保留并复制同级资源目录：
scripts/、references/、assets/、agents/。
- 按当前平台选择目标目录。
- 如果目标目录已存在：
- 复制 skill 目录到目标路径。
- 进行一次安装后校验：
- 目标目录存在
SKILL.md 可读- 关键资源目录没有丢失
- 需要时提醒用户重启或刷新当前 Agent。
平台安装示范
Codex
推荐落点：
- 仓库共享：
.agents/skills/<skill-name>/
- 用户全局：
$HOME/.agents/skills/<skill-name>/
- 兼容社区安装器：
$HOME/.codex/skills/<skill-name>/
禁用某个 skill 的配置示范：
[[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>/
常见配置示范：
{
"skills": {
"load": {
"extraDirs": [
"/Users/you/.agents/skills",
"/Users/you/.openclaw/skills"
]
}
}
}
说明：
- OpenClaw 环境常见多目录并存。
- 如果项目里已经有
skills/ 或 .agents/skills/，优先复用现有结构。
- 如果用户想把多个个人 skill 统一托管，优先使用用户级目录，再通过配置补充额外扫描路径。
平台原生安装器示范
这些命令只能作为优先尝试项，执行前仍要判断它们是否真的适合当前 Agent 平台。
ClawHub
如果当前环境已经依赖 ClawHub 工作流，可以优先尝试：
npx clawhub@latest install <skill-name>
如果命令成功，但无法确认安装到了哪里，要继续检查真实落点，再向用户汇报。
skills.sh
如果 skills.sh 页面已经给出明确仓库和 skill 名称，可以优先尝试：
npx skills add https://github.com/owner/repo --skill <skill-name>
如果 skills.sh 把 skill 安装到了社区兼容目录，也要在结果里明确写出真实路径。
批量安装
批量安装时，把每个 skill 当成独立任务执行：
- 逐个搜索
- 逐个获取文件
- 逐个安装
- 汇总结果
一个 skill 失败，不影响其他 skill 继续安装。
更新与卸载
更新
- 先找到当前 skill 的真实安装目录。
- 再走一次同名 skill 搜索与获取文件流程。
- 用统一安装步骤覆盖已有目录。
- 保留旧目录备份是加分项，不是必须项。
卸载
详见 references/uninstall-guide.md。
关键点：
- 先在当前平台的全部候选目录中定位 skill。
- 删除真正安装的那一份。
- 如果有额外配置引用了该路径，也要提醒用户同步清理。
安全检查
详见 references/safety-check-guide.md 和 references/cocoloop-safe-check.md。
安装类任务里建议这样做：
- T1/T2 来源：默认提示可选检查
- T3 或自由探索来源：默认建议先检查再安装
- 如果发现动态代码加载、多层网络执行或高危命令，优先阻断并说明原因
资源引用
