{"id":"3b65fd27-8918-40f5-963f-4881b7ded3b7","shortId":"dYx5gx","kind":"skill","title":"bump-release","tagline":"This skill should be used when the user asks to \"bump release\", \"cut a release\", \"tag a release\", \"bump version\", \"create a new release\", or mentions release versioning, changelog updates, or version tagging workflows.","description":"# Bump Release\n\nSupport for both regular and beta releases.\n\n## Parameters\n\n- `version`: Optional explicit version to use (e.g., `2.0.0`). When provided, skips automatic version inference\n- `--beta`: Create a beta release with `-beta.X` suffix\n- `--dry-run`: Preview the release without making any changes (no file modifications, commits, or tags)\n\n## Steps\n\n0. **Locate the package** - The user may be in a monorepo where the package to release lives in a subdirectory. Look for `package.json` in the current working directory first; if not found, ask which package to release. All file paths (`CHANGELOG.md`, `package.json`, `justfile`) are relative to the package directory.\n1. Update the `CHANGELOG.md` file with all changes since the last version release (**skip this step for beta releases**).\n2. Bump the version in `package.json`:\n   - **Regular release**: Follow semantic versioning (e.g., 1.2.3)\n   - **Beta release**: Add `-beta.X` suffix (e.g., 1.2.3-beta.1)\n3. **Format files** - If a `justfile` exists in the repository, run `just full-write` to ensure `CHANGELOG.md` and `package.json` are properly formatted\n4. Commit the changes with a message like \"docs: release <version>\"\n5. Create a new git tag by running `git tag -a v<version> -m \"<version>\"`\n\n**Note**: When `--dry-run` flag is provided, display what would be done without making any actual changes to files, creating commits, or tags.\n\n## Tasks\n\n## Process\n\n1. **Check for arguments** - Determine if `version` was provided, if this is a beta release (`--beta`), and/or dry-run (`--dry-run`)\n2. **Check for clean working tree** - Run `git status --porcelain` to verify there are no uncommitted changes unrelated to this release. If there are, run the `commit` skill to commit them before proceeding\n3. **Write Changelog** - Examine diffs between the current branch and the previous tag to write Changelog. Then find\n   relevant PRs by looking at the commit history and add them to each changelog (when available). If `package.json` contains\n   a `files` field, only include changes within those specified files/directories. If no `files` field exists, include all\n   changes except test changes, CI/CD workflows, and development tooling\n4. **Follow format** - Consult `references/common-changelog.md` for the Common Changelog specification\n5. **Check version** - Get current version from `package.json`\n6. **Bump version** - If `version` argument provided, use it directly. Otherwise, if unchanged since last release, increment per Semantic Versioning rules:\n   - **For regular releases**:\n     - **PATCH** (x.x.X) - Bug fixes, documentation updates\n     - **MINOR** (x.X.x) - New features, backward-compatible changes\n     - **MAJOR** (X.x.x) - Breaking changes\n   - **For beta releases** (`--beta` flag):\n     - If current version has no beta suffix: Add `-beta.1` to the version\n     - If current version already has beta suffix: Increment beta number (e.g., `-beta.1` → `-beta.2`)\n     - If moving from beta to release: Remove beta suffix and use the base version\n   - **When unsure** — If the changes are ambiguous (e.g., a new feature that may also break consumers, or a mix of fixes and features), use `AskUserQuestion` to let the user decide the semver level:\n\n     - header: \"Version\"\n     - question: \"Changes include both `<summary>`. Which release level?\"\n     - options: list the plausible semver levels with their resulting version (e.g., \"1.3.0 (minor)\", \"2.0.0 (major)\")\n     - multiSelect: false\n\n     Use the user's choice and skip step 7\n7. **Confirm version** - When the version was confidently inferred (no explicit `version` argument), use `AskUserQuestion` to confirm before proceeding:\n\n   - header: \"Version\"\n   - question: \"Release `<current>` → `<inferred>`?\"\n   - options:\n     - The inferred version label (e.g., \"1.3.0 (minor)\") — mark as \"(Recommended)\"\n     - One alternative that is one semver level higher (e.g., \"2.0.0 (major)\")\n     - One alternative that is one semver level lower when possible (e.g., \"1.2.4 (patch)\")\n   - multiSelect: false\n\n   If the user picks an alternative, use that version for the remaining steps. Skip this step when `--dry-run` is active (show the inferred version in the preview instead)\n\n## Beta Release Logic\n\nWhen `--beta` flag is provided in the $ARGUMENTS\n\n1. **Check for explicit version** - If `version` provided:\n   - If version already has beta suffix → use as-is\n   - If version has no beta suffix → append `-beta.1`\n2. **Otherwise, parse current version** from `package.json` and **determine beta version**:\n   - If current version is `1.2.3`: Create `1.2.4-beta.1` (increment patch + beta.1)\n   - If current version is `1.2.3-beta.1`: Create `1.2.3-beta.2` (increment beta number)\n   - If current version is `1.2.3-beta.5`: Create `1.2.3-beta.6` (increment beta number)\n3. **Skip CHANGELOG.md update** - Beta releases don't update the changelog\n4. **Commit and tag** with beta version (e.g., `v1.2.4-beta.1`)\n\n## Output\n\nFor regular releases only, generate changelog entries in `CHANGELOG.md` following the format and writing guidelines in `references/common-changelog.md`. Use the `Changed`, `Added`, `Removed`, `Fixed` categories (in that order). Every entry must begin with a present-tense verb in imperative mood.\n\n## Inclusion Criteria\n\nFor regular releases only (changelog generation is skipped for beta releases):\n\n- **Files field constraint** - If `package.json` contains a `files` field, only include changes to files/directories specified in that array. All other codebase changes should be excluded from the CHANGELOG\n- **Production changes only** - When no `files` field exists, exclude test changes, CI/CD workflows, and development tooling\n- **Reference pull requests** - Link to PRs when available for context\n- **Net changes only** - Examine diffs between the current branch and the previous tag to identify changes\n- **Only dependencies and peerDependencies changes** - Exclude changes to devDependencies\n\n## Examples\n\n### Regular Release\n\n```bash\n# Create a regular patch/minor/major release\n/bump-release\n\n# Preview what a regular release would do\n/bump-release --dry-run\n```\n\n### Beta Release\n\n```bash\n# Create a beta release with -beta.X suffix\n/bump-release --beta\n\n# Preview what a beta release would do\n/bump-release --beta --dry-run\n```\n\n### Explicit Version\n\n```bash\n# Specify exact version\n/bump-release 2.0.0\n\n# Specify exact beta version\n/bump-release 2.0.0-beta.1\n\n# Combine with flags\n/bump-release 2.0.0 --dry-run\n```\n\n## Version Examples\n\n| Current Version | Release Type   | New Version     |\n| --------------- | -------------- | --------------- |\n| `1.2.3`         | Regular        | `1.2.4` (patch) |\n| `1.2.3`         | Beta           | `1.2.4-beta.1`  |\n| `1.2.3-beta.1`  | Beta           | `1.2.3-beta.2`  |\n| `1.2.3-beta.5`  | Regular        | `1.2.3`         |\n| `1.2.3`         | `2.0.0`        | `2.0.0`         |\n| `1.2.3`         | `2.0.0` + Beta | `2.0.0-beta.1`  |\n\n## Resources\n\n- `references/common-changelog.md` — Common Changelog format and writing guidelines","tags":["bump","release","agent","skills","paulrberg","agent-skills","ai-agents"],"capabilities":["skill","source-paulrberg","skill-bump-release","topic-agent-skills","topic-ai-agents"],"categories":["agent-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/PaulRBerg/agent-skills/bump-release","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add PaulRBerg/agent-skills","source_repo":"https://github.com/PaulRBerg/agent-skills","install_from":"skills.sh"}},"qualityScore":"0.475","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 50 github stars · SKILL.md body (7,061 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T00:56:17.226Z","embedding":null,"createdAt":"2026-04-18T22:17:34.423Z","updatedAt":"2026-04-22T00:56:17.226Z","lastSeenAt":"2026-04-22T00:56:17.226Z","tsv":"'/bump-release':874,882,896,905,916,922,928 '0':87 '1':136,248,640 '1.2.3':167,174,681,692,695,704,707,941,945,949,952,954,957,958,961 '1.2.4':595,683,943,947 '1.3.0':524,568 '2':155,271,666 '2.0.0':55,526,582,917,923,929,959,960,962,964 '3':176,304,712 '4':199,367,723 '5':209,377 '6':385 '7':538,539 'activ':620 'actual':238 'ad':753 'add':170,331,439 'alreadi':447,650 'also':484 'altern':574,585,604 'ambigu':477 'and/or':264 'append':664 'argument':251,390,551,639 'array':803 'as-i':655 'ask':12,119 'askuserquest':495,553 'automat':59 'avail':337,837 'backward':420 'backward-compat':419 'base':469 'bash':868,888,912 'begin':763 'beta':45,62,65,153,168,261,263,428,430,437,449,452,460,464,629,633,652,662,675,698,710,716,728,784,886,891,897,901,906,920,946,951,963 'beta.1':175,440,455,665,684,687,693,924,948,950,965 'beta.2':456,696,953 'beta.5':705,955 'beta.6':708 'beta.x':68,171,894 'branch':312,848 'break':425,485 'bug':411 'bump':2,14,22,38,156,386 'bump-releas':1 'categori':756 'chang':79,143,202,239,287,346,358,361,422,426,475,507,752,797,807,815,824,841,855,860,862 'changelog':32,306,319,335,375,722,738,779,813,969 'changelog.md':127,139,193,714,741 'check':249,272,378,641 'choic':534 'ci/cd':362,825 'clean':274 'codebas':806 'combin':925 'commit':83,200,243,297,300,328,724 'common':374,968 'compat':421 'confid':546 'confirm':540,555 'constraint':788 'consult':370 'consum':486 'contain':340,791 'context':839 'creat':24,63,210,242,682,694,706,869,889 'criteria':774 'current':112,311,381,433,445,669,678,689,701,847,935 'cut':16 'decid':500 'depend':857 'determin':252,674 'devdepend':864 'develop':365,828 'diff':308,844 'direct':394 'directori':114,135 'display':230 'doc':207 'document':413 'done':234 'dri':71,225,266,269,617,884,908,931 'dry-run':70,224,265,268,616,883,907,930 'e.g':54,166,173,454,478,523,567,581,594,730 'ensur':192 'entri':739,761 'everi':760 'exact':914,919 'examin':307,843 'exampl':865,934 'except':359 'exclud':810,822,861 'exist':182,355,821 'explicit':50,549,643,910 'fals':529,598 'featur':418,481,493 'field':343,354,787,794,820 'file':81,125,140,178,241,342,353,786,793,819 'files/directories':350,799 'find':321 'first':115 'fix':412,491,755 'flag':227,431,634,927 'follow':163,368,742 'format':177,198,369,744,970 'found':118 'full':189 'full-writ':188 'generat':737,780 'get':380 'git':213,217,278 'guidelin':747,973 'header':504,558 'higher':580 'histori':329 'identifi':854 'imper':771 'includ':345,356,508,796 'inclus':773 'increment':401,451,685,697,709 'infer':61,547,564,623 'instead':628 'justfil':129,181 'label':566 'last':146,399 'let':497 'level':503,512,518,579,590 'like':206 'link':833 'list':514 'live':103 'locat':88 'logic':631 'look':107,325 'lower':591 'm':221 'major':423,527,583 'make':77,236 'mark':570 'may':93,483 'mention':29 'messag':205 'minor':415,525,569 'mix':489 'modif':82 'monorepo':97 'mood':772 'move':458 'multiselect':528,597 'must':762 'net':840 'new':26,212,417,480,939 'note':222 'number':453,699,711 'one':573,577,584,588 'option':49,513,562 'order':759 'otherwis':395,667 'output':732 'packag':90,100,121,134 'package.json':109,128,160,195,339,384,672,790 'paramet':47 'pars':668 'patch':409,596,686,944 'patch/minor/major':872 'path':126 'peerdepend':859 'per':402 'pick':602 'plausibl':516 'porcelain':280 'possibl':593 'present':767 'present-tens':766 'preview':73,627,875,898 'previous':315,851 'proceed':303,557 'process':247 'product':814 'proper':197 'provid':57,229,256,391,636,647 'prs':323,835 'pull':831 'question':506,560 'recommend':572 'refer':830 'references/common-changelog.md':371,749,967 'regular':43,161,407,734,776,866,871,878,942,956 'relat':131 'releas':3,15,18,21,27,30,39,46,66,75,102,123,148,154,162,169,208,262,291,400,408,429,462,511,561,630,717,735,777,785,867,873,879,887,892,902,937 'relev':322 'remain':610 'remov':463,754 'repositori':185 'request':832 'resourc':966 'result':521 'rule':405 'run':72,186,216,226,267,270,277,295,618,885,909,932 'semant':164,403 'semver':502,517,578,589 'show':621 'sinc':144,398 'skill':5,298 'skill-bump-release' 'skip':58,149,536,612,713,782 'source-paulrberg' 'specif':376 'specifi':349,800,913,918 'status':279 'step':86,151,537,611,614 'subdirectori':106 'suffix':69,172,438,450,465,653,663,895 'support':40 'tag':19,36,85,214,218,245,316,726,852 'task':246 'tens':768 'test':360,823 'tool':366,829 'topic-agent-skills' 'topic-ai-agents' 'tree':276 'type':938 'unchang':397 'uncommit':286 'unrel':288 'unsur':472 'updat':33,137,414,715,720 'use':8,53,392,467,494,530,552,605,654,750 'user':11,92,499,532,601 'v':220 'v1.2.4-beta.1':731 'verb':769 'verifi':282 'version':23,31,35,48,51,60,147,158,165,254,379,382,387,389,404,434,443,446,470,505,522,541,544,550,559,565,607,624,644,646,649,659,670,676,679,690,702,729,911,915,921,933,936,940 'within':347 'without':76,235 'work':113,275 'workflow':37,363,826 'would':232,880,903 'write':190,305,318,746,972 'x.x.x':410,416,424","prices":[{"id":"34521b32-cfec-47e8-9335-8d87eb30277e","listingId":"3b65fd27-8918-40f5-963f-4881b7ded3b7","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"PaulRBerg","category":"agent-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:17:34.423Z"}],"sources":[{"listingId":"3b65fd27-8918-40f5-963f-4881b7ded3b7","source":"github","sourceId":"PaulRBerg/agent-skills/bump-release","sourceUrl":"https://github.com/PaulRBerg/agent-skills/tree/main/skills/bump-release","isPrimary":false,"firstSeenAt":"2026-04-18T22:17:34.423Z","lastSeenAt":"2026-04-22T00:56:17.226Z"}],"details":{"listingId":"3b65fd27-8918-40f5-963f-4881b7ded3b7","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"PaulRBerg","slug":"bump-release","github":{"repo":"PaulRBerg/agent-skills","stars":50,"topics":["agent-skills","ai-agents"],"license":"mit","html_url":"https://github.com/PaulRBerg/agent-skills","pushed_at":"2026-04-20T16:22:56Z","description":"PRB's collection of agent skills","skill_md_sha":"426f3b84b194d4955c6ab38359237bafa3926494","skill_md_path":"skills/bump-release/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/PaulRBerg/agent-skills/tree/main/skills/bump-release"},"layout":"multi","source":"github","category":"agent-skills","frontmatter":{"name":"bump-release","description":"This skill should be used when the user asks to \"bump release\", \"cut a release\", \"tag a release\", \"bump version\", \"create a new release\", or mentions release versioning, changelog updates, or version tagging workflows."},"skills_sh_url":"https://skills.sh/PaulRBerg/agent-skills/bump-release"},"updatedAt":"2026-04-22T00:56:17.226Z"}}