skills-release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skills Release

Skills版本发布

Overview

概述

main

is the distribution branch:

/plugin marketplace add zenml-io/kitaru-skills

installs whatever

main

holds, immediately.

develop

is the working base. A release moves

main

forward to

develop

's current commit as a fast-forward and stamps a plugin version, so

main

is always an exact snapshot of

develop

at release time.

The

main-release-only

ruleset blocks all pushes and PR merges to

main

except by repository admins. A release is therefore an admin running this checklist — never a PR into

main

, never a force push.

Versions are this repository's own plugin versions. Do not reuse Kitaru product version numbers; state tested Kitaru compatibility in the release notes instead.

main

是分发分支：执行

/plugin marketplace add zenml-io/kitaru-skills

会立即安装

main

分支当前的内容。

develop

是开发基准分支。版本发布操作会将

main

分支快速前向更新至

develop

分支的当前提交，并标记插件版本，因此

main

分支始终是发布时

develop

分支的精确快照。

main-release-only

规则集禁止所有对

main

分支的推送和PR合并操作，仅仓库管理员可执行。因此版本发布必须由管理员按照本清单执行——绝不允许通过PR合并到

main

分支，也不允许强制推送。

版本号为本仓库自身的插件版本号。请勿复用Kitaru产品的版本号；相反，应在发布说明中注明已测试的Kitaru兼容版本。

Preconditions

前置条件

Stop and resolve before releasing if any of these fail:

On
```
develop
```
with a clean working tree.
```
git fetch origin
```
done; local
```
develop
```
in sync with
```
origin/develop
```
.
Fast-forward is possible:
```
git merge-base --is-ancestor origin/main origin/develop
```
exits 0. A non-zero exit means
```
main
```
has commits
```
develop
```
lacks — investigate how they got there; never force-push over them.

如果以下任意条件不满足，请停止并解决后再执行发布：

当前处于
```
develop
```
分支，且工作树干净。
已执行
```
git fetch origin
```
；本地
```
develop
```
分支与
```
origin/develop
```
保持同步。
可以执行快速前向合并：
```
git merge-base --is-ancestor origin/main origin/develop
```
命令执行后返回值为0。若返回非零值，说明
```
main
```
分支包含
```
develop
```
分支没有的提交——请调查这些提交的来源；绝不要强制推送覆盖它们。

Steps

步骤

Review what ships:
```
git log --oneline origin/main..origin/develop
```
. Draft release notes from these commits (what changed, why it matters to installers), plus a "Tested against Kitaru X.Y" line when known.
Agree the next version with the user: minor for new or changed skills, patch for fixes and docs-only changes.

Bump all three version fields to the same value:

```
.claude-plugin/plugin.json
```
→
```
.version
```

.claude-plugin/marketplace.json

→

.metadata.version

.claude-plugin/marketplace.json

→

.plugins[0].version

Validate:

jq . .claude-plugin/plugin.json

and

jq . .claude-plugin/marketplace.json

parse, and all three fields match:

bash

jq -r .version .claude-plugin/plugin.json
jq -r '.metadata.version, .plugins[0].version' .claude-plugin/marketplace.json

Commit only the two JSON files on
```
develop
```
with subject
```
Release vX.Y.Z
```
, then push
```
develop
```
.

Tag the release commit:

git tag vX.Y.Z && git push origin vX.Y.Z

Fast-forward
```
main
```
:
```
git push origin develop:main
```
. No
```
--force
```
ever — a rejection means the push is not a fast-forward; go back to Preconditions.
Publish the drafted notes via a file, never inline in the command — commit subjects routinely contain backticks, which the shell would execute as command substitution inside a
```
--notes "..."
```
argument. Write the notes to a scratch file with a file-writing tool (or a quoted heredoc,
```
cat > notes.md <<'EOF'
```
), then:
bash
```
gh release create vX.Y.Z --title "vX.Y.Z" --notes-file notes.md
```
Verify:
```
git ls-remote origin refs/heads/main refs/heads/develop
```
shows identical SHAs, and the GitHub Release page exists.

查看待发布内容：执行
```
git log --oneline origin/main..origin/develop
```
。根据这些提交编写发布说明草稿（包括变更内容、对安装者的重要性），若已知兼容版本，需添加“已针对Kitaru X.Y版本测试”的说明。
与用户商定下一个版本号：新增或修改技能时使用小版本号（minor），仅修复问题或更新文档时使用补丁版本号（patch）。

将三处版本字段更新为同一值：

```
.claude-plugin/plugin.json
```
→
```
.version
```

.claude-plugin/marketplace.json

→

.metadata.version

.claude-plugin/marketplace.json

→

.plugins[0].version

验证配置：执行

jq . .claude-plugin/plugin.json

和

jq . .claude-plugin/marketplace.json

确保文件可解析，且三处版本字段一致：

bash

jq -r .version .claude-plugin/plugin.json
jq -r '.metadata.version, .plugins[0].version' .claude-plugin/marketplace.json

在
```
develop
```
分支上仅提交这两个JSON文件，提交信息为
```
Release vX.Y.Z
```
，然后推送
```
develop
```
分支。

为发布提交打标签：执行

git tag vX.Y.Z && git push origin vX.Y.Z

。

快速前向更新
```
main
```
分支：执行
```
git push origin develop:main
```
。绝不要使用
```
--force
```
参数——若推送被拒绝，说明无法执行快速前向合并，请回到前置条件步骤排查。
通过文件发布已草拟的说明，绝不要在命令中直接输入——提交信息通常包含反引号，若在
```
--notes "..."
```
参数中使用，Shell会将其作为命令替换执行。使用文件写入工具（或带引号的 heredoc，如
```
cat > notes.md <<'EOF'
```
）将说明写入临时文件，然后执行：
bash
```
gh release create vX.Y.Z --title "vX.Y.Z" --notes-file notes.md
```
验证：执行
```
git ls-remote origin refs/heads/main refs/heads/develop
```
查看两个分支的SHA是否一致，同时确认GitHub Release页面已创建。

Recovery

回滚方案

Push to
```
main
```
rejected: confirm admin (bypass) rights and re-run the ancestor check from Preconditions.
Wrong version committed but not yet tagged: fix the JSON files and amend the release commit before tagging.
Tag already pushed with wrong content: if the GitHub Release is not yet published, delete and re-create the tag; otherwise cut a follow-up patch release rather than rewriting history.

推送至
```
main
```
分支被拒绝：确认是否拥有管理员（绕过规则）权限，并重新执行前置条件中的祖先检查。
已提交错误版本但尚未打标签：修复JSON文件并修改发布提交后再打标签。
已推送错误内容的标签：若GitHub Release尚未发布，删除并重新创建标签；否则应发布后续补丁版本，而非重写历史。

Maintenance

维护说明

The canonical copy of this skill is

.claude/skills/skills-release/SKILL.md

.agents/skills/skills-release

is a symlink to it — edit only the canonical file.

本技能的标准副本位于

.claude/skills/skills-release/SKILL.md

。

.agents/skills/skills-release

是指向该文件的符号链接——仅可编辑标准文件。