skill-publish

技能发布

发布 Claude Code 插件和独立 Agent 技能，并妥善管理版本、变更日志和 Git 工作流。

确定发布类型

开始前，根据项目结构确定发布类型：

指标	类型
存在 .claude-plugin/plugin.json 和／或 .codex-plugin/plugin.json	托管插件
存在独立的 SKILL.md，且没有插件清单	独立 Agent 技能

托管插件通过推送到 GitHub 来发布。支持多个宿主的仓库必须确保所有实际清单及其共享的市场元数据保持同步。Codex 会按版本缓存插件内容，因此即使源提交已更新，过时的版本也可能导致技能内容仍然过时。

独立 Agent 技能遵循 agentskills.io 规范，并以包含 SKILL.md 的目录形式分发。

托管插件工作流

1. 检查当前状态

# Read and validate every host manifest
python3 scripts/check-plugin-manifests.py

# Check git is clean and up to date
git fetch origin && git status

# Review commits since last version bump
git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo HEAD~10)..HEAD

2. 整理文档

必须包含 CHANGELOG.md。在 Unreleased 下概述自上次发布以来所有用户可见或与运行相关的变更。每当公开内容清单、安装流程、运行时行为或宣传的功能集发生变化时，都要更新 README.md。如果有文档检查命令，请运行：

python3 scripts/check-docs.py

对比上次清单版本更新提交与当前 HEAD，确保没有遗漏在版本号过时期间提交的变更。

3. 更新所有实际清单的版本号

如果仓库提供同步更新命令，请使用该命令。对于 bopen-tools：

python3 scripts/check-plugin-manifests.py --bump-patch

否则，请同时编辑所有宿主清单。除非用户明确要求并说明理由，否则仅递增补丁版本：

0.1.6 → 0.1.7
1.0.23 → 1.0.24

4. 完成 CHANGELOG.md

将审核后的 Unreleased 条目移至带日期的发布条目下：

## [X.X.X] - YYYY-MM-DD

### Added
- New features

### Changed
- Changes to existing functionality

### Fixed
- Bug fixes

保留空的 Unreleased 标题，以便记录下一次变更。确认发布标题与所有清单完全一致。

5. 验证插件结构

发布前，确认插件结构有效：

• .claude-plugin/plugin.json 包含必需的 name 字段
• 组件目录（commands/、agents/、skills/、hooks/）中包含有效文件
• 技能包含带有效 YAML frontmatter（name + description）的 SKILL.md
• Agent 和命令包含带 YAML frontmatter 的 .md 文件
• 所有引用的文件和脚本均存在
• 所有宿主清单及市场版本均已同步
• CHANGELOG.md 包含发布版本号
• README 中的清单与已编写的技能、Agent、命令和钩子一致
• 生成的宿主适配器均为最新版本

对于 bopen-tools，请运行：

python3 scripts/check-plugin-manifests.py
python3 scripts/check-docs.py
python3 scripts/codex-agents/generate.py --check
bash hooks/tests/run-tests.sh
git diff --check

6. 提交并推送

重要：推送到默认分支即代表发布。 Claude Code 插件市场会自动获取最新提交。

# Stage only reviewed, owned paths; never sweep unrelated worktree changes.
git add .claude-plugin/plugin.json .codex-plugin/plugin.json CHANGELOG.md README.md
git add path/to/each/reviewed/component
git commit -m "Release vX.X.X"
git push origin <default-branch>
git log origin/<default-branch>..<default-branch>

如果任一实际清单的版本号已更新，请在同一会话中推送。已提交但未推送的版本更新会导致发布搁置。

7. 在每个宿主上验证发布

推送后，确认插件更新已可用：

CLAUDECODE= claude plugin update <plugin-name>@<publisher>
codex plugin marketplace upgrade
codex plugin add <plugin-name>@<publisher>

CLAUDECODE= 前缀可避免嵌套 Claude 会话错误。对于 Codex，marketplace add 不会刷新现有快照；请在重新安装前使用 marketplace upgrade。确认安装目录包含新版本，然后在两个宿主的全新会话中进行冒烟测试。

注意： 市场可能需要几分钟才会显示新版本。

8. 更新下游引用

如果其他位置（例如市场页面、文档或 lib/plugins.ts）跟踪了插件版本，请更新这些引用，使其与新版本一致。

独立 Agent 技能工作流

对于未打包在 Claude Code 插件中的技能，请遵循 agentskills.io 规范。

1. 验证 SKILL.md

确认 frontmatter 符合规范。详情请参阅 references/agentskills-spec.md。

必需字段：

• name：1-64 个字符，由小写字母、数字和连字符组成，且必须与目录名一致
• description：1-1024 个字符，说明用途及使用时机

可选字段：

• license、compatibility、metadata、allowed-tools

2. 验证结构

skill-name/
├── SKILL.md          # Required
├── scripts/          # Optional executables
├── references/       # Optional docs loaded on demand
└── assets/           # Optional static resources

3. 通过元数据设置版本

在 frontmatter 的 metadata 字段中跟踪版本：

metadata:
  author: org-name
  version: "1.1.0"

4. 分发

独立技能以目录形式分发。常见方式：

• Git 仓库（推送到 GitHub）
• 压缩包（将技能目录打包为 zip）
• 软件包注册表（如适用）

常见问题

插件未更新

如果 claude plugin update 未能获取更改：

• 确认推送已提交到默认分支（通常为 main 或 master）
• 检查 .claude-plugin/plugin.json 是否为有效的 JSON
• 等待几分钟，让市场完成同步

版本已存在

如果之前的提交已使用该版本字符串，请在推送前将版本号再次递增到下一个修订版本。

嵌套会话错误

在活动的 Claude Code 会话中运行 CLI 命令时，始终在命令前加上 CLAUDECODE=，以避免“嵌套会话”错误。

其他资源

参考文件

• references/agentskills-spec.md — 独立技能的 agentskills.io 规范完整摘要