npm-release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

pnpm / Bun / npm Package Release Workflow

pnpm / Bun / npm 包发布工作流

Package manager detection

包管理器检测

Detect the active package manager by lockfile first. Priority order:

```
pnpm-lock.yaml
```
→ pnpm
```
bun.lock
```
or
```
bun.lockb
```
→ bun
```
package-lock.json
```
→ npm

If no lockfile is present, fall back to tool availability in the same preference order: pnpm → bun → npm. If a lockfile is present but its tool is missing, error out — don't silently switch managers.

release-prepare.sh

runs this check and prints

Package manager: <name>

. Read that output and use the same manager consistently in every later step. All command blocks below list pnpm first, then bun, then npm — pick the one for the detected manager.

首先通过锁文件检测当前使用的包管理器，优先级顺序：

```
pnpm-lock.yaml
```
→ pnpm
```
bun.lock
```
或
```
bun.lockb
```
→ bun
```
package-lock.json
```
→ npm

如果没有锁文件，则按照相同的优先级顺序检查工具是否可用：pnpm → bun → npm。如果存在锁文件但对应的工具未安装，则报错——不要静默切换管理器。

release-prepare.sh

脚本会执行此检查并输出

Package manager: <name>

。读取该输出并在后续所有步骤中一致使用同一个管理器。以下所有命令块均先列出pnpm命令，再是bun，最后是npm——请选择与检测到的管理器对应的命令。

Purpose

目的

Automate the release process for pnpm / bun / npm packages with:

Pre-flight validation and safety checks
Intelligent version bump recommendations
Git workflow automation (commit, tag, push)
User approval before publishing
CI/CD integration support

为pnpm / bun / npm包自动化发布流程，包含：

预发布验证与安全检查
智能版本升级建议
Git工作流自动化（提交、打标签、推送）
发布前需用户批准
CI/CD集成支持

When to Use This Skill

使用场景

Use this skill when the user:

Asks to "release", "publish", or "create a new version"
Wants to bump the package version
Needs to create a release tag
Mentions releasing to npm registry

当用户有以下需求时使用此技能：

请求“发布”“推送”或“创建新版本”
需要升级包版本
需要创建发布标签
提及要发布到npm registry

Bundled Scripts

内置脚本

This skill includes three helper bash scripts in the

scripts/

directory:

release-prepare.sh - Validates git status, branch, and runs dry-run build
release-analyze.sh - Analyzes commits since last tag and suggests version bump
release-execute.sh - Creates git tag and pushes to remote

To use bundled scripts, execute them from the skill directory:

bash

bash scripts/release-prepare.sh
bash scripts/release-analyze.sh
bash scripts/release-execute.sh

These scripts work with any pnpm/bun/npm project and don't require project-specific setup.

此技能在

scripts/

目录下包含三个辅助bash脚本：

release-prepare.sh - 验证Git状态、分支，并执行构建预演
release-analyze.sh - 分析上次标签后的提交记录并建议版本升级类型
release-execute.sh - 创建Git标签并推送到远程仓库

使用内置脚本时，请从技能目录执行：

bash

bash scripts/release-prepare.sh
bash scripts/release-analyze.sh
bash scripts/release-execute.sh

这些脚本适用于任何pnpm/bun/npm项目，无需项目专属配置。

Prerequisites

前置条件

```
jq
```
installed (used by release-analyze.sh and release-execute.sh)
Git repository with at least one prior commit

已安装
```
jq
```
（release-analyze.sh和release-execute.sh会用到）
Git仓库至少有一次提交记录

Asking the User

用户交互规则

Every question in this skill is written as

AskUserQuestion

options. Use that tool where the host offers it, or the host's nearest structured-choice equivalent. Where the host has neither, ask the same question in normal chat as a numbered list of 2–5 options — recommended first, one short line of description each — and wait for the user to reply with a number.

