dart-package-maintenance — Claude Code skill: Dart package versioning
dart-package-maintenance — a skill for maintaining Dart packages per Dart team standards: manage semantic versioning, keep CHANGELOG in sync, and prepare releases. Essential if you publish packages to pub.dev.
Apache-2.0 285 installs ★ 149 updated 2026-10-17
npx skills add kevmoo/dash_skills --skill dart-package-maintenance -a claude-codeWhat dart-package-maintenance does
This skill provides guidelines on semantic versioning for Dart packages, including rules for pre-1.0.0 versions where the second number increments for breaking changes, and for stable releases. It shows when to add a -wip suffix to pubspec.yaml and CHANGELOG.md — immediately after each release, even for minimal changes. The skill covers version selection: major for breaking changes, minor for new features, patch for fixes and dependency constraint updates.
It walks through CHANGELOG practices: record user-visible changes only, omit internal refactors and dev dependency updates, and never add entries under already-published version headings. Publishing requires removing -wip, running dart pub publish, and creating a git tag in the format v1.2.3 or package-name-v1.2.3 in monorepos. Pull request guidance includes avoiding force pushes, merging main into your branch to resolve conflicts instead of rebasing, and using gh pr checkout for local review.
What it helps with
- align package version with semantic versioning standards
- sync version numbers across pubspec.yaml and CHANGELOG.md
- prepare a package for release to pub.dev
- coordinate team contributions without history conflicts
- choose the correct version bump type for a change
Example prompts for the agent
- I added a new public method. What version should go in pubspec.yaml?
- Release this package to pub.dev: remove the -wip suffix
- Add a changelog entry for breaking changes to the API
How to install dart-package-maintenance
1Skills CLI (Vercel)
npx skills add kevmoo/dash_skills --skill dart-package-maintenance -a claude-code2Manually: put the files in place
~/.claude/skills/dart-package-maintenance/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/dart-package-maintenance/
1Skills CLI (Vercel)
npx skills add kevmoo/dash_skills --skill dart-package-maintenance -a codex2Manually: put the files in place
.agents/skills/dart-package-maintenance/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add kevmoo/dash_skills --skill dart-package-maintenance -a cursor2Manually: put the files in place
.cursor/skills/dart-package-maintenance/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install kevmoo/dash_skills skills/dart-package-maintenance2Manually: put the files in place
.github/skills/dart-package-maintenance/SKILL.md1Skills CLI (Vercel)
npx skills add kevmoo/dash_skills --skill dart-package-maintenance -a gemini-cli2Platform CLI
gemini skills install https://github.com/kevmoo/dash_skills --path skills/dart-package-maintenanceManually: put the files in place
.devin/skills/dart-package-maintenance/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add kevmoo/dash_skills --skill dart-package-maintenance -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about dart-package-maintenance
How do I install dart-package-maintenance in Claude Code?
Run npx skills add kevmoo/dash_skills --skill dart-package-maintenance -a claude-code in your terminal, then refer to ~/.claude/skills/dart-package-maintenance/SKILL.md.
What does dart-package-maintenance do?
The skill provides best practices for Dart package maintenance: semantic versioning rules, when to use -wip versions, CHANGELOG synchronization, publishing workflow, and pull request conventions aligned with Dart team guidance.
Should I use this skill for private packages with publish_to: none?
No. The skill targets packages published to pub.dev. For private packages marked publish_to: none in pubspec.yaml, these versioning and changelog guidelines do not apply.
Source text
SKILL.md · Apache-2.0
---
name: dart-package-maintenance
description: |-
Guidelines for maintaining external Dart packages, covering versioning,
publishing workflows, and pull request management. Use when updating Dart
packages, preparing for a release, or managing collaborative changes in a
repository.
key_features:
- Versioning & CHANGELOG sync
- Publishing workflow guidelines
- Pull request management
---
# Dart Package Maintenance
Guidelines for maintaining Dart packages in alignment with the canonical Dart
team
[External Package Maintenance](https://github.com/dart-lang/sdk/blob/main/docs/External-Package-Maintenance.md)
specification.
## When to use this skill
Use this skill when:
- Updating Dart packages, preparing for a release, or managing collaborative
changes in a repository.
- Managing versioning, `CHANGELOG.md` synchronization, and publishing workflows.
- Ensuring published packages comply with Dart team conventions.
### When NOT to use (Abstention Guardrails)
Do NOT apply package maintenance version bumps or changelog updates when:
- **Internal / Private Packages**: Packages marked `publish_to: none` in
`pubspec.yaml` that are not published to `pub.dev` (e.g., application root
packages or internal monorepo tooling).
- **Repository-Root Files or Historical `CHANGELOG.md` Typos**: Pull requests
that only modify repository-level files outside a published package (such as
`.github/workflows/`, repo-root `SKILL.md`, or root docs in a monorepo) or
that only fix typos/formatting in historical `CHANGELOG.md` sections.
- **In-Flight PR Commits**: Intermediate commits on an active feature branch
where the version already carries an appropriate `-wip` suffix.
## Versioning
### Semantic Versioning
Dart packages use [semantic versioning](https://semver.org) with a
[pre-`1.0.0` variation](https://dart.dev/tools/pub/dependencies#caret-syntax)
where the version numbers are shifted to the right before a `1.0.0` release; see
also the
[`package:pub_semver` semantics](https://pub.dev/packages/pub_semver#semantics):
- **Packages at `1.0.0` or later**: `major.minor.patch`.
- **Packages not yet at `1.0.0`**: `0.major.minor`, where the second number is
bumped for breaking changes, such as `0.4.2` to `0.5.0-wip`, and the third
number is bumped for non-breaking features and bug fixes, such as `0.4.2` to
`0.4.3-wip`. Avoid `+1` build suffixes (in `package:pub_semver`, `0.4.2+1-wip`
parses `+1-wip` as build metadata rather than a `-wip` pre-release).
- **Recommendation**: Aim to publish `1.0.0` as soon as the package is stable.
Choose the version bump based on the impact of the change:
- **Major**: Breaking changes, including removing or renaming a `pubspec.yaml`
`executables` entry.
- **Minor**: New features and non-breaking API changes, such as introducing a
new class or adding a `pubspec.yaml` `executables` entry.
- **Patch**: Bug fixes, minimum `environment.sdk` or runtime `dependencies`
constraint updates, or any other change that does not impact calling code.
### Updating the Version
Whenever the code in the repo differs from the latest version published on
`pub.dev`, both `pubspec.yaml` and `CHANGELOG.md` must use a `-wip` version. We
bump to `-wip` on the _first_ change after a release, even if we don't plan on
publishing the code in that state or if the change doesn't impact consumers.
When opening or merging a PR, check the current version in `pubspec.yaml` and
`CHANGELOG.md`:
- **Currently at a published version**, such as `1.2.3`: Perform the appropriate
version bump, append `-wip` in `pubspec.yaml`, and add a matching
`## <version>-wip` section at the top of `CHANGELOG.md`.
- **Already at a `-wip` version**, such as `1.2.4-wip`: Compare the existing
`-wip` bump against the bump required for your change. If your change requires
a larger bump, such as from a _patch_ bump to a _minor_ bump when adding a
feature, update `pubspec.yaml` and rename the existing `## <version>-wip`
heading in `CHANGELOG.md` in place.
- **Not yet published to `pub.dev`**, at `0.1.0-wip`: Keep `0.1.0-wip` and the
`- Initial release.` entry without adding per-PR changelog entries until after
the first release.
### Updating `CHANGELOG.md`
- **User-visible changes**: Add an entry under the top `-wip` section.
- **Internal or non-user-visible changes**, such as safe refactorings, lint
cleanups, `test/`, `tool/`, or `README.md` updates, or `dev_dependencies` and
`dependency_overrides` changes:
- If your PR creates the new `-wip` section, add the `## <version>-wip`
heading with no bullet items below it.
- If the package is already at a `-wip` version, leave `CHANGELOG.md`
untouched and apply the `skip-changelog-check` PR label.
- **Follow-up edits to unreleased work**: If a subsequent PR modifies or reverts
an unreleased change in the current `-wip` section, such as bumping an SDK or
dependency constraint again before publishing, update or remove the existing
`-wip` bullet in place instead of adding a duplicate entry.
- **Already-published sections**: Never add new entries under an
already-published version heading, especially after merging `main` when a
release landed while your PR was open.
### Breaking Changes
- Evaluate the impact on dependent packages and internal projects.
- Consider running changes through internal presubmits if possible.
- Prefer incremental rollouts (e.g., new behavior as opt-in) to minimize
downstream breakage.
## Publishing Process
1. **Preparation**: Remove the `-wip` suffix from `pubspec.yaml` and
`CHANGELOG.md` in a dedicated pull request.
2. **Execution**: Run `dart pub publish` (or `flutter pub publish`) and resolve
all warnings and errors.
3. **Tagging**: Create and push a git tag for the published version:
- For single-package repos: `v1.2.3`
- For monorepos: `package_name-v1.2.3`
- Example: `git tag v1.2.3 && git push --tags`
## Pull Request Management
- **Commits**: Each PR should generally correspond to a single squashed commit
upon merging.
- **Shared History**: Once a PR is open, avoid force pushing to the branch.
- **Conflict Resolution**: Prefer merging `main` into the PR branch rather than
rebasing to resolve conflicts. This preserves the review history and comments.
- **Reviewing**: Add comments from the "Files changed" view to batch them.
- **Local Inspection**: Use `gh pr checkout <number>` to inspect changes locally
in your IDE.
© kevmoo · Apache-2.0 · kevmoo/dash_skills