plugin-marketplace-setup

插件与技能市场设置

分开交付 技能（可移植的说明）、插件（运行时连接）和 市场（目录），不要混为一谈。

三层结构（规范性）

层	定义	安装单元	Skill Steward 目录
技能	按照 agentskills.io 的 SKILL.md	npx skills add owner/repo --skill name	skills/{name}/
插件	Open Plugin 或供应商清单，以及 hooks/MCP/规则/命令	按 Agent 安装（见矩阵）	plugins/{id}/ (ADR 0004)
市场	插件/技能目录	添加市场，然后安装插件	产品仓库；Skill Steward 使用公开 Git + skills.sh

规则： 只有说明 → 技能。事件钩子或多文件连接 → 插件（通过 ID 引用技能，不要复制 SKILL.md）。

Skill Steward 元插件的含义： 声明式清单、引用的技能 ID、钩子/规则片段，以及经过验证的连接配置文件。这不代表已经提交到宿主市场，也不能在不提示的情况下修改 Cursor/Codex/Claude 配置。针对宿主的安装步骤仍须在 README/文档中明确说明。

公开与私有（决策）

目标	推荐渠道	说明
公开发现	GitHub 公开仓库 + skills.sh	npx skills add owner/repo；索引需要有效的 skills/*/SKILL.md
仅供团队使用的技能（适用于任意 Agent）	私有 GitHub/GitLab 仓库	如果 Agent 可以克隆仓库，可使用相同的 npx skills add org/private-repo；使用部署密钥/SSO
Cursor 团队插件	团队市场 — Dashboard → Settings → Plugins → Import repo	适用于 Teams/Enterprise；私有 GitHub 仓库需包含 .cursor-plugin/marketplace.json
Claude Code 团队	私有 Git 市场	使用带令牌环境变量的 /plugin marketplace add 实现自动更新（Claude 文档）
Codex 团队	$REPO_ROOT/.agents/plugins/marketplace.json 或 ~/.agents/plugins/marketplace.json	仓库/个人市场；从应用或 CLI 安装
Zed 技能	.agents/skills/ 或 ~/.agents/skills/	仅技能；Zed 没有远程技能注册表或自定义搜索路径
npm 私有技能包	Claude 市场 source.type: npm	适用于托管在 npm 上的插件包；纯 SKILL.md 目录较少采用

Skill Steward 默认设置： 用公开的 arenukvern/skill_steward 提供元技能；钩子单独说明（npx skills 不会安装 Cursor 钩子）。

跨 Agent 安装矩阵（技能）

使用 vercel-labs/skills 作为通用安装工具：

npx skills add owner/repo                    # all skills, project scope
npx skills add owner/repo --skill my-skill   # one skill
npx skills add owner/repo -a cursor -a claude-code -a codex -a zed -y
npx skills add owner/repo -g                 # global (~/.agents/skills/)
npx skills add owner/repo --copy             # copy instead of symlink

发现功能还会读取 .claude-plugin/plugin.json 和 .claude-plugin/marketplace.json 中的技能路径（兼容 Claude 市场）。

Agent	--agent 标志	项目技能路径	全局技能路径
Cursor	cursor	.agents/skills/（Cursor 也会读取 .cursor/skills/）	~/.cursor/skills/
Claude Code	claude-code	.claude/skills/	~/.claude/skills/
Codex	codex	.agents/skills/	~/.codex/skills/
Zed	zed	.agents/skills/	~/.agents/skills/
Copilot、Windsurf、Cline 等	见 npx skills --help	见 CLI 表格	见 CLI 表格

钩子： 支持 Claude Code、Cline、Kiro；npx skills 不支持 Cursor。Cursor 钩子需要 .cursor/hooks.json（Skill Steward 示例）。

跨 Agent 安装矩阵（插件）

Agent	清单目录	市场文件	安装（通常方式）
Cursor	.cursor-plugin/plugin.json	.cursor-plugin/marketplace.json（多插件仓库）	市场界面、团队导入，或 init 脚本 → .cursor/plugins/local/
Claude Code	.claude-plugin/plugin.json	.claude-plugin/marketplace.json	先运行 /plugin marketplace add owner/repo，再运行 /plugin install name@marketplace
Codex	.codex-plugin/plugin.json	$REPO_ROOT/.agents/plugins/marketplace.json 或 ~/.agents/plugins/marketplace.json	应用插件目录或 codex plugin add name@marketplace
Open Plugin v1	.plugin/plugin.json	取决于宿主	可移植的基准配置；仅在需要针对特定宿主进行覆盖时添加厂商清单
仅 Open skills	不适用	不适用	npx skills add — 不含 MCP/钩子

参考产品布局：产品仓库市场分发配置。

Codex 插件说明

• .codex-plugin/ 中仅保留 plugin.json；将 skills/、.mcp.json、.app.json、hooks/ 和 assets/ 放在插件根目录。
• 仅当配套文件/目录存在时，才在 .codex-plugin/plugin.json 中包含 skills、mcpServers、apps 或 hooks。Codex 也会检查默认的 hooks/hooks.json。
• 仓库/团队目录的市场文件位于 $REPO_ROOT/.agents/plugins/marketplace.json，个人目录的市场文件位于 ~/.agents/plugins/marketplace.json。
• 每个市场条目都必须包含 policy.installation、policy.authentication 和 category；source.path 必须相对于市场根目录，且位于该根目录内。
• Codex 会将市场插件安装到 ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/；本地源文件有更改时，必须重新安装/刷新缓存，新线程才能看到这些更改。

Open Plugin 可移植性

• 如果插件需要在不同 Open Plugin 宿主间保持厂商中立，请使用 .plugin/plugin.json。
• 仅当宿主需要厂商专属清单时，才添加 .codex-plugin/plugin.json、.cursor-plugin/plugin.json 或 .claude-plugin/plugin.json。
• 不要将 Skill Steward 的 plugin.yaml 与宿主市场清单混淆。它是用于记录 Skill Steward 配置的本地元插件清单。

搭建新的市场仓库

A. 仅含技能的市场（最简单 — Skill Steward 风格）

my-skills/
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── skills.sh.json          # optional: skills.sh categories
├── README.md               # install commands
└── package.json            # optional: pnpm run validate

发布：推送到公开仓库 → npx skills add org/my-skills。无需插件清单。有关通过在 skills.sh.json 中定义分组和类别来自定义仓库页面的信息，请参阅 skills.sh 自定义文档。

B. Codex / Claude / Cursor 市场（多插件）

my-marketplace/
├── .agents/plugins/
│   └── marketplace.json    # Codex catalog
├── .claude-plugin/
│   └── marketplace.json    # Claude catalog, when needed
├── .cursor-plugin/
│   └── marketplace.json    # Cursor catalog, when needed
└── plugins/
    └── my-plugin/
        ├── .plugin/plugin.json
        ├── .codex-plugin/plugin.json
        ├── .claude-plugin/plugin.json
        ├── .cursor-plugin/plugin.json
        ├── skills/
        ├── hooks/
        └── .mcp.json

Codex 条目："source": {"source": "local", "path": "./plugins/my-plugin"}，并附上策略/类别。Claude 和 Cursor 使用各自的市场格式。仅使用目标 Agent 所需的厂商目录树。

C. Skill Steward 元插件（钩子 + 技能引用）

plugins/my-hook-pack/
├── plugin.yaml
├── README.md               # manual .cursor/hooks.json steps
├── hooks.json.snippet
└── hooks/

规范技能保留在 skills/ 中。请参阅 templates/plugin/。

私有市场检查清单

1. 仓库访问权限 — 团队能够执行 git clone（HTTPS 令牌、SSH，或用于 Cursor 团队市场的 GHE 应用）。
2. 密钥 — 切勿提交令牌；记录 Claude 在私有市场中自动更新所需的 GITHUB_TOKEN / GITLAB_TOKEN。
3. 安装文档 — 每个渠道提供一个 README 说明块（skills CLI、Claude /plugin 或 Cursor 控制面板）。
4. 版本管理 — 每次发布时递增插件清单中的 version；技能通过 npx skills update 使用 git SHA。
5. CI — 验证技能（在 Skill Steward 中运行 pnpm run validate / dart run :steward validate）；产品仓库需添加契约测试。
6. 作用范围 — 项目级安装（已提交的 .agents/skills/）与 -g 全局安装；记录团队规范。

Skill Steward 与产品仓库的区别

关注点	Skill Steward	产品（例如 product MCP）
Skills	仅元数据（skill-authoring-lifecycle、repository-governance-lifecycle、…）	领域 + MCP skills
Plugins	元数据钩子（steward-validate-on-save）	完整套件：MCP + skills + init
CLI	steward validate	[toolkit-cli] init <agent>
Marketplace	公共 Git + skills.sh	Claude/Codex git + Cursor submit + Smithery

不要将产品 MCP 服务放入 Skill Steward。交叉推广：npx skills add arenukvern/skill_steward --skill mcp-harness-repo-maintainer。

工作流：向 Skill Steward 添加可分发的 skill

1. 按照 skill-authoring-lifecycle 执行——skills/{name}/SKILL.md。
2. 在 skills.sh.json 和根目录 README.md 中注册。
3. 在 skill_steward 中运行 pnpm run validate。
4. 合并到 main 后，即可通过 npx skills add arenukvern/skill_steward --skill {name} 安装公共仓库。
5. 可选：提交至 skills.sh 排行榜（包含有效 skills 的公共仓库会自动收录）。

工作流：添加 Skill Steward 插件

1. 将 templates/plugin/ 复制到 plugins/{id}/。
2. 在 plugin.yaml 中列出引用的 skills（仅填写 id）。
3. 编写安装说明（Cursor 钩子合并等）。
4. 更新 plugins/README.md。

反面模式

• 只将钩子放在 skills/ 中，却期望 npx skills 能为 Cursor 配置钩子
• 在每个插件目录中重复存放 SKILL.md
• 仅提及一种 Agent 的私有 Marketplace 文档
• Marketplace 仓库中长期保留计划文件（参见计划文件规范）

更多资源

• distribution-matrix.md — 完整的渠道表
• manifest-snippets.md — 精简的 JSON/YAML 示例
• ADR 0004
• ADR 0006
• skills.sh 自定义文档

安装此 skill

npx skills add arenukvern/skill_steward --skill plugin-marketplace-setup

来源

参见 references/sources.md。调研时，请遵循 skill-source-citations。