🚀 publish-kit

One release prompt, every channel aligned. A directory-bundle Agent Skill + npm-installable CLI that turns "release this" into a coordinated publish across npm registries, GitHub + Gitee remotes, marketplace listings, repo RP fields, bilingual README, and git tags — all in lockstep. Works on DSH, Claude Code, Codex CLI, Gemini CLI, Cursor. Runs anywhere Node, Python, Rust, Go, or any exe target lives.

English · 简体中文

⭐ If you ship software and have ever lost a version to "I forgot to tag it," give it a Star.
_{Install: npx skills add https://github.com/EternalNight996/publish-kit or npm i -g @eternalnight/publish-kit}

🚀 Install

Three install paths, all one command. Pick the one that matches your host.:

# Skill bundle (any agent that reads .agents/skills/ — DSH, Claude Code, Codex, Gemini, Cursor)
npx skills add https://github.com/EternalNight996/publish-kit

# npm package (global CLI: bootstrap-release + release-exe available on PATH)
npm install -g @eternalnight/publish-kit

# DSH plugin via npm wrapper (uses the package's dsh.marketplace metadata)
dsh plugin --profile web add @eternalnight/publish-kit

For project-scoped (committable) installs and dsh-agent-skills UI integration, see INSTALL.md.

📖 Usage

As an Agent Skill (model-invoked)

Once loaded, the agent responds to any of these prompts automatically:

release this                       cut v0.4.2
publish my new version             ship it
bump version and tag               submit to marketplace
write the README                   slim the npm package
cargo publish this                 publish to PyPI
tag this commit                    push to GitHub and Gitee
build the exe and upload to GitHub Releases

The skill classifies the request into one of 8 release tracks (npm / DSH plugin / cargo / PyPI / PyInstaller exe / Go binary / Rust binary / Electron desktop), runs the per-track steps, and verifies every channel agrees on the version before declaring the release done. Full workflow in SKILL.md.

As a CLI (manual invocation)

After npm install -g @eternalnight/publish-kit, two commands are available:

# npm package release (six-step SOP: bump + publish + tag + push + RP)
bootstrap-release patch    # or minor | major

# exe release (PyInstaller / Go / Rust / Electron cross-platform build + GitHub Release)
release-exe rust mycli 1.0.0 "x86_64-unknown-linux-gnu,x86_64-pc-windows-msvc,x86_64-apple-darwin"

Both scripts take an optional -Draft / --draft flag to publish a draft release for review first.

🤖 Supported agents & languages (at a glance)

Agents that consume publish-kit

Programming languages & package ecosystems publish-kit ships templates for

Every non-DSH track follows the same SOP: bump version → tests + build → publish → git tag → push tags to both remotes → marketplace submission (where applicable) → RP fields.

This is not paranoia; every one of these happened in real releases documented in EXAMPLES.md.

🚀 After loading the skill: each pain solved with one prompt

flowchart LR
  A["User says:<br/>'release this'"] --> B{"Classify release track"}
  B -- "npm package<br/>(incl. DSH plugin)" --> C["npm SOP:<br/>bump → test → build → publish → tag → push tags → RP"]
  B -- "cargo / PyPI" --> D["Standard registry flow<br/>(REFERENCE.md H / I)"]
  B -- "Git-only project" --> E["git tag SOP:<br/>resolve hash from git log,<br/>verify subject, push both remotes"]
  B -- "exe artifact" --> F["PyInstaller:<br/>anchor on sys.executable,<br/>smoke-test no crash.log"]
  C & D & E & F --> G["Verify every channel<br/>agrees on version"]
  G -- "PASS" --> H["Submit to marketplaces:<br/>awesome PR + dsh-market Issue"]
  G -- "FAIL" --> X["❌ Block + report<br/>missing channel"]

🧬 Core design: why a Skill bundle, not an npm package

The publish-kit skill is not a cordis plugin and not an npm runtime dependency. It is a directory of dense facts + copy-paste templates that the agent consults when you ask it to release something. Three design decisions follow from that:

publish-kit complements rather than competes with the release tooling the agent already knows. It encodes specific release traps (npm pack --dry-run for files whitelist, git show for tag verification, full-width punctuation in .bat, the _MEIPASS PyInstaller path) that generic release helpers skip.

If you already use any of the above, publish-kit adds the layer they skip — the release boundary itself.

✨ Feature tour

./scripts/bootstrap-release.sh patch    # or minor / major

🌐 Detailed packaging ecosystem table

The tables below expand on the "at a glance" view above; each track's "where it lives" column names the registry or store the release lands in.

DSH ecosystem (native)

Non-DSH language libraries (host-agnostic)

Every non-DSH track goes through the same SOP: bump version → tests + build → publish → git tag → push tags to both remotes → marketplace submission (where applicable) → RP fields.

Tracks publish-kit explicitly does NOT cover

• Monorepo versioning strategy (lerna/changesets/nx release) — see find-skills for monorepo-specific tooling.
• Language-specific lint/test setup (separate skill per language).
• Host runtime debugging (DSH plugin loader errors, npm peer resolution diagnostics).
• Release internals design (package API surface, library architecture).

📚 Skill bundle discovery & inclusion standards

For publish-kit-style bundles to surface on every host that consumes them, the bundle must satisfy the conventions below. This section is both the standard publish-kit itself follows and the checklist you should apply to your own skill bundle.

Universal requirements (every host)

DSH marketplace inclusion matrix

GitHub repo RP (required for marketplace auto-scanners)

# Description (one-line, English; keywords help SEO)
gh api -X PATCH repos/<owner>/<repo> -f description="<one-line>"

# Topics (independent endpoint — DO NOT include topics in the PATCH above, it returns 400)
gh api -X PUT repos/<owner>/<repo>/topics --input topics.json
# topics.json content: {"names":["dsh-skill","agent-skills","publishing","release","npm","cargo","pypi"]}

Topic taxonomy

GitHub social preview

Upload assets/social-preview.png (1280×640 PNG) at Settings → General → Social preview. This is the image GitHub, Gitee, npm, and Twitter use when the URL is shared — a strong preview is the single largest click-rate lever. See the next section for design guidance.

For skill authors (publishing your own bundle)

1. Use this repo (publish-kit) as the template — copy .agents/skills/<your-skill>/ and the supporting top-level files.
2. Add the topics your bundle needs (don't add dsh-skill if you're shipping a cordis plugin only).
3. Open one PR against awesome-dsh-plugin and one Issue against dsh-market.
4. Run the skill's own SOP once on yourself before publishing (eat your own dogfood — proves the templates work).

🎨 README & repo home: how to maximize clicks

The biggest leverage point for a new release is the first 5 seconds a visitor spends on the GitHub repo home. This section codifies the moves publish-kit itself uses; copy them for your own bundles.

Repo home (the GitHub repo landing page)

README structure (the visited page)

Asset hygiene that wins clicks

• Banner at the top. Full-width PNG or WebP (GitHub README rendering prefers assets/readme-banner.{svg,png,webp} referenced as relative ./assets/...).
• GIFs under 10 MB. Compress with ffmpeg (REFERENCE.md D6). Over the threshold, GitHub silently drops the image.
• Use raw.githubusercontent.com URLs for any image rendered on GitHub AND npm AND Gitee. Keeps images in git (so both git hosts render them) but out of the npm tarball.
• Mermaid with a static-table fallback. Some hosts (older Cursor, Windsurf, Copilot) don't render Mermaid; provide a parallel table for those viewers.
• Pin a screenshot or GIF showing the result, not the install command. Visitors want to see the outcome, then decide.

SEO & shareability

• Repo Description: one line, English, with at least 2 keywords that search engines and humans both use (e.g. "release playbook for AI agents npm cargo PyPI").
• Topics: never duplicate the description; think of them as tags, not keywords. Aim for 5-10.
• README H1 should match the repo name. GitHub renders H1 as the page title.
• Social preview must show the project name + one-line tagline + version. A wall of text in social preview kills click-through.

Community signals that move the needle

• Star CTA in the README — one line near the top, not aggressive.
• "Used by" section if any real project depends on this — concrete social proof.
• A pinned Discussion / Q&A category at repo Settings → Features — invites questions, builds community.
• An explicit License — MIT for maximum reach. Missing license = legal ambiguity = lost users.
• Sponsor button at .github/FUNDING.yml — optional but signals sustainability.

publish-kit itself follows every line above; the README you are reading is the example.

🔧 Bundle layout

publish-kit/
├── README.md              # this file (English)
├── README.zh.md           # Chinese mirror
├── LICENSE                # MIT
├── CHANGELOG.md           # Keep a Changelog
├── .gitignore
├── .claude-plugin/
│   ├── plugin.json        # Vercel CLI manifest
│   └── marketplace.json   # Vercel CLI marketplace
└── .agents/skills/publish-kit/
    ├── SKILL.md           # main entry, <100 lines, model-invoked
    ├── REFERENCE.md       # dense facts (sections A-J)
    ├── TEMPLATE.md        # 10 copy-paste skeletons
    ├── INSTALL.md         # 4 install paths
    ├── DSH-DEPLOY.md      # DSH-specific deployment
    ├── COMPATIBILITY.md   # platform + frontmatter matrix
    └── EXAMPLES.md        # worked transcripts

🧪 Pre-release strategy (ship a beta, then promote)

For any non-trivial change, publish a pre-release first, validate, then promote to latest. A bug in latest hits 100% of npm install <pkg> users; a bug in beta only hits opt-in testers.

# Step 1: pre-release (npm `beta` dist-tag + GitHub Pre-release)
./scripts/bootstrap-release.sh patch --pre-release beta
# -> v0.4.1-beta.1

# Step 2: iterate on beta if bugs surface
./scripts/bootstrap-release.sh --pre-release beta --pre-release-bump 2
# -> v0.4.1-beta.2

# Step 3: promote to latest (no version bump; only moves dist-tag)
./scripts/bootstrap-release.sh --promote-from-beta --promote-version v0.4.1-beta.2
# -> v0.4.1 published to npm `latest` + GitHub Production release

Skip pre-release for: doc-only changes (README typo, comment cleanup), patch releases with no behavior change. Full SOP + recovery playbook in REFERENCE.md section K.

🗺 Roadmap

v0.1.0 (current): initial bundle — SKILL.md / REFERENCE.md / TEMPLATE.md / INSTALL.md / DSH-DEPLOY.md / COMPATIBILITY.md / scripts/bootstrap-release.{ps1,sh}.

v0.1.1 (current): added EXAMPLES.md with two worked transcripts (this release + a fictional DSH plugin npm flow).

v0.1.5 (current): added scripts/release-exe.{ps1,sh} for exe projects (PyInstaller / Go / Rust / Electron cross-platform builds + checksum + GitHub Release upload); TEMPLATE.md K section with 4 GitHub Actions workflows (K.1 PyInstaller / K.2 Go matrix / K.3 Rust matrix / K.4 Electron); EXAMPLES.md Example 3 (Rust CLI end-to-end transcript + 7-row pitfall table); README EN/ZH language toggle buttons.

v0.2.0 (current): npm package @eternalnight/publish-kit published to https://registry.npmjs.org/ — 19 files / 51 KB / scoped / MIT / explicit registry / signed. Bundles the skill directory, ships scripts as bin, includes cordis.patch.yml + dsh.marketplace metadata for dsh plugin install path. README top-of-page Install + Usage + Supported agents/languages tables. All "not published to npm" notes updated to reflect the publication.

v0.2.1 (current): docs cleanup — removed duplicate old Install section in both READMEs; marked npm wrapper Roadmap entry as completed (superseded by v0.2.0 publication).

v0.3.0 (current): repo governance — .github/ISSUE_TEMPLATE/{bug_report,feature_request,release_question}.yml, .github/PULL_REQUEST_TEMPLATE.md, .github/CONTRIBUTING.md, .github/SECURITY.md, .github/CODE_OF_CONDUCT.md, .github/FUNDING.yml; CI workflow (.github/workflows/ci.yml, 4 jobs: validate-skill / check-readme-links / check-package / check-markdown-toc); assets/social-preview.png (1280x640).

v0.5.0 (current): postinstall hardening — scripts/postinstall.js now correctly handles pre-existing Windows directory junctions at the 5 skill roots (~/.agents, ~/.claude, ~/.codex, ~/.gemini, ~/.dsh). Previously the script would unlink + symlink('junction') and throw EEXIST warnings on systems where the same source inode was already linked from another path, blocking dsh plugin --profile web add for any user who had the skill installed by the 0.4.0 copy. New behaviour: detect the existing link, compare realpath against the locally bundled source, keep it; honour PUBLISH_KIT_FORCE=1 to overwrite; report installed in N location(s) vs kept M existing link(s) separately. npm @eternalnight/publish-kit@0.5.0 on dist-tag=latest. Withdrew 0.5.0-beta.1 (npm deprecated, git tag deleted on both remotes).

v0.5.0-beta.1 (superseded — withdrawn): Pre-release workflow — REFERENCE.md K section + bootstrap-release.{ps1,sh} with --pre-release beta / --promote-from-beta flags; release-exe.{ps1,sh} with -Prerelease flag; release-doctor prerelease check; verify-release dist-tag channel; SKILL.md Workflow step 2 + README EN/ZH Pre-release strategy section. Withdrawn because the tag pointed at the CHANGELOG/docs commit and missed the post-install junction fix that ships in v0.5.0.

v0.4.0: scripts — release-doctor.mjs (12 pre-flight checks for git / npm / DSH marketplace / lockfile / docs / remotes / GH RP / .bat), verify-release.mjs (9-channel post-publish verifier), scripts/README.md (usage docs); .github/dependabot.yml (weekly GitHub Actions + npm + Docker auto-PR); repo settings (delete_branch_on_merge, allow_update_branch, Discussions); GitHub Releases for v0.2.0 / v0.2.1 / v0.3.0 / v0.4.0; PR #3554 conflicts resolved (now MERGEABLE); Gitee mirror complete (https://gitee.com/eternalnight996/publish-kit has main + 9 tags); npm @eternalnight/publish-kit@0.4.0 published (20 files / 56.6 KB / signed).

Coming soon:

• release-doctor.mjs — pre-flight checker that scans a target repo for the 9-row pitfall table in REFERENCE.md J and reports drift before publish
• verify-release.mjs — post-publish verifier that walks every channel (npm view, gh release, gitee release, awesome-dsh-plugin search, dsh-market issue status, GitHub topics, marketplace catalog) and reports per-channel status
• npm wrapper package (@eternalnight/publish-kit) — ships skills/publish-kit/ as an asset, symlinks into ~/.agents/skills/ via postinstall, exposed via dsh plugin --profile web add (v0.2.0)
• Multi-language templates — add Rust Cargo.lock strategy, Python setup.cfg legacy path, GitLab CI / Gitea Actions release workflows

📦 Release log

• v0.5.0 (2026-09-03): postinstall hardening (scripts/postinstall.js keeps pre-existing junctions, detects EEXIST correctly, honours PUBLISH_KIT_FORCE=1, separates installed N vs kept M). npm @eternalnight/publish-kit@0.5.0 promoted to dist-tag=latest. Withdraws 0.5.0-beta.1 (npm deprecate + tag delete on both remotes).
• v0.5.0-beta.1 (2026-08-29, withdrawn): pre-release workflow (REFERENCE.md K + bootstrap-release prerelease/promote flags + release-exe prerelease flag + release-doctor + verify-release dist-tag check + SKILL + README EN/ZH). npm @eternalnight/publish-kit@0.5.0-beta.1 deprecated on dist-tag=beta. GitHub Pre-release removed.
• v0.4.0 (2026-08-28): release-doctor.mjs (12 pre-flight checks) + verify-release.mjs (9-channel post-publish verifier) + scripts/README.md; .github/dependabot.yml; repo settings (delete_branch_on_merge + Discussions); PR #3554 conflicts resolved; Gitee mirror complete; npm @eternalnight/publish-kit@0.4.0 published.
• v0.3.0 (2026-08-28): repo governance — issue templates (bug/feature/question), PR template, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, FUNDING; CI workflow (4 jobs); social-preview.png (1280x640).
• v0.2.1 (2026-08-28): docs cleanup — removed duplicate Install section in both languages; marked npm wrapper Roadmap item as completed.
• v0.2.0 (2026-08-28): npm package @eternalnight/publish-kit published (51 KB, 19 files, signed); top-of-page Install + Usage + Supported agents/languages tables; README/DSH-DEPLOY/CHANGELOG npm-publication notes synchronized.
• v0.1.5 (2026-08-28): scripts/release-exe.{ps1,sh} (PyInstaller / Go / Rust / Electron build + checksum + GitHub Release); TEMPLATE.md K section (4 GitHub Actions workflows); EXAMPLES.md Example 3 (Rust CLI transcript); README EN/ZH language toggle.
• v0.1.4 (2026-08-28): EN/ZH language toggle buttons at the top of both READMEs.
• v0.1.3 (2026-08-28): language support matrix (DSH + 12 non-DSH libraries); skill bundle inclusion matrix; README/homepage attractiveness guide; banner SVG.
• v0.1.2 (2026-08-28): README rewritten following dsh-memory-eternal productization pattern; npm status clarified; bilingual README.zh.md.
• v0.1.1 (2026-08-28): bootstrap-release scripts (ps1 + sh); EXAMPLES.md worked transcripts; SKILL.md See also extended; README script reference added.
• v0.1.0 (2026-08-28): initial bundle — 6-document skill, 10 templates, 4 install paths, full DSH deployment guide. PR #3554 to awesome-dsh-plugin (category=skill); Issue #94 to dsh-market.

See CHANGELOG.md for the Keep a Changelog-style record.

🔌 Discovery / Distribution

The GitHub repo carries the topics that auto-discovery scanners read. Listing them makes the bundle findable through every supported channel.

GitHub repo topics set:

agent-skills · cargo · dsh-skill · npm · publishing · pypi · release

📜 License

MIT

Ship once, ship in agreement. ⭐ If you've ever debugged "why is Gitee 4 versions behind," give it a Star.