User prompts occur at Step 0 (ambiguous conventions) and Step 7 (release approval). Do not proceed past either without a user reply. Never guess ambiguous conventions. Never push without approval.

此技能中的所有问题均以

AskUserQuestion

选项形式呈现。若宿主平台提供该工具则直接使用，或使用宿主平台最相近的结构化选择功能。若两者都没有，则在普通对话中以2-5个选项的编号列表形式提问——推荐选项放在首位，每个选项配一行简短描述——等待用户回复编号。

用户交互会出现在步骤0（模糊约定）和步骤7（发布批准）环节。在未得到用户回复前，不得推进这两个环节之后的步骤。绝不猜测模糊的约定，绝不未经批准就推送内容。

Release Workflow

发布工作流

Follow these steps in order. Create an in-memory plan at the start.

请按顺序执行以下步骤。开始前先在脑中规划好整体流程。

Step 0: Read Project Conventions

步骤0：读取项目约定

Before doing anything else, read the project's instruction files to honor local conventions. Check, in order:

```
CLAUDE.md
```
at the repo root
```
AGENTS.md
```
at the repo root
```
.agents/
```
or
```
.claude/
```
rule files if they exist

Extract and apply whatever applies to this release:

Release commit message format — e.g.
```
chore: release v<version>
```
or a project-specific template. This overrides the default
```
Release v<version>
```
used in Step 5.
Pre-release prerequisites — e.g. updating
```
CHANGELOG.md
```
via a separate skill, regenerating docs, running a project-specific validation script. Run these before bumping the version so
```
release:dry
```
in Step 2 can gate on them.
Branch policy — some projects allow releases only from
```
master
```
, some from version branches (
```
x.y
```
), some restrict by environment.
Tag format — default is
```
v<version>
```
. If the project documents something else, use it.
Dist-tag policy — how prerelease versions are routed (
```
alpha
```
/
```
beta
```
/
```
rc
```
/
```
next
```
).

CLAUDE.md

AGENTS.md

doesn't exist or doesn't say anything about releases, fall back to the defaults below. If an instruction is ambiguous, ask the user, per Asking the User.

在执行任何操作前，先读取项目的说明文件以遵循本地约定。按以下顺序检查：

仓库根目录下的
```
CLAUDE.md
```
仓库根目录下的
```
AGENTS.md
```
若存在
```
.agents/
```
或
```
.claude/
```
规则文件，也需检查

提取并应用与本次发布相关的规则：

发布提交信息格式——例如
```
chore: release v<version>
```
或项目专属模板。这会覆盖步骤5中默认使用的
```
Release v<version>
```
。
预发布前置要求——例如通过其他技能更新
```
CHANGELOG.md
```
、重新生成文档、运行项目专属验证脚本。请在升级版本前完成这些操作，以便步骤2中的
```
release:dry
```
可以将其作为检查项。
分支策略——部分项目仅允许从
```
master
```
分支发布，部分允许从版本分支（如
```
x.y
```
）发布，部分会按环境限制。
标签格式——默认是
```
v<version>
```
。如果项目文档指定了其他格式，请使用指定格式。
Dist-tag策略——预发布版本的路由规则（如
```
alpha
```
/
```
beta
```
/
```
rc
```
/
```
next
```
）。

如果

CLAUDE.md

AGENTS.md

不存在或未提及发布相关内容，则使用以下默认规则。若某个说明模糊不清，请按照用户交互规则询问用户。

Step 1: Pre-flight Checks

步骤1：预发布检查

Verify git status and branch:

Check current branch is
```
master
```
or
```
main
```
(or other default branch if different)
Check for uncommitted changes (staged or unstaged)
If there are issues:
- Reply with a short, clear message explaining the problem
- Suggest stashing changes and trying again:
```
git stash && [retry]
```
- Do not proceed further

Use the bundled script:

bash

bash scripts/release-prepare.sh

Or manual checks:

bash

undefined

验证Git状态与分支：

