wshobson/agents 保姆级部署教程：多平台智能体插件市场

一句话定位：GitHub 开源项目 wshobson/agents 是一个多宿主（Multi-harness）智能体插件市场——同一份 Markdown 源码里的插件、子智能体、技能与命令，经过适配器自动生成后，可同时装载进 Claude Code、OpenAI Codex CLI、Cursor、OpenCode、Antigravity CLI、GitHub Copilot 与 Pi 这七款主流 AI 编码工具，不用在每个工具里重复造轮子。

slogan：Use one collection of plugins, agents, skills, and commands across Claude Code, OpenAI Codex CLI, Cursor, OpenCode, Antigravity CLI, GitHub Copilot, and Pi.

仓库地址：https://github.com/wshobson/agents · 许可证：MIT · ⭐ 42,053 · 默认分支 main

▲ 图 1：wshobson/agents 仓库官方 Star History 增长曲线（数据来自 star-history.dera.page，仓库 README 内嵌）

一、项目简介

wshobson/agents 解决的是一个非常现实的痛点：现在 AI 编码工具太多了，Claude Code、Codex CLI、Cursor、OpenCode、Copilot……每家都有自己的插件/智能体/技能格式，你在 A 工具里调好了一套「Python 开发 + 安全扫描」的专家子智能体，换到 B 工具就得重写一遍。这个仓库把所有组件统一维护成一份 Claude Code 插件格式的 Markdown 源码，再由内置适配器（adapter）按各宿主的规范自动生成对应产物——原生支持的宿主直接指向源文件，不支持的宿主由生成器产出对应格式的副本，命令在不同宿主里可能变成技能或提示词模板，模型别名（opus/sonnet/haiku/fable/inherit）也会被映射到各宿主自己的模型设置上。

截至 README 最新版本，仓库目录里共有 94 个插件（其中 92 个本地插件、2 个外部条目），本地源码包含 202 个 agent、185 个 skill、105 个 command。插件按工作域分组，覆盖 Python/JavaScript 开发、代码评审、调试、Git、测试、基础设施、安全扫描等日常研发场景。项目以 MIT 许可证开源，完整代码与文档托管在 GitHub 仓库。

二、功能特点

三、环境要求

• 宿主工具：至少装好以下之一——Claude Code、OpenAI Codex CLI、Cursor、OpenCode、Antigravity CLI、GitHub Copilot CLI、Pi；使用相应安装路线时该工具必须已在终端可用。
• Python 与 uv：从克隆仓库走 make install-* 路线时，需要安装 uv 以及 Python 3.12 或更高版本。
• GitHub CLI：使用 gh skill install 单技能安装器需要 GitHub CLI 2.90 或更高版本；使用 gh repo clone 克隆仓库也依赖 gh。
• Node.js / npm：使用 npx skills 安装器需要本机具备 Node.js 与 npm。
• 网络：能访问 GitHub 拉取仓库与 marketplace；首次运行 make install-* 时会通过 uv 安装插件评估相关依赖。
• Pi 的子智能体扩展：Pi 宿主要跑 agents 组件，还需要其官方 subagent 参考扩展或兼容扩展。

四、保姆级部署步骤

本仓库按你使用的宿主分四条安装路线，挑你自己那条即可，不需要全跑。

4.1 Claude Code（原生插件市场）

在 Claude Code 会话里依次执行下面两条斜杠命令，先注册市场再安装 Python 开发插件：

/plugin marketplace add wshobson/agents
/plugin install python-development@claude-code-workflows

装完后直接让 Claude 用 Python 智能体干活，或跑插件自带的脚手架命令：

/python-development:python-scaffold Create a FastAPI service with tests

Claude Code 是原生支持最完整的宿主：源 agent、skill、command 直接加载，还支持插件级 hooks 与 MCP 配置。

4.2 OpenAI Codex CLI（原生 marketplace）

在终端里（不是在 Codex 会话里）执行：

codex plugin marketplace add wshobson/agents
codex plugin add python-development@claude-code-workflows

原生 Codex 清单会暴露源 skill；生成的 TOML 格式 agent 与由 command 派生的 skill 走另一条适配器路径，会把超过 8 KB 的大块正文拆成引用文件。选安装路线前建议先看 README 里指向的 Codex setup 细节。

4.3 Cursor

Cursor 直接读取仓库里已经提交的 .cursor-plugin/marketplace.json 注册文件，按官方 harnesses 文档里的 Cursor 章节添加市场并安装插件即可。安装后源 agent、skill、command 都会加载，并附带经过策划的项目规则（project rules）。

4.4 OpenCode / Antigravity CLI / GitHub Copilot / Pi（克隆仓库安装）

这四款工具走「克隆仓库 + make 安装器」路线。先用 gh 克隆：

gh repo clone wshobson/agents ~/agents
cd ~/agents

然后按你用的工具跑对应的一条命令，安装器会自动生成对应产物并把所有本地插件链接进该工具的用户配置：

# OpenCode
make install-opencode

# Antigravity CLI
make install-antigravity

# GitHub Copilot
make install-copilot

# Pi
make install-pi

