publish
Skill19 starsChanged 3 months agoMITView on GitHub
Bump version, build, test, publish to npm, and install locally
- Reads credentials
- Installs packages
- Commits and pushes
66 other projects use a version of this.
Adopted by
Most recently taken up by
- vincentventalon/claude-code-video-editing-skilltheir own version, first seen Nov 15, 2026
- vincentventalon/my-claude-skillstheir own version, first seen Nov 15, 2026
- foster-systems/shelftheir own version, first seen Nov 15, 2026
- carlos2219/web-kittheir own version, first seen Nov 15, 2026
- shoot16625/note-clitheir own version, first seen Nov 15, 2026
- markmhendrickson/neotomatheir own version, first seen Nov 15, 2026
Used with
Projects with it also use create, render and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MicrosoftSkillcreate
Also in 4 projects that use this
suxrobGMSkillrender
Generate raster images (PNG, JPEG, WebP) from natural language prompts using Python rendering engines. Covers graphics, charts, layouts, and procedural art. Not for SVG output.
Also in 3 projects that use this
JaimeGBASkillingest
Digest an external source (article, paper, transcript, URL, book chapter) and integrate its content into the knowledge base
Also in 6 projects that use this
genomewalkerSkillexplore
RLM-style recursive memory exploration - dynamically navigate the memory graph
Also in 4 projects that use this
GoogleSkilltranslate
Translates a common phrase into one or more languages.
Also in 3 projects that use this
VercelSkillsetup
Set up Vercel CLI and project configuration. Use when the user says "set up Vercel", "configure Vercel", "link to Vercel", or "vercel init".
Also in 14 projects that use this
Other versions66 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 66
- code-yeongyu/oh-my-openagent★ 71ksame name
- code-yeongyu/oh-my-opencode★ 71ksame name
- garrytan/gbrain★ 33ksame name
- TencentCloud/Octop★ 12ksame name
- harbor-framework/harbor★ 7.1ksame name
- laude-institute/harbor★ 7.1ksame name
- Q00/ouroboros★ 6.4ksame name
- paean-ai/deeptide★ 1.1ksame name
- ZimoLiao/scholaraio★ 585same name
- ai-search-guru/getcito-worlds-first-open-source-aio-aeo-or-geo-tool★ 432same name
56 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository30 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- src/CLAUDE.mdCLAUDE.md
- communeSkill
- connector-builderSkill
- distillSkill
- divineSkill
- eldarSkill
- flflSkill
- flo-simplifySkill
- floSkill
- floSkill
- guidanceSkill
- healerSkill
- luminariumSkill
- meditateSkill
- memory-optimizationSkill
- memory-patternsSkill
- memory-teamSkill
- memory-worktreeSkill
- optimize-learningsSkill
- perf-auditSkill
- quickenSkill
- reasoningbank-intelligenceSkill
- reset-epicSkill
- spell-builderSkill
- spell-scheduleSkill
- test-gapsSkill
- vector-searchSkill
- verifySkill
- wardSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
20 rules. 0 are common, 8 are distinctive, and 12 are very specific to this project.
0
Common
Most of the 55 edited versions we read keep these.
8
Distinctive
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 40
Default bump type is patch if not specified
- Very specific: line 44
Without
-rc: Use npm version <patch|minor|major> --no-git-tag-version - Very specific: line 46
If current version is already an RC of the same bump level (e.g., 4.8.57-rc.3), increment the RC number (→ 4.8.57-rc.4)
- Very specific: line 74
Always runs regardless of CHECK_MODE.
- Distinctive: line 76
Must exit 0: If it fails, stop and fix the build error.
- Distinctive: line 94
Must have 0 test file failures: If any test files fail, retest them individually to distinguish real failures from flaky ones (per broken …
- Distinctive: line 117
Read the fingerprint output from Step 1.
- Very specific: line 131
If CHECK_MODE=true, walk all manual gates regardless of triggers (full audit).
- Very specific: line 133
If the trigger set is none AND CHECK_MODE=false: skip Step 7 entirely.
- Distinctive: line 137
Commit the version bump files:
- Distinctive: line 145
Only commit version-related files.
- Very specific: line 250
If 401 or "not logged in": auth token in ~/.npmrc is missing or expired.
- Very specific: line 264
Verify with npm whoami before proceeding.
- Distinctive: line 276
If npm returns an OTP/one-time-password error, ask the user for their authenticator code
- Very specific: line 305
If package.json or package-lock.json changed from the install:
- Distinctive: line 338
All commands run from the project root — never cd into subdirectories
- Very specific: line 339
Never use --force on npm publish
- Very specific: line 340
Never install moflo globally — it is always a local devDependency
- Distinctive: line 341
If any step that DID run fails, stop and fix the issue before proceeding — do not skip steps
- Very specific: line 347
Use --check / -ch when:
“Common” is measured: kept by at least 6 in 10 of the 55 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/publish - Version Bump, Build, Test & Publish
Automated release pipeline for moflo. Bumps version, commits, builds, tests, runs doctor, publishes to npm, and installs the new version locally.
Arguments: $ARGUMENTS
Usage
/publish # patch bump, default mode (skips CI-covered gates)
/publish minor # minor bump (4.8.56 → 4.9.0)
/publish major # major bump (4.8.56 → 5.0.0)
/publish -rc # patch RC bump (4.8.56 → 4.8.57-rc.1)
/publish minor -rc # minor RC bump (4.8.56 → 4.9.0-rc.1)
/publish --check # full pre-flight (lint + test + smoke + everything)
/publish -ch # short form of --check
/publish minor -ch # combine: full pre-flight on a minor bump--check / -ch flag (presence-only)
Default (flag absent): runs build + doctor + trigger-based manual checks only. Skips local lint/test/smoke because lint+test are covered by ci.yml on every PR + push to main, and cross-platform smoke is dispatched as part of this skill (Step 8.5 below) — the release-smoke.yml workflow runs the full 3-OS matrix on the exact commit about to be published.
With --check or -ch (any presence): runs the full pre-flight from pre-publish-rules.md — lint, build, test, doctor (strict), local clean smoke, local populated smoke, and a forced full walk of every manual gate. Use this for publishes that didn't go through a green PR, risky releases, or when you want belt-and-suspenders on the local box in addition to the CI matrix.
The flag is presence-only. --check and -ch both set it to true. There is no --check=true / --check=false syntax — absence means false.
Step-by-Step Procedure
Step 0: Parse Arguments
- Default bump type is
patchif not specified -rcflag: produce a release candidate--checkor-ch(presence): setCHECK_MODE=true. OtherwiseCHECK_MODE=false.- Determine the new version string:
- Without
-rc: Usenpm version <patch|minor|major> --no-git-tag-version - With
-rc: Calculate manually:- If current version is already an RC of the same bump level (e.g.,
4.8.57-rc.3), increment the RC number (→4.8.57-rc.4) - Otherwise, bump the base version and append
-rc.1(e.g.,4.8.56→4.8.57-rc.1) - Write with:
npm version <new-version> --no-git-tag-version
- If current version is already an RC of the same bump level (e.g.,
- Without
Step 1: Compute Manual-Check Fingerprint (always)
bash .claude/skills/publish/fingerprint.shThe script diffs HEAD against the most recent chore: install moflo@* commit and pattern-matches the file list against the manual-gate triggers from pre-publish-rules.md. Output is one block:
Triggered manual checks: bin-scriptfiles-sync info-loss-audit
Diff range: <last-publish-sha>..HEAD
Changed files: 7Triggered manual checks: none means gates 1/2/6 don't apply to this diff — skip them entirely.
This step costs ~50 tokens and is the cornerstone of token-efficient default mode.
Step 2: Build (always)
npm run buildAlways runs regardless of CHECK_MODE. Syncs the version to src/cli/version.ts via the version lifecycle script, then compiles all TypeScript. Confirms the deliverables on disk are correct.
Must exit 0. If it fails, stop and fix the build error.
Step 3: Lint (only if CHECK_MODE=true)
npm run lintSkipped by default — ci.yml runs lint on every PR with max-warnings 0. Run when --check is set.
Step 4: Tests (only if CHECK_MODE=true)
npm testSkipped by default — ci.yml runs the full test suite on every PR. Run when --check is set.
Must have 0 test file failures. If any test files fail, retest them individually to distinguish real failures from flaky ones (per broken window theory). Fix all real failures before proceeding.
Step 5: Doctor (always — strict, no repair)
npx moflo doctor --strictDoctor is the only check with no CI equivalent — it inspects local state (daemon lock, embeddings hygiene, sandbox tier, vector-stats freshness) that CI cannot validate for you. Always runs in --strict mode regardless of CHECK_MODE.
Never --fix on the publish path. A release pipeline must fail fast on broken local state, not silently repair it; a doctor that auto-repairs masks the very signal we want — "something is off, stop and investigate before shipping." If doctor --strict fails, stop and run flo healer --fix (or npx moflo doctor --fix) interactively, verify the repair, then retry the publish.
Step 6: Local Smoke Tests (only if CHECK_MODE=true)
npm run test:smoke
npm run test:smoke:populatedSkipped by default. Local smoke covers the same harness as CI's Ubuntu leg, so it adds little signal over release-smoke.yml's Ubuntu matrix entry (Step 8.5). Run only when --check is set — useful if you want belt-and-suspenders on the local box before dispatching the full CI matrix.
Step 7: Manual Gate Walk (trigger-based, even in default mode)
Read the fingerprint output from Step 1.
| Trigger | Manual check (gate) | What to walk |
split-newlines | Gate 7 | Diff the changed file-reading code; verify any newline split uses /\r?\n/ not '\n' |
homedir-tmpdir | Gate 7 | Verify env-var literals use os.homedir() / os.tmpdir(), not raw process.env.HOME / /tmp |
bwrap-permissions | Gate 7 | Spell bash steps that need network declare permissionLevel: elevated |
posix-only-spell-bash | Gate 7 | Spell bash steps avoid mkdir/rm/cp; use node -e with fs/os for cross-platform file ops |
bin-scriptfiles-sync | Gate 8 | New bin/ script appears in all three scriptFiles arrays (session-start-launcher.mjs, init/moflo-init.ts, third sync site) |
helper-static-files | Gate 8 | New helpers ship as static bin/ files, not generated at runtime |
shipped-guidance-prefix | Gate 8 | New shipped guidance has moflo- prefix and lives in .claude/guidance/shipped/ |
files-glob-coverage | Gate 9 | Run npm pack --dry-run and confirm new shipped files appear in the tarball listing |
info-loss-audit | Gate 10 | For each deleted/renamed file, audit destinations bullet-by-bullet — every piece of removed content has a home |
If CHECK_MODE=true, walk all manual gates regardless of triggers (full audit). If CHECK_MODE=false, walk only triggered ones.
If the trigger set is none AND CHECK_MODE=false: skip Step 7 entirely.
Step 8: Commit & Push
Commit the version bump files:
git add package.json package-lock.json src/cli/version.ts
git commit -m "chore: bump version to <new-version>"
git push origin mainOnly commit version-related files. Do not stage unrelated changes.
Step 8.5: Dispatch release-smoke and block until green
# Capture the SHA we just pushed — release-smoke runs against this exact commit.
PUBLISH_SHA=$(git rev-parse HEAD)
# Trigger the full 3-OS × 2-harness matrix. `sha` is a required workflow input
# so the dispatched run is unambiguously bound to this commit.
gh workflow run release-smoke.yml --ref main -f sha="$PUBLISH_SHA"
# Find the dispatched run, block until it finishes, then PROVE it green.
#
# `gh run watch --exit-status` is NOT the gate. It has been observed to exit 0
# while most of the matrix was still in progress (moflo@4.12.4-rc.7 publish:
# exit 0 with 7 of 9 jobs unfinished), which would publish against an unproven
# matrix. It is used here only to block cheaply — the verdict comes from an
# explicit status/conclusion read afterwards. Same rule
# `.claude/skills/fl/phases.md` Phase 5.3b already states for
# `gh pr checks --watch`: a green exit code is not proof.
#
# The run lookup retries instead of guessing a fixed delay, and matches on
# head_sha so a concurrent dispatch (a manual UI retry from another tab) can
# never be mistaken for ours — never `--limit 1` alone.
node -e '
const { execFileSync } = require("node:child_process");
const sha = process.argv[1];
const gh = (args) => execFileSync("gh", args, { encoding: "utf8" }).trim();
// Synchronous by design: this script does nothing but wait, and a blocking
// sleep keeps the control flow linear. Do not "fix" it into setTimeout.
const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
const deadline = Date.now() + 60 * 60 * 1000;
const WATCH_TIMEOUT_MS = 10 * 60 * 1000;
let runId = "";
while (!runId && Date.now() < deadline) {
const rows = JSON.parse(gh(["run", "list", "--workflow=release-smoke.yml", "--branch", "main",
"--json", "databaseId,headSha"]));
const hit = rows.find((r) => r.headSha === sha);
if (hit) { runId = String(hit.databaseId); break; }
sleep(5000);
}
if (!runId) {
console.error("ERROR: no release-smoke run found for SHA " + sha +
". Check https://github.com/eric-cielo/moflo/actions/workflows/release-smoke.yml");
process.exit(1);
}
console.log("release-smoke run " + runId + " bound to " + sha);
for (;;) {
// Blocks while the run is live; may also return early and prematurely green.
// Capped so a stalled watch cannot outlive the deadline below — on timeout we
// simply fall through to the authoritative status read and watch again.
try {
execFileSync("gh", ["run", "watch", runId, "--exit-status"],
{ stdio: "inherit", timeout: WATCH_TIMEOUT_MS });
} catch (err) {
// Expected when the run failed (watch exits non-zero) or when the cap above
// fired. Surfaced rather than swallowed so a real fault — gh missing, auth
// expired, rate limit — is visible instead of looking like a slow run.
console.error("gh run watch: " + ((err && err.message) || err));
}
const state = JSON.parse(gh(["run", "view", runId, "--json", "status,conclusion"]));
if (state.status === "completed") {
if (state.conclusion !== "success") {
console.error("ERROR: release-smoke concluded " + state.conclusion +
" — inspect: gh run view " + runId + " --log-failed");
process.exit(1);
}
break;
}
if (Date.now() > deadline) {
console.error("ERROR: release-smoke still " + state.status + " after 60m — run " + runId);
process.exit(1);
}
sleep(15000);
}
// Every leg, not just the rollup — a skipped or cancelled job is not a pass.
const jobs = JSON.parse(gh(["run", "view", runId, "--json", "jobs"])).jobs;
const bad = jobs.filter((j) => j.conclusion !== "success");
if (bad.length > 0) {
console.error("ERROR: " + bad.length + " job(s) not success: " +
bad.map((j) => j.name + "=" + (j.conclusion || "incomplete")).join(", "));
process.exit(1);
}
console.log("release-smoke GREEN — " + jobs.length + " jobs, run " + runId);
' "$PUBLISH_SHA"release-smoke.yml runs full consumer + populated smoke on Ubuntu/macOS/Windows, plus file-sync smoke on all three filesystems. Per-PR CI is intentionally Ubuntu-only to keep recurring cost manageable — the full cross-platform matrix is paid once here, at publish time, against the exact commit we're about to publish.
Wall time expectations: typical run is ~15-20 min once caches are warm. The first dispatch after release-smoke.yml lands will have cold caches on every leg (no prior runs of this workflow exist to populate the consumer-warm and fastembed caches per-OS). Expect ~25-35 min on that first dispatch — the macOS leg is the long pole. Subsequent dispatches reuse the cache and settle to the typical ~15 min.
Never publish on gh run watch's exit code alone. The block above treats it as a cheap way to block, not as the verdict — it can return 0 with the matrix still running. The gate is the explicit status == "completed" + conclusion == "success" read, plus a per-job sweep so a cancelled or skipped leg cannot pass as green.
If the block above exits non-zero: stop immediately. It prints the run id and, on a real failure, the conclusion. Inspect the failed leg with gh run view <run-id> --log-failed, fix the underlying issue, push the fix, then re-run this step (no need to rerun Steps 0–8 — the bump commit is already on main, and the SHA-filtered lookup will pick up the new dispatched run against the same SHA only after cancel-in-progress: false lets the previous run drain). Do not proceed to npm publish until release-smoke is green for the SHA you intend to publish.
Step 9: Verify npm Authentication
npm whoamiIf 401 or "not logged in": auth token in ~/.npmrc is missing or expired. Ask the user for a valid npm publish token.
How to create a token (provide these instructions to the user if needed):
- Go to https://www.npmjs.com/settings/~/tokens
- Click "Generate New Token" → select "Granular Access Token"
- Set permissions: "Read and write" for the
moflopackage - Copy the token (starts with
npm_...)
Once the user provides the token, write it to ~/.npmrc:
echo "//registry.npmjs.org/:_authToken=<token>" > ~/.npmrcVerify with npm whoami before proceeding.
Step 10: Publish to npm
npm publish --tag <tag>- For stable releases:
npm publish(publishes tolatesttag by default) - For RC releases:
npm publish --tag rc(publishes torctag so it doesn't becomelatest)
OTP handling:
- If npm returns an OTP/one-time-password error, ask the user for their authenticator code
- Then retry with:
npm publish --otp=<code> --tag <tag> - Tip: Granular access tokens created on npmjs.com do NOT require OTP — prefer those over legacy tokens
Step 11: Verify Publication
npm view moflo version
npm view moflo dist-tagsConfirm the published version matches what we just built.
Step 12: Install Locally
npm install moflo@<new-version> --save-dev
npm install --package-lock-only --force
npm ci --dry-run --legacy-peer-depsThe first command updates package.json and package-lock.json to use the newly published version as a devDependency.
The second command (--package-lock-only --force) backfills cross-platform optional-dependency entries that npm omits from the lockfile when npm install runs on a single host platform. Without it, transitive optional deps like the nested @rolldown/binding-wasm32-wasi/node_modules/@emnapi/* entries get dropped when publishing from Windows, and the resulting lockfile fails npm ci on Ubuntu/macOS CI legs. This produced the green-release-smoke → red-ci.yml divergence in run 26487580745 (moflo@4.10.27 install commit).
The final npm ci --dry-run --legacy-peer-deps proves the resulting lockfile is in sync with package.json before we commit it. If this exits non-zero, stop and investigate — do not commit a broken lockfile.
Step 13: Final Commit
If package.json or package-lock.json changed from the install:
git add package.json package-lock.json
git commit -m "chore: install moflo@<new-version>"
git push origin mainThe chore: install moflo@<version> commit message is the anchor the fingerprint uses to bound future diffs — keep the prefix exact.
Output
Print a summary at the end:
Publish Summary
───────────────
Mode: default | --check
Version: <old> → <new>
Tag: latest | rc
Build: passed
Tests: skipped (CI-covered) | <N> files passed, <N> tests passed
Lint: skipped (CI-covered) | passed
Doctor: <N> passed, <N> warnings
Smoke (local): skipped (CI-covered) | passed
Release-smoke: green (run <id>, 3-OS × 2-harness)
Triggered gates: <list> | none
Published: moflo@<new-version>
Installed: moflo@<new-version> (devDependency)Important
- All commands run from the project root — never cd into subdirectories
- Never use
--forceon npm publish - Never install moflo globally — it is always a local devDependency
- If any step that DID run fails, stop and fix the issue before proceeding — do not skip steps
- The
prepublishOnlyscript in package.json runsnpm run buildautomatically, so npm publish will fail-fast on any TypeScript or asset-bundling error even if Step 2 had been skipped (it isn't — Step 2 always runs) - Pre-publish rules live in
.claude/guidance/internal/pre-publish-rules.md— never duplicate or paraphrase them in this skill; reference and follow
When to use --check
Use --check / -ch when:
- The PR didn't go through CI (e.g., publishing from a local-only branch)
- You're publishing a risky change (broad refactor, infrastructure surface, packaging changes)
- CI was red on something orthogonal you waived, and you want belt-and-suspenders locally
- You explicitly want to re-walk gates 7/8/10 manually regardless of trigger output
For the common case — publishing right after a merged green PR — the default mode is correct and meaningfully cheaper in tokens and time.
See Also
.claude/skills/publish/fingerprint.sh— Trigger-fingerprint script invoked by Step 1.claude/guidance/internal/pre-publish-rules.md— Authoritative gate ruleset (gates 1–10) and trigger mapdocs/BUILD.md— Step-by-step build/publish process this skill mirrors.claude/guidance/internal/dogfooding.md— Why we catch consumer-facing regressions first as our own dependencyharness/consumer-smoke/README.md— Smoke harness profiles (clean + populated) that prove a consumer install works.github/workflows/ci.yml— Lint/build/test gates this skill skips by default (ubuntu-only).github/workflows/consumer-install-smoke.yml— Per-PR ubuntu-only smoke.github/workflows/file-sync-smoke.yml— Per-PR ubuntu-only file-sync smoke.github/workflows/release-smoke.yml— Full 3-OS × 2-harness matrix this skill dispatches at Step 8.5
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

