feat(plugins): add registry publishing strategies and documentation

- Introduced `PUBLISHING-REGISTRIES.md` and its Chinese counterpart, detailing strategies for publishing plugins to skills.sh, ClawHub, and GitHub.
- Updated existing documentation to reference the new publishing guidelines, ensuring clarity on the process for external registry distribution.
- Enhanced `AGENT-DEVELOPMENT.md` and `CONTRIBUTING.md` to include notes on registry publishing, improving the overall authoring experience for plugin developers.

This update provides comprehensive guidance for plugin authors on how to effectively publish their work across various registries, enhancing the accessibility and usability of the plugin ecosystem.

plugins/README.md

@@ -14,5 +14,6 @@ Start here:
 - Plugin spec kit: [`spec/README.md`](spec/README.md)
 - Plugin authoring spec: [`spec/SPEC.md`](spec/SPEC.md)
 - Agent handoff guide: [`spec/AGENT-DEVELOPMENT.md`](spec/AGENT-DEVELOPMENT.md)
+- Registry publishing strategy: [`spec/PUBLISHING-REGISTRIES.md`](spec/PUBLISHING-REGISTRIES.md)
 - Full product spec: [`../docs/plugins-spec.md`](../docs/plugins-spec.md)
 - Manifest schema: [`../docs/schemas/open-design.plugin.v1.json`](../docs/schemas/open-design.plugin.v1.json)

plugins/README.zh-CN.md

@@ -14,6 +14,6 @@
 - 插件规范包：[`spec/README.zh-CN.md`](spec/README.zh-CN.md)
 - 插件作者规范：[`spec/SPEC.zh-CN.md`](spec/SPEC.zh-CN.md)
 - Agent handoff 指南：[`spec/AGENT-DEVELOPMENT.zh-CN.md`](spec/AGENT-DEVELOPMENT.zh-CN.md)
+- Registry 发布策略：[`spec/PUBLISHING-REGISTRIES.zh-CN.md`](spec/PUBLISHING-REGISTRIES.zh-CN.md)
 - 完整产品 spec：[`../docs/plugins-spec.zh-CN.md`](../docs/plugins-spec.zh-CN.md)
 - Manifest schema：[`../docs/schemas/open-design.plugin.v1.json`](../docs/schemas/open-design.plugin.v1.json)
-

plugins/spec/AGENT-DEVELOPMENT.md

@@ -20,6 +20,7 @@ Read these files before editing:
 - `plugins/spec/SPEC.md`
 - `docs/schemas/open-design.plugin.v1.json`
 - `docs/plugins-spec.md` when you need deeper product semantics
+- `plugins/spec/PUBLISHING-REGISTRIES.md` when the user asks to publish outside Open Design
 - A nearby example under `plugins/spec/examples/`
 
 ## Build Procedure
@@ -38,6 +39,7 @@ Read these files before editing:
 4. Put OD-specific display, inputs, preview, pipeline, atoms, connectors, and capabilities in `open-design.json`.
 5. Add `examples/`, `preview/`, `assets/`, or `references/` only when they materially help the agent produce better results.
 6. Add `evals/evals.json` when the plugin has enough behavior to regress.
+7. If publishing externally, prepare registry-safe README sections for skills.sh, ClawHub, and canonical GitHub source.
 
 ## Quality Bar
 
@@ -78,3 +80,4 @@ When opening or preparing a PR, include:
 - Validation commands and results.
 - Capabilities requested.
 - Screenshots, preview URLs, or example artifacts for visual plugins.
+- Registry links and dry-run output when publishing to skills.sh, ClawHub, or another skill registry.

plugins/spec/AGENT-DEVELOPMENT.zh-CN.md

@@ -20,6 +20,7 @@
 - `plugins/spec/SPEC.zh-CN.md`
 - `docs/schemas/open-design.plugin.v1.json`
 - 需要更深入产品语义时阅读 `docs/plugins-spec.zh-CN.md`