检查当前分支是否为
```
master
```
或
```
main
```
（或项目指定的其他默认分支）
检查是否有未提交的更改（已暂存或未暂存）
若存在问题：
- 回复简短清晰的消息说明问题
- 建议暂存更改后重试：
```
git stash && [retry]
```
- 不得继续推进流程

使用内置脚本：

bash

bash scripts/release-prepare.sh

或手动检查：

bash

undefined

Check branch

检查分支

git branch --show-current

Check for changes

检查更改

git status --porcelain

Verify build and packaging

验证构建与打包

pnpm release:dry

or

或

bun run release:dry

or

或

npm publish --dry-run

undefined

npm publish --dry-run

undefined

Step 2: Validate Release Build

步骤2：验证发布构建

Run dry-run release to ensure everything builds correctly:

bash

pnpm release:dry

执行发布预演以确保所有内容构建正确：

bash

pnpm release:dry

or

或

bun run release:dry

or

或

npm publish --dry-run


If validation fails:

- Report the error to the user
- Do not proceed with release
- Suggest fixing issues first

npm publish --dry-run


若验证失败：

- 将错误告知用户
- 不得继续推进发布流程
- 建议先修复问题

Step 3: Analyze Commits for Version Decision

步骤3：分析提交记录以确定版本

Determine whether to use

major

minor

, or

patch

bump by analyzing changes since last release.

Use the bundled script:

bash

bash scripts/release-analyze.sh

Or manual analysis:

bash

undefined

通过分析上次发布后的提交记录，决定是升级

major

、

minor

还是

patch

版本。

使用内置脚本：

bash

bash scripts/release-analyze.sh

或手动分析：

bash

undefined

Get last version tag

获取上一个版本标签

git describe --tags --abbrev=0

Show commits since last tag

显示上一个标签后的所有提交

git log $(git describe --tags --abbrev=0)..HEAD --oneline

Show detailed changes if needed

若需要，显示详细变更

git log $(git describe --tags --abbrev=0)..HEAD --stat


**Decision criteria:**

- **Major bump** (x.0.0): Breaking API changes, removal of public APIs, incompatible behavior changes (post-1.0 only)
- **Minor bump** (0.x.0): New features, significant enhancements, API additions, breaking changes (in pre-1.0)
- **Patch bump** (0.0.x): Bug fixes, small improvements, documentation updates, refactoring

If commits don't provide enough context, examine specific diffs:

```bash
git diff $(git describe --tags --abbrev=0)..HEAD -- [key-files]

git log $(git describe --tags --abbrev=0)..HEAD --stat


**决策标准：**

- **Major升级**（x.0.0）：API破坏性变更、移除公共API、不兼容的行为变更（仅适用于1.0版本之后）
- **Minor升级**（0.x.0）：新增功能、重大增强、API新增、破坏性变更（适用于1.0版本之前）
- **Patch升级**（0.0.x）：Bug修复、小改进、文档更新、代码重构

若提交记录提供的上下文不足，可查看具体差异：

```bash
git diff $(git describe --tags --abbrev=0)..HEAD -- [关键文件]

Step 4: Bump Version

步骤4：升级版本

Update

package.json

version. Use the detected package manager; always pass the flag that disables the automatic commit/tag (we create those manually in later steps).

bash

undefined

更新

package.json

中的版本号。使用检测到的包管理器；务必添加禁用自动提交/打标签的参数（我们会在后续步骤中手动创建这些内容）。

bash

undefined

pnpm

pnpm version minor --no-git-tag-version pnpm version patch --no-git-tag-version

Bun (uses bun pm version)

Bun（使用bun pm version）

bun pm version minor --no-git-tag-version bun pm version patch --no-git-tag-version

npm

npm version minor --no-git-tag-version npm version patch --no-git-tag-version


**Prerelease bumps** (alpha/beta/rc) use `prerelease` with an explicit preid:

