agentleFS
petarzarkovpetarzarkov/dunx/.claude/skills/release/SKILL.md

release

Skill93 starsChanged 4 months agoMITView on GitHub

Version and publish @dunx/* packages to npm. Use when cutting a release, when a publish failed or a package is missing from npm, when a package needs its first npm version, or when touching scripts/version.ts, the pinned npm version, or the publish job in ci.yml.

  • Reads credentials

193 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use create-agent-adapter, changelog-style 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.
  • MicrosoftSkill

    create-agent-adapter

    Technical guide for creating a new Paperclip agent adapter. Use when building a new adapter package, adding support for a new AI coding tool (e.g. a new CLI agent, API-based agent, or custom process), or when modifying the adapter system. Covers the required interfaces, module structure, registration points, and conventions derived from the existing claude-local and codex-local adapters.

    Also in 5 projects that use this

  • GrinvSkill

    changelog-style

    Turn a commit range into CHANGELOG.md entries following common-changelog style. Use when finishing a PR or cutting a release, to write/fix the [Unreleased] section's entries — moving [Unreleased] under a new dated version heading is a separate, automated step (see the release skill / scripts/sync-version.ts), not this skill's job.

    Also in 4 projects that use this

  • GrinvSkill

    docs-consistency-check

    Check README/manifest.json/server.json/CHANGELOG.md/AGENTS.md and docs/*.md for drift against the actual registered tools and source. Use after adding, renaming, or removing a tool, or as part of a live-audit pass.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    component-release

    Prepares a verifiable Agent Landing Zone UI release. Use for release branches, VERSION, changelog entries, tags, release notes, and compatibility evidence; never publish without explicit human approval.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    documentation-consistency

    Keeps AI Landing Zone contributor, user, and operator documentation aligned with shipped Bicep behavior. Use for parameters, defaults, outputs, topology, deployment flow, operations, or releases.

    Also in 8 projects that use this

  • rivet-devSkill

    launch-graphics

    Generate agentOS marketing/launch graphics (launch & social heroes, code-snippet cards) from the committed generators in docs-internal/graphics. Use when asked to make, update, or render an agentOS launch image, social image, "agentOS Apps" graphic, or technical code-snippet image.

    Also in 3 projects that use this

  • +3 more from Grinv

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 183 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run the publish-guard agent over the changed packages.

    line 26
  2. Distinctive:

    Commit the release trigger and push to main:

    line 29
  3. Very specific:

    After the version commit is pushed, scripts/github-release.ts tags v<version> and creates the GitHub release.

    line 74
  4. Very specific:

    Do not add NPM_TOKEN, a second publishing workflow, or npm calls outside scripts/publish.ts.

    line 135

“Common” is measured: kept by at least 6 in 10 of the 183 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/release

Releases are lockstep: every @dunx/* package shares one version and ships together, even the ones a release did not touch. Change detection decides whether to release, never what. The reason is a correctness one - a published range names a concrete version of @dunx/core, so independent versions would let an app end up with two copies of it, and in this container a token is a class object. Full reasoning: architecture/packaging.md, "Versioning is lockstep".

Do not make versions independent again without also solving the duplicate-core problem - see that section for the two alternatives and why each was rejected.

CI runs bun run version on every push to main, and it publishes nothing unless the head commit is a release commit. Ordinary merges run the checks and deploy the docs. This skill is for cutting a release deliberately, and for the failure modes.

Cutting a release

  1. /ci-check - build, lint, typecheck, test. A failed build publishes nothing, but a passing build with broken dist/ publishes broken.
  2. Run the publish-guard agent over the changed packages.
  3. bun run version:dry-run - on a non-release commit this reports that it would skip. It prints the computed bump, the commits it read, and the changed packages.
  4. Commit the release trigger and push to main:

    SubjectBump
    release: <summary>derived from every commit since the last release
    release(major|minor|patch): <summary>stated outright
    release!: <summary>major

    The trigger is matched on the subject only, so a body quoting the word does not publish.

The bump and the changed-package detection both span every commit back to the previous chore(release): bump version to ... marker. That marker is RELEASE_COMMIT_PREFIX in scripts/bump.ts, written by pushVersionCommit in scripts/version.ts - if you change one, change both, or every range becomes "all of history". CI's fetch-depth: 0 is load-bearing for the same reason: a shallow checkout cannot see the marker and silently under-reports the bump to a patch.

Force every package to publish regardless of computed bumps by putting [force-publish] in the commit message. That path bypasses the release gate, and writes no changelog entry: it has no range to describe.

The changelog

Each release prepends a section to the root CHANGELOG.md, from the same commit range the bump was derived from. scripts/changelog.ts owns the format in both directions - renderRelease writes a section, parseChangelog reads them back - and internal/docs renders them at #/releases. Nothing is hand-written.

  • The release: commit's own prose becomes the section's summary, so that subject is the release note. A release whose whole range is that one commit still gets a section.
  • Commits group by conventional type; an unrecognised one lands under "Other changes" rather than being dropped.
  • The generator escapes < and replaces em and en dashes, so a subject written before those rules existed cannot fail no-em-dash.test.ts or lose a type parameter to raw HTML.
  • The docs site is built after the release step in ci.yml, so the deployed artifact carries the section this release just wrote. The release commit is [skip ci], so building it earlier would leave the page a release behind.
  • Re-running a failed release does not duplicate a section: a version already present is left alone.

The tag and the GitHub release

After the version commit is pushed, scripts/github-release.ts tags v<version> and creates the GitHub release. Before this existed, git tag -l was empty across every release and the repo's Releases page held nothing.

  • The notes are read back from CHANGELOG.md by parseChangelog, not re-rendered from the commit range. A second renderer is how the tag, the file and the site would come to disagree about what shipped.
  • The body ends with a link to #/releases/<version>, which internal/docs serves as a page per release. The URL is derived from owner/repo, so a fork points at its own Pages site.
  • The API call is fetch against the REST API, not the gh CLI: nothing else in scripts/ needs gh, and fetch is native. It needs contents: write, which ci.yml's publishing job already had.
  • Neither step throws and neither fails the job. By the time they run the packages are on npm, so a failure here would make a finished publish look broken. Both are idempotent: an existing tag or release is left alone, so a rerun after a partial failure is safe.
  • A missing GITHUB_TOKEN skips the release and says so, which is what a local bun run version does.
  • [force-publish] gets no tag and no release. It bypasses the release gate and writes no changelog section, so there is no range to describe.

Constraints that are load-bearing

  • Trusted publishing (OIDC), no NPM_TOKEN. Each package's trusted publisher on npmjs.com is pinned to the workflow filename ci.yml. Renaming that file silently breaks publishing for every package. ci.yml is the only workflow permitted to publish.
  • npm is the one sanctioned non-bun tool, only inside scripts/publish.ts: bun publish cannot authenticate via OIDC (oven-sh/bun#15601). It runs as bunx npm@<pinned> - the NPM constant, currently bunx npm@11.10.1. Bun executes npm on its own runtime, so CI needs no setup-node. The pin must stay >= 11.5.1; ubuntu-latest still ships npm 10.x, so the pin is doing real work. Bump the constant to upgrade.
  • workspace: ranges. npm publish does not expand them, so the publish path rewrites them to concrete ranges around the publish and restores package.json afterwards. The policy is one function, resolveWorkspaceRange in scripts/workspace-ranges.ts, shared by publish.ts and first-publish.ts because a second copy of it is how the two would drift: workspace:* publishes as ^<version>, not as an exact pin. Every internal range is a peerDependency, and an exact peer accepts one version and nothing else, so a consumer whose core resolved one patch ahead gets an ERESOLVE from npm or a nested second copy of core. The caret's pre-1.0 limit (^0.2.0 excludes 0.3.0) is why versioning stays lockstep, not a reason to go back to exact - exact excludes 0.2.1 as well. If a publish dies mid-run, check git diff for a package manifest left with concrete ranges where workspace:* belongs.
  • --provenance only under GITHUB_ACTIONS. It errors anywhere else, which would break a manual publish.

Failure modes

SymptomCause
First publish of a new package fails in CIA package with no versions on npm has no trusted-publisher settings page yet. Run bunx npm@11.10.1 login then bun scripts/first-publish.ts - not a bare npm publish, which ships workspace:* verbatim and breaks every consumer install.
dist-tag, deprecate, access fail in CIOnly npm publish can use the OIDC credential. Run these locally against a personal npm login.
Published tarball contains src/ or test filesMissing or wrong files in the manifest. publish-guard catches this.
Consumer on node16/nodenext cannot resolveAn extensionless relative specifier reached the emitted .d.ts. Every relative import in source needs a .js extension.
CI publishes nothing and reports successNo version changed. Expected - check the dry-run output.

Never

Do not add NPM_TOKEN, a second publishing workflow, or npm calls outside scripts/publish.ts. Do not hand-edit CHANGELOG.md: the next release rewrites the file around whatever is there, and the site renders what the script wrote.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.