+- 当用户要求发布到 Open Design 以外的 registry 时，阅读 `plugins/spec/PUBLISHING-REGISTRIES.zh-CN.md`
 - `plugins/spec/examples/` 下最接近的示例
 
 ## 构建流程
@@ -38,6 +39,7 @@
 4. 把 OD 专属 display、inputs、preview、pipeline、atoms、connectors 和 capabilities 放进 `open-design.json`。
 5. 只有在能明显提升 agent 输出质量时，才添加 `examples/`、`preview/`、`assets/` 或 `references/`。
 6. 当插件行为足够复杂、容易回归时，添加 `evals/evals.json`。
+7. 如果要对外发布，准备适配 skills.sh、ClawHub 和 canonical GitHub source 的 registry-safe README 段落。
 
 ## 完成标准
 
@@ -78,4 +80,4 @@ od plugin apply <plugin-id> --input key=value
 - 验证命令与结果。
 - 请求的 capabilities。
 - 视觉类插件的截图、preview URL 或示例 artifact。
-
+- 发布到 skills.sh、ClawHub 或其他 skill registry 时，附上 registry 链接和 dry-run 输出。

plugins/spec/CONTRIBUTING.md

@@ -10,6 +10,7 @@ Plugins that follow this spec can live in this repo as examples, or in their own
 - Improvements to templates, authoring docs, evals, or PR checklists.
 - Fixes that make plugin folders more portable across Agent Skills compatible clients.
 - Marketplace index updates that point to public plugin repos.
+- Registry publishing notes for skills.sh, ClawHub, or another dedicated skill registry.
 
 ## Review Checklist
 
@@ -22,6 +23,7 @@ Reviewers should check:
 - Capabilities are minimal.
 - Externally visible actions are guarded by user confirmation.
 - Visual examples include a preview or concrete output.
+- Registry publishing claims link to canonical source and do not imply registry endorsement.
 - JSON is valid and validation commands are listed in the PR.
 
 ## PR Template
@@ -43,4 +45,11 @@ Reviewers should check:
 ## Validation
 
 ## Screenshots or example outputs
+
+## Registry publishing
+
+- Canonical source:
+- skills.sh:
+- ClawHub:
+- Other registries:
 ```

plugins/spec/CONTRIBUTING.zh-CN.md

@@ -10,6 +10,7 @@
 - 模板、作者文档、evals 或 PR checklist 的改进。
 - 提升插件在 Agent Skills 兼容客户端之间可移植性的修复。
 - 指向公开插件仓库的 marketplace index 更新。
+- skills.sh、ClawHub 或其他专用 skill registry 的发布说明。
 
 ## Review Checklist
 
@@ -22,6 +23,7 @@ Reviewer 应检查：
 - capabilities 是最小必要集合。
 - 对外可见的操作有用户确认。
 - 视觉类示例包含 preview 或具体输出。
+- registry 发布声明链接到 canonical source，且不暗示 registry 背书。
 - JSON 合法，PR 中列出了验证命令。
 
 ## PR 模板
@@ -43,5 +45,11 @@ Reviewer 应检查：
 ## Validation
 
 ## Screenshots or example outputs
-```
 