```bash

npm version minor --no-git-tag-version npm version patch --no-git-tag-version


**预发布版本升级**（alpha/beta/rc）需使用`prerelease`参数并指定明确的预发布标识：

```bash

pnpm / npm

pnpm version prerelease --preid=alpha --no-git-tag-version npm version prerelease --preid=alpha --no-git-tag-version

Bun

bun pm version prerelease --preid=alpha --no-git-tag-version


**Important:** `--no-git-tag-version` prevents automatic commit/tag creation — we create them explicitly in Steps 5 and 6.

bun pm version prerelease --preid=alpha --no-git-tag-version


**重要提示：** `--no-git-tag-version`参数会阻止自动创建提交/标签——我们会在步骤5和6中显式创建。

Step 5: Commit Version Bump

步骤5：提交版本升级

Use the release commit message format captured in Step 0. Only fall back to the generic

Release v<version>

if the project did not specify one.

bash

undefined

使用步骤0中获取的发布提交信息格式。仅当项目未指定格式时，才使用通用的

Release v<version>

作为 fallback。

bash

undefined

Stage package.json and whichever lockfile exists

暂存package.json和对应的锁文件

git add package.json pnpm-lock.yaml bun.lock bun.lockb package-lock.json 2>/dev/null || true

Commit with the format from Step 0 (examples — pick ONE):

按照步骤0中的格式提交（示例——选择其中一种）：

git commit -m "Release v{{VERSION}}" # fallback default git commit -m "chore: release v{{VERSION}}" # Conventional Commits git commit -m "release: v{{VERSION}}" # project-specific alternative


If the project uses a non-obvious template (commit body, trailers, sign-off), reproduce it exactly as documented. Never invent a format the project didn't specify.

git commit -m "Release v{{VERSION}}" # 默认fallback格式 git commit -m "chore: release v{{VERSION}}" # 约定式提交格式 git commit -m "release: v{{VERSION}}" # 项目专属替代格式


若项目使用非通用模板（如提交正文、尾部信息、签名），请严格按照文档重现。绝不自行发明项目未指定的格式。

Step 6: Create Git Tag

步骤6：创建Git标签

Tag the release commit with a signed tag (

-s

implies

-a

, so the tag is also annotated — required for

--follow-tags

, preserves tagger/date/message, and provides a verifiable signature regardless of the user's

tag.gpgSign

config):

bash

git tag -s v{{VERSION}} -m "Release v{{VERSION}}"

Example:

git tag -s v0.16.0 -m "Release v0.16.0"

If the user has no signing key configured,

git tag -s

fails with a gpg/ssh error. In that case, advise them to configure SSH or GPG signing (

user.signingkey

gpg.format

) before retrying.

为发布提交创建签名标签（

-s

参数隐含

-a

，因此标签同时是带注释的——这是

--follow-tags

所需的，可保留标签创建者/日期/信息，并提供可验证的签名，不受用户

tag.gpgSign

配置影响）：

bash

git tag -s v{{VERSION}} -m "Release v{{VERSION}}"

示例：

git tag -s v0.16.0 -m "Release v0.16.0"

若用户未配置签名密钥，

git tag -s

会因gpg/ssh错误失败。这种情况下，建议用户配置SSH或GPG签名（

user.signingkey

、

gpg.format

）后重试。

Step 7: User Review & Approval

步骤7：用户审核与批准

CRITICAL: Always pause here for explicit user approval unless explicitly told to skip.

Present a summary to the user (each on a new line):

Version: What version is being released (e.g., v0.16.0)
Bump type: Minor or Patch
Changes summary: 2-4 bullet points of key changes based on your analysis
What happens next: Push commits and tags, CI/CD will publish

Ask for approval, per Asking the User:

```
Yes
```
(Recommended) — Proceed with pushing and releasing
```
No
```
— Cancel the release and keep local changes for review

With

AskUserQuestion