各宿主产出的形态略有差异：OpenCode 拿到的是翻译过工具权限的 agent/skill/command；Antigravity 拿到的是打包好的插件；Copilot 拿到的是生成的 agent profile 与 skill，command 也会变成可调用的 skill；Pi 拿到的是生成的 skill 与提示词模板，agents 还需要额外装 subagent 扩展。

4.5 只想装单个技能（Skills-only）

如果你不想装一整个插件包，只要某一个技能，用下面任一安装器，会在提示时让你选编码工具：

# 方式一：GitHub CLI 安装器（需 gh 2.90+）
gh skill install wshobson/agents python-testing-patterns

# 方式二：npx 安装器（需 Node.js / npm）
npx skills add wshobson/agents --skill python-testing-patterns

两个安装器都直接从 GitHub 读取 skill，不克隆仓库，也不会连带安装该插件的 agent、command 与 hooks。

五、配置说明

本仓库是组件市场，安装后通常无需额外配置，各宿主按自己的发现与调用规则加载组件即可。需要注意的配置点如下：

• 模型别名映射：源 agent 里写的 opus、sonnet、haiku、fable、inherit 会被适配器翻译成各宿主自己的模型设置；其中部分 inherit 条目在适配器里有固定默认值，想换模型请到对应宿主的配置文件里改。
• 全局安装路径：make install-* 会把组件链接到该宿主的用户级配置目录，具体路径与卸载命令见仓库 docs/harnesses.md 的 global install 章节。
• 插件评估：可选跑 LLM judge 与 Monte Carlo 两层实验性评分，需要额外安装 llm 依赖；设置了 ANTHROPIC_API_KEY 就用该 Key 计费，否则走你本机的 Claude Code 登录态。这两层分数未经人工标注校准，只作模型自评与重复仿真参考。
• Pensyve 外部市场：仓库仍保留 Pensyve 作为可选的外部 Claude Code marketplace 条目，由 Major7 Apps 维护；其托管云服务已于 2026-10-01 关闭，需自托管时按其 self-host 文档配置。

六、使用方法

6.1 在 Claude Code 里调用已装插件

以装好的 python-development 插件为例，直接用斜杠命令触发脚手架：

/python-development:python-scaffold Create a FastAPI service with tests

或者直接在对话里说「用 Python 开发那套智能体帮我做这件事」，Claude Code 会按插件里的 agent 描述自动委派给对应专家子智能体。

6.2 浏览插件与技能清单

仓库 docs/ 下有完整目录，按任务域挑插件非常方便：

• 插件按任务与域分类的总表：docs/plugins.md
• 可用 agent 与模型配置：docs/agents.md
• 可用 skill 清单：docs/agent-skills.md
• 命令用法与示例：docs/usage.md

6.3 贡献者本地校验

如果你想改源码或自定义插件，在仓库根目录跑这一组命令做结构与产物校验：

make generate-all
make validate STRICT=1
make garden

也可以用 plugin-eval 对单个 skill 做不调用模型的静态评分：

uv run --project plugins/plugin-eval plugin-eval score plugins/python-development/skills/python-testing-patterns --depth quick

七、常见问题 FAQ

问一：我同时在用 Claude Code 和 Cursor，会不会两边的插件冲突？
答：不会。每条安装路线把组件链接到对应宿主自己的用户配置目录，互相独立。同一份 Markdown 源由适配器在各自宿主侧生成对应格式，原生支持的宿主直接指向源文件。卸载也按宿主分别操作，具体命令见 docs/harnesses.md。

问二：为什么 Codex CLI 装完之后，agent 和 skill 看起来不一样？
答：原生 Codex 清单直接暴露源 skill，而 TOML 格式的 agent 与由 command 派生的 skill 走单独的适配器路径——为了满足 Codex 8 KB 的预算上限，适配器会把超长正文拆成引用文件。这是预期行为，不是安装失败。

问三：gh skill install 报错或者找不到命令？
答：该命令要求 GitHub CLI 2.90 或更高版本，先升级 gh 再试。不想用 gh 可以走 npx skills add wshobson/agents --skill <技能名>，前提是本机有 Node.js 与 npm。两个安装器都不克隆仓库、不装 hooks。

问四：make install-opencode 之类的命令跑不起来？
答：这条路线依赖 uv 和 Python 3.12+，先按 uv 官方安装文档 装好，再确认 Python 版本。同时确保你要装的那个宿主（OpenCode / Antigravity / Copilot / Pi）本身已在终端可用。

问五：plugin-eval 的 LLM judge 评分为什么要消耗我的 API 额度？
答：这是 README 明确说明的实验性能力。设置了 ANTHROPIC_API_KEY 就用该 Key 计费，否则走本机 Claude Code 登录态；Monte Carlo 层会做重复仿真。这两层分数未经人工标注校准，只用于模型自评参考，不要当成任务成功率的保证。

相关链接

• 项目仓库：wshobson/agents
• 插件目录：docs/plugins.md
• 宿主安装差异与能力矩阵：docs/harnesses.md
• 用法指南：docs/usage.md
• 架构说明：ARCHITECTURE.md
• 质量评估：docs/plugin-eval.md
• 贡献与编写约定：CONTRIBUTING.md 与 docs/authoring.md
• uv 安装：Astral uv 官方文档