+## Registry publishing
+
+- Canonical source:
+- skills.sh:
+- ClawHub:
+- Other registries:
+```

plugins/spec/PUBLISHING-REGISTRIES.md

@@ -0,0 +1,135 @@
+# Publishing To Skill Registries
+
+Language: English | [简体中文](PUBLISHING-REGISTRIES.zh-CN.md)
+
+Open Design plugins are intentionally shaped so one folder can travel across multiple agent ecosystems. The safest publishing model is:
+
+1. Keep the source of truth in a public GitHub repository or in an Open Design PR.
+2. Keep `SKILL.md` portable and registry-friendly.
+3. Add `open-design.json` as the Open Design sidecar.
+4. Publish or list the same source in external registries only after local validation passes.
+
+Registry rules can change, so always check the target registry docs before running a publish command.
+
+## Recommended Release Order
+
+1. Validate the plugin folder locally.
+2. Push a public GitHub repository or open an Open Design PR.
+3. Add README install instructions for Open Design and generic Agent Skills clients.
+4. Add registry-specific badges or links.
+5. Publish to registries that match the plugin's audience.
+6. Record every published URL in the README and PR body.
+
+## Registry Matrix
+
+| Target | Best for | Source shape | Publish strategy |
+| --- | --- | --- | --- |
+| Open Design | OD marketplace, composer chips, pipelines, GenUI, artifact provenance | `SKILL.md` + `open-design.json` | Open a PR to Open Design or publish a marketplace index entry pointing to the plugin repo. |
+| skills.sh | Agent Skills discovery across many coding agents | Public Git repo or subpath containing `SKILL.md` | Make `npx skills add owner/repo` work, add the skills.sh badge, and keep the README clear. |
+| ClawHub | OpenClaw users who install skills or OpenClaw plugins from a registry | `SKILL.md` folder for skills; OpenClaw package metadata for plugins | Use `clawhub skill publish ./my-skill` for skill folders. Use `clawhub package publish ... --family code-plugin` only when you also ship OpenClaw plugin metadata. |
+| Standalone GitHub | Source of truth and broad agent compatibility | Portable folder or mono-repo subpath | Tag releases, document install commands, and keep changelogs. |
+
+## skills.sh Strategy
+
+The skills.sh ecosystem indexes installable Agent Skills and documents the `skills` CLI as the main install path. The public docs show installation through GitHub-style sources:
+
+```bash
+npx skills add owner/repo
+npx skills add https://github.com/owner/repo/tree/main/path/to/skill
+npx skills add ./my-local-skills
+```
+
+For Open Design plugin authors:
+
+- Ensure the repo or subpath contains a valid `SKILL.md`.
+- Keep `open-design.json` additive; generic skill clients should be able to ignore it.
+- Put a short install block in your README:
+
+```bash
+npx skills add owner/repo --skill my-plugin
+od plugin install https://github.com/owner/repo
+```
+
+- Add a badge once the public source is stable:
+
+```markdown
+[![skills.sh](https://skills.sh/b/owner/repo)](https://skills.sh/owner/repo)
+```
+
+- Use a GitHub topic and README keywords that match the plugin's lane, such as `open-design-plugin`, `agent-skill`, `prototype`, `deck`, `hyperframes`, or `design-system`.
+
+Do not assume skills.sh is the canonical storage location. Treat GitHub as source of truth and skills.sh as a discovery and install surface.
+
+## ClawHub Strategy
+
+ClawHub is the OpenClaw registry layer for skills and plugins. Its docs distinguish skill publishing from package publishing:
+
+```bash
+npm i -g clawhub
+clawhub login
+
+clawhub skill publish ./my-skill \
+  --slug my-skill \
+  --name "My Skill" \
+  --version 1.0.0 \
+  --changelog "Initial release"
+```
+
+Use this path for normal Open Design plugins because they are centered on `SKILL.md`.
+
+Only use the OpenClaw package path when you intentionally ship an OpenClaw code plugin with OpenClaw compatibility metadata:
+
+```bash
+clawhub package publish <source> --family code-plugin --dry-run
+clawhub package publish <source> --family code-plugin
+```
+
+For ClawHub-ready skills:
+
+- Keep `SKILL.md` metadata accurate.
+- Declare required environment variables, tools, permissions, connectors, or network access in the README and skill body.
+- Run the dry run or inspect command before making a listing public.
+- Link back to the canonical GitHub repo and Open Design PR.
+- Keep changelog text honest and versioned.
+
+## Safety Checklist
+
+Public skill registries are supply-chain surfaces. Before publishing:
+
+- No hidden install scripts.
+- No automatic credential collection.
+- No network calls unless the plugin clearly declares why they are needed.
+- No destructive shell commands without explicit user confirmation.
+- Include `license`, `author`, source URL, version, and changelog.
+- Include validation output from `pnpm guard`, plugin manifest validation, and any registry dry run.
+- Prefer small example assets over large opaque archives.
+
+## PR Body Snippet
+
+```markdown
+## Registry publishing
+
+- Canonical source:
+- Open Design PR:
+- skills.sh install:
+- ClawHub listing:
+- Other registries:
+
+## Registry validation
+
+- `pnpm guard`:
+- `pnpm --filter @open-design/plugin-runtime typecheck`:
+- `od plugin validate ./path/to/plugin`:
+- `npx skills add ... --list`:
+- `clawhub skill publish ./path --dry-run` or equivalent:
+```
+
+## References
+
+- [skills.sh](https://skills.sh/)
+- [skills.sh docs](https://www.skills.sh/docs)
+- [skills CLI](https://github.com/vercel-labs/skills)
+- [ClawHub](https://clawhub.ai/)
+- [ClawHub quickstart](https://github.com/openclaw/clawhub/blob/main/docs/quickstart.md)
+- [How ClawHub works](https://documentation.openclaw.ai/clawhub/how-it-works)
+

plugins/spec/PUBLISHING-REGISTRIES.zh-CN.md

@@ -0,0 +1,135 @@
+# 发布到 Skill Registries
+
+语言：[English](PUBLISHING-REGISTRIES.md) | 简体中文
+
+Open Design 插件刻意设计成一个文件夹可以跨多个 agent 生态流转。最稳妥的发布模型是：
+
+1. 把公开 GitHub 仓库或 Open Design PR 作为 source of truth。
+2. 保持 `SKILL.md` 可移植、适合 registry 读取。
+3. 添加 `open-design.json` 作为 Open Design sidecar。
+4. 本地验证通过后，再发布或登记到外部 registry。
+
+各 registry 的规则可能变化，运行 publish 命令前一定要查看目标 registry 的当前文档。
+
+## 推荐发布顺序
+
+1. 本地验证插件文件夹。
+2. 推送公开 GitHub 仓库，或向 Open Design 打开 PR。
+3. 在 README 中添加 Open Design 和通用 Agent Skills 客户端的安装说明。
+4. 添加 registry 专属 badge 或链接。
+5. 发布到符合目标用户的 registry。
+6. 在 README 和 PR body 中记录所有已发布 URL。
+
+## Registry 矩阵
+
+| 目标 | 适合场景 | 源形态 | 发布策略 |
+| --- | --- | --- | --- |
+| Open Design | OD marketplace、composer chips、pipelines、GenUI、artifact provenance | `SKILL.md` + `open-design.json` | 向 Open Design 提 PR，或发布指向插件仓库的 marketplace index entry。 |
+| skills.sh | 面向多种编码 agent 的 Agent Skills 发现 | 包含 `SKILL.md` 的公开 Git repo 或 subpath | 确保 `npx skills add owner/repo` 可用，添加 skills.sh badge，并写清 README。 |
+| ClawHub | 让 OpenClaw 用户从 registry 安装 skills 或 OpenClaw plugins | skill 使用 `SKILL.md` 文件夹；plugin 使用 OpenClaw package metadata | `SKILL.md` 文件夹使用 `clawhub skill publish ./my-skill`。只有同时提供 OpenClaw plugin metadata 时，才使用 `clawhub package publish ... --family code-plugin`。 |
+| 独立 GitHub | source of truth 和广泛 agent 兼容 | 可移植文件夹或 mono-repo subpath | 打 tag、写安装命令、维护 changelog。 |
+
+## skills.sh 策略
+
+skills.sh 生态索引可安装 Agent Skills，并把 `skills` CLI 作为主要安装路径。公开文档展示了通过 GitHub 风格来源安装：
+
+```bash
+npx skills add owner/repo
+npx skills add https://github.com/owner/repo/tree/main/path/to/skill
+npx skills add ./my-local-skills
+```
+
+对 Open Design 插件作者：
+
+- 确保 repo 或 subpath 包含合法 `SKILL.md`。
+- 保持 `open-design.json` 为纯增量；通用 skill 客户端应能忽略它。
+- 在 README 中放一个短安装块：
+
+```bash
+npx skills add owner/repo --skill my-plugin
+od plugin install https://github.com/owner/repo
+```
+
+- 公共来源稳定后添加 badge：
+
+```markdown
+[![skills.sh](https://skills.sh/b/owner/repo)](https://skills.sh/owner/repo)
+```
+
+- 使用与插件主类匹配的 GitHub topic 和 README 关键词，例如 `open-design-plugin`、`agent-skill`、`prototype`、`deck`、`hyperframes`、`design-system`。
+
+不要把 skills.sh 视为 canonical 存储位置。GitHub 是 source of truth，skills.sh 是发现和安装表面。
+
+## ClawHub 策略
+
+ClawHub 是 OpenClaw 的 skills 和 plugins registry layer。它的文档区分 skill publishing 与 package publishing：
+
+```bash
+npm i -g clawhub
+clawhub login
+
+clawhub skill publish ./my-skill \
+  --slug my-skill \
+  --name "My Skill" \
+  --version 1.0.0 \
+  --changelog "Initial release"
+```
+
+普通 Open Design 插件应优先走这个路径，因为它们以 `SKILL.md` 为核心。
+
+只有当你明确发布 OpenClaw code plugin，并提供 OpenClaw compatibility metadata 时，才使用 OpenClaw package 路径：
+
+```bash
+clawhub package publish <source> --family code-plugin --dry-run
+clawhub package publish <source> --family code-plugin
+```
+
+为了适配 ClawHub：
+
+- 保持 `SKILL.md` metadata 准确。
+- 在 README 和 skill 正文中声明所需环境变量、工具、权限、connectors 或 network access。
+- 公开 listing 前先跑 dry run 或 inspect。
+- 链回 canonical GitHub repo 和 Open Design PR。
+- changelog 诚实且版本化。
+
+## 安全 Checklist
+
+公共 skill registry 是供应链表面。发布前检查：
+
+- 没有隐藏安装脚本。
+- 不自动收集凭据。
+- 没有未声明原因的网络请求。
+- 没有未经过用户明确确认的破坏性 shell 命令。
+- 包含 `license`、`author`、source URL、version 和 changelog。
+- 包含 `pnpm guard`、plugin manifest validation 和 registry dry run 的验证输出。
+- 优先使用小型示例资产，避免大型不透明 archives。
+
+## PR Body 片段
+
+```markdown
+## Registry publishing
+
+- Canonical source:
+- Open Design PR:
+- skills.sh install:
+- ClawHub listing:
+- Other registries:
+
+## Registry validation
+
+- `pnpm guard`:
+- `pnpm --filter @open-design/plugin-runtime typecheck`:
+- `od plugin validate ./path/to/plugin`:
+- `npx skills add ... --list`:
+- `clawhub skill publish ./path --dry-run` or equivalent:
+```
+
+## 参考
+
+- [skills.sh](https://skills.sh/)
+- [skills.sh docs](https://www.skills.sh/docs)
+- [skills CLI](https://github.com/vercel-labs/skills)
+- [ClawHub](https://clawhub.ai/)
+- [ClawHub quickstart](https://github.com/openclaw/clawhub/blob/main/docs/quickstart.md)
+- [How ClawHub works](https://documentation.openclaw.ai/clawhub/how-it-works)
+

plugins/spec/README.md

@@ -11,6 +11,7 @@ Open Design plugins follow the same portable shape as Agent Skills: a folder wit
 - [`SPEC.md`](SPEC.md) - the portable plugin spec and taxonomy.
 - [`AGENT-DEVELOPMENT.md`](AGENT-DEVELOPMENT.md) - copy this into an external agent session to build and validate a plugin.
 - [`CONTRIBUTING.md`](CONTRIBUTING.md) - PR standards for plugins that follow this spec.
+- [`PUBLISHING-REGISTRIES.md`](PUBLISHING-REGISTRIES.md) - strategies for skills.sh, ClawHub, GitHub, and Open Design publishing.
 - [`templates/`](templates/) - blank starter files.
 - [`examples/`](examples/) - complete example plugin folders and a sample marketplace index.
 
@@ -19,6 +20,7 @@ Chinese mirrors:
 - [`SPEC.zh-CN.md`](SPEC.zh-CN.md)
 - [`AGENT-DEVELOPMENT.zh-CN.md`](AGENT-DEVELOPMENT.zh-CN.md)
 - [`CONTRIBUTING.zh-CN.md`](CONTRIBUTING.zh-CN.md)
+- [`PUBLISHING-REGISTRIES.zh-CN.md`](PUBLISHING-REGISTRIES.zh-CN.md)
 - [`examples/README.zh-CN.md`](examples/README.zh-CN.md)
 
 ## What To Build

plugins/spec/README.zh-CN.md

@@ -11,6 +11,7 @@ Open Design 插件遵循和 Agent Skills 兼容的可移植形态：一个包含
 - [`SPEC.zh-CN.md`](SPEC.zh-CN.md) - 可移植插件规范与分类。
 - [`AGENT-DEVELOPMENT.zh-CN.md`](AGENT-DEVELOPMENT.zh-CN.md) - 可以直接复制给外部 agent 的开发说明。
 - [`CONTRIBUTING.zh-CN.md`](CONTRIBUTING.zh-CN.md) - 遵循此规范的插件 PR 标准。
+- [`PUBLISHING-REGISTRIES.zh-CN.md`](PUBLISHING-REGISTRIES.zh-CN.md) - 发布到 skills.sh、ClawHub、GitHub 和 Open Design 的策略。
 - [`templates/`](templates/) - 空白 starter 文件。
 - [`examples/`](examples/) - 完整示例插件文件夹和示例 marketplace index。
 
@@ -19,6 +20,7 @@ Open Design 插件遵循和 Agent Skills 兼容的可移植形态：一个包含
 - [`SPEC.md`](SPEC.md)
 - [`AGENT-DEVELOPMENT.md`](AGENT-DEVELOPMENT.md)
 - [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- [`PUBLISHING-REGISTRIES.md`](PUBLISHING-REGISTRIES.md)
 - [`examples/README.md`](examples/README.md)
 
 ## 可以构建什么
@@ -64,4 +66,3 @@ od plugin apply <plugin-id> --input key=value
 - Agent Skills overview: https://agentskills.io/home
 - Agent Skills specification: https://agentskills.io/specification
 - Open Design 插件完整 spec: ../../docs/plugins-spec.zh-CN.md
-

plugins/spec/SPEC.md

@@ -210,3 +210,5 @@ Before opening a PR:
 4. If available, run `od plugin validate ./path/to/plugin`.
 5. Include one screenshot, rendered preview, or example output when the plugin is visual.
 6. Explain trust and capabilities in the PR body.
+
+For external registry distribution, follow [`PUBLISHING-REGISTRIES.md`](PUBLISHING-REGISTRIES.md). In short: keep GitHub or the Open Design PR as source of truth, make the folder installable as a generic `SKILL.md` skill, then publish or list it on skills.sh, ClawHub, or other registries only after local validation passes.

plugins/spec/SPEC.zh-CN.md

@@ -211,3 +211,4 @@ preview 应展示真实输出形态，而不是装饰性的 splash screen。
 5. 视觉类插件包含一张截图、渲染 preview 或示例输出。
 6. 在 PR body 里说明 trust 和 capabilities。
 
+外部 registry 分发策略见 [`PUBLISHING-REGISTRIES.zh-CN.md`](PUBLISHING-REGISTRIES.zh-CN.md)。简言之：把 GitHub 或 Open Design PR 作为 source of truth，让文件夹能作为通用 `SKILL.md` skill 安装；本地验证通过后，再发布或登记到 skills.sh、ClawHub 或其他 registry。