, "Other" is added automatically and lets the user provide custom instructions. With the chat fallback, the user can always reply with free text instead of picking a number.

Example structured call:

AskUserQuestion:
  question: "Ready to push v{{VERSION}} and release?"
  header: "Release"
  options:
    - label: "Yes (Recommended)"
      description: "Push commits and tags to trigger CI/CD publishing"
    - label: "No"
      description: "Cancel release (local commit and tag will remain)"

Example chat fallback:

Ready to push v{{VERSION}}?
1. Yes — push commits and tags to trigger release
2. No — keep local commit and tag for review

If user selects:

Yes → Proceed to Step 8
No → Inform the user that the local commit and tag remain in place for review. Do not run cleanup automatically. If the user wants to undo the release prep, explain the cleanup steps and ask before performing any destructive git command.
Other → Follow user's custom instructions

关键：除非明确告知可跳过，否则务必在此暂停并等待用户明确批准。

向用户呈现以下摘要（每项单独一行）：

版本号： 即将发布的版本（例如v0.16.0）
升级类型： Minor或Patch
变更摘要： 根据分析列出2-4个关键变更要点
后续操作： 推送提交和标签，CI/CD将执行发布

按照用户交互规则请求批准：

```
Yes
```
（推荐）——继续推送并发布
```
No
```
——取消发布，保留本地更改供审核

使用

AskUserQuestion

时，会自动添加“Other”选项，允许用户提供自定义指令。若使用对话 fallback，用户也可回复自由文本而非选择编号。

结构化调用示例：

AskUserQuestion:
  question: "是否准备推送v{{VERSION}}并发布？"
  header: "发布确认"
  options:
    - label: "是（推荐）"
      description: "推送提交和标签以触发CI/CD发布"
    - label: "否"
      description: "取消发布（本地提交和标签将保留）"

对话 fallback 示例：

是否准备推送v{{VERSION}}？
1. 是 —— 推送提交和标签以触发发布
2. 否 —— 保留本地提交和标签供审核

用户选择后的处理：

是 → 推进至步骤8
否 → 告知用户本地提交和标签已保留供审核。不得自动执行清理操作。若用户希望撤销发布准备，请说明清理步骤并在执行任何破坏性Git命令前询问用户。
Other → 遵循用户的自定义指令

Step 8: Push Release

步骤8：推送发布内容

Only after user approves:

Use the bundled script:

bash

bash scripts/release-execute.sh

Or manual push:

bash

git push --follow-tags

--follow-tags

pushes commits plus any annotated tags reachable from them in a single round-trip. It avoids the torn state of two separate pushes and won't accidentally publish stale local tags from other branches the way

git push --tags

does.

仅在用户批准后执行：

使用内置脚本：

bash

bash scripts/release-execute.sh

或手动推送：

bash

git push --follow-tags

--follow-tags

参数会在一次往返中推送提交以及所有可从提交到达的带注释标签。这避免了两次单独推送导致的不一致状态，且不会像

git push --tags

那样意外推送其他分支的过时本地标签。

Step 9: Confirm Completion

步骤9：确认完成

Inform the user:

Release has been pushed
CI/CD will handle publishing (if configured)
Provide relevant links:
- GitHub release page
- npm package page
- Any deployment URLs

告知用户：

发布内容已推送
CI/CD将处理发布（若已配置）
提供相关链接：
- GitHub发布页面
- npm包页面
- 任何部署URL

Bundled Helper Scripts Details

内置辅助脚本详情

The three bundled scripts provide complete release workflow support:

三个内置脚本提供完整的发布工作流支持：

scripts/release-prepare.sh

Validates current branch is master/main
Checks for uncommitted changes
Detects package manager via lockfile first (pnpm → bun → npm), falls back to tool availability, and prints the result

Runs dry-run release to verify build (

pnpm release:dry

bun run release:dry

npm publish --dry-run

)

Provides clear error messages and suggestions

验证当前分支是否为master/main
检查是否有未提交的更改
首先通过锁文件检测包管理器（pnpm → bun → npm），若没有锁文件则检查工具可用性，并输出检测结果

执行发布预演以验证构建（

pnpm release:dry

bun run release:dry

npm publish --dry-run

）

提供清晰的错误消息和建议

scripts/release-analyze.sh

Finds last release tag
Shows all commits since last release
Analyzes commit messages for features, fixes, etc.
Provides version bump recommendation (minor vs patch)
Shows file change statistics

查找上一个发布标签
显示上一个标签后的所有提交
分析提交信息以识别功能新增、Bug修复等
提供版本升级建议（minor或patch）
显示文件变更统计

scripts/release-execute.sh

Reads version from package.json
Creates git tag with v prefix
Pushes commits and tags to remote
Confirms before pushing if tag exists
Shows post-release verification links

从package.json读取版本号
创建带v前缀的Git标签
将提交和标签推送到远程仓库
若标签已存在则在推送前确认
显示发布后的验证链接

Error Handling

错误处理

If any step fails:

Stop the workflow immediately
Report the error clearly to the user
Suggest corrective action
Do not proceed to next steps

若任何步骤失败：

立即停止工作流
向用户清晰报告错误
建议纠正措施
不得推进至下一步骤

Common Issues

常见问题

Uncommitted changes:

Suggest:
```
git stash
```
then retry, or commit changes first

Wrong branch:

Suggest:
```
git checkout master
```
then retry

Failed dry-run:

Build errors: Fix and retry
Lint errors: Run the project's lint-fix script (
```
pnpm lint:fix
```
/
```
bun run lint:fix
```
/
```
npm run lint:fix
```
) then retry
Type errors: Fix TypeScript issues first
Project-specific gate failures (e.g. missing CHANGELOG section): see what Step 0 surfaced and resolve before retrying

No tags found:

First release: Suggest starting with v0.1.0 or v1.0.0
Ask user which version to use as baseline

未提交的更改：

建议：
```
git stash
```
后重试，或先提交更改

错误分支：

建议：
```
git checkout master
```
后重试

预演失败：

构建错误：修复后重试
代码检查错误：运行项目的代码检查修复脚本（
```
pnpm lint:fix
```
/
```
bun run lint:fix
```
/
```
npm run lint:fix
```
）后重试
类型错误：先修复TypeScript问题
项目专属检查失败（如缺少CHANGELOG章节）：查看步骤0中提取的规则并解决后重试

未找到标签：

首次发布：建议从v0.1.0或v1.0.0开始
询问用户将哪个版本作为基线

Advanced: Manual Publishing

进阶：手动发布

If CI/CD is not configured or manual publishing is needed:

bash

undefined

若未配置CI/CD或需要手动发布：

bash

undefined

After pushing tags

推送标签后执行

pnpm publish --access public

or

或

bun publish --access public

or

或

npm publish --access public


**Note:** Most projects should use CI/CD for publishing to ensure consistency and security.

npm publish --access public


**注意：** 大多数项目应使用CI/CD进行发布，以确保一致性和安全性。

Integration Notes

集成说明

This skill is self-contained and requires no project-specific setup. However:

CI/CD Integration: Projects should configure GitHub Actions or similar for automated npm publishing
Documentation: Projects can reference this skill in their CLAUDE.md or README
Custom Scripts: If projects already have release scripts, use those instead of bundled ones
Flexibility: All steps can be performed manually if bundled scripts don't fit the workflow

此技能是独立的，无需项目专属配置。但请注意：

CI/CD集成：项目应配置GitHub Actions或类似工具以实现npm自动发布
文档：项目可在CLAUDE.md或README中引用此技能
自定义脚本：若项目已有发布脚本，请使用项目自有脚本而非内置脚本
灵活性：若内置脚本不符合工作流，所有步骤均可手动执行