tuanductran Changeset
Purpose
Use this skill whenever a pull request introduces user-visible changes that should be included in the next release of the hr-skills repository.
A changeset records release notes, determines semantic version bumps, and drives CHANGELOG.md generation through Changesets.
Do not create a changeset for internal-only work that has no effect on repository users.
Decision Process
Before creating a changeset, inspect the pull request and classify the changes.
A changeset is required
Create a changeset for changes such as:
- New skills.
- New prompts.
- New examples.
- New generators.
- New validators.
- New build capabilities.
- New CLI functionality.
- Bug fixes affecting repository behavior.
- User-visible documentation improvements that change repository capabilities.
- Any change that should appear in release notes.
A changeset is usually not required
Do not create a changeset for work such as:
- Typo fixes.
- Markdown formatting.
- README wording improvements.
- Internal refactoring.
- Code movement without behavior changes.
- Test-only changes.
- CI configuration updates that do not affect released functionality.
- Comments or cleanup work.
When uncertain, prefer consistency with previous releases and existing changesets in the repository.
Create a Changeset
Generate a new changeset:
bun run changeset
Follow the interactive prompts or edit the generated file inside:
.changeset/
A typical file looks like:
---
"hr-skills": patch
---
Added support for validating duplicate skill names during repository validation.
Do not modify the YAML frontmatter format.
Use the exact package name defined by the repository.
Choose the Correct Version Bump
patch
Use for backward-compatible fixes and small improvements.
Examples:
- Bug fixes.
- Prompt improvements.
- Example improvements.
- Validator fixes.
- Tooling corrections.
- Content corrections.
- Small enhancements that do not introduce new functionality.
minor
Use for new functionality that is backward compatible.
Examples:
- New skill.
- New prompt library.
- New examples.
- New validator.
- New CLI command.
- New build capability.
- New repository feature.
major
Use for breaking changes.
Examples:
- Breaking changes to SKILL.md format.
- Breaking package API changes.
- Folder layout changes requiring migration.
- Removed repository functionality.
- Incompatible validator behavior.
- Repository architecture changes requiring user action.
Writing Guidelines
A good changeset explains what changed and why it matters, not how it was implemented.
General Rules
- Focus on user-visible outcomes.
- Write concise release notes.
- Prefer one to three short sentences.
- Use clear, direct language.
- End every sentence with a period.
- Keep descriptions suitable for inclusion in
CHANGELOG.md.
Use Past Tense
Describe completed work using past tense.
Examples:
Added a new HR analytics skill.
Fixed duplicate validation logic.
Updated the onboarding examples.
Describe Outcomes
Prefer:
Added validation for duplicate skill names.
Instead of:
Modified validator.ts.
Release notes should describe the effect of the change, not the implementation details.
New Skills
Example:
Added a new `hr-virtual-onboarding` skill covering remote onboarding workflows, manager checklists, and AI-assisted onboarding prompts.
Bug Fixes
When appropriate, reference the GitHub issue.
Example:
Fixed #42 by correcting turnover calculation guidance in the HR analytics content.
Tooling
Example:
Updated repository validation to require prompts and examples for Full-tier skills.
Avoid
Do not:
- Copy commit messages.
- List every modified file.
- Describe internal refactoring.
- Include implementation details.
- Repeat repository structure.
- Write long release notes.
- Add Markdown headings inside the description except
####or lower if absolutely necessary.
Validation Checklist
Before finishing:
- Verify a changeset is actually required.
- Verify the selected version bump is correct.
- Verify the package name is correct.
- Verify the description is concise and user-facing.
- Verify Markdown formatting.
- Verify the generated file is located inside
.changeset/.
Do not edit generated changelog files manually.
References
AGENTS.mdREADME.mddocs/engineering/format.md.changeset/CHANGELOG.md- Changesets documentation: https://github.com/changesets/changesets/tree/main/docs
- Conventional Commits: https://www.conventionalcommits.org/