# Changeset

> Command: changeset

- Skill: `udecode/changeset` (Agent Skill)
- Install (CLI): `npx skillmds add udecode/changeset`
- Raw SKILL.md: https://api.skillmd.com/api/skills/udecode/changeset/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: udecode (https://skillmd.com/u/udecode)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/udecode/changeset

---


# Changeset

Changesets document package changes for release. Concise bullets, imperative voice, user impact only.

**Core principle:** one action verb + one impact statement = one bullet.

## When To Use

Use when:

- Creating `.changeset/*.md` files
- Documenting package changes: feat, fix, breaking
- Updating `docs/components/changelog.mdx` for registry work

Do not use for:

- Internal docs
- Commit messages
- PR descriptions

## Critical Rules

### 1. Core packages: no `minor`

**Forbidden:** `minor` changesets for:

- `@platejs/slate`
- `@platejs/core`
- `platejs`

Use `patch` instead. `minor` on those explodes version bumps across dependents.

```yaml
# Wrong
---
"@platejs/core": minor
---

# Correct
---
"@platejs/core": patch
---
```

Only real breaking changes get `major`.

### 2. One package per file

Never combine packages in one changeset.

```bash
# Wrong
---
'@platejs/core': patch
'@platejs/utils': patch
---

# Correct
.changeset/core-fix-types.md
.changeset/utils-add-helper.md
```

### 3. Registry work is changelog work

If changes are only under `apps/www/src/registry/`, do **not** write a package changeset.

Update `docs/components/changelog.mdx` instead.

### 4. Style

Use imperative voice:

- `Add support for X`
- `Fix Y behavior`
- `Remove deprecated Z`

Do not use:

- `Added ...`
- `We fixed ...`

Keep simple changes to one line:

```md
- Fix `asChild` TypeScript error
- Add `disabled` prop to Button
```

Use code examples only when needed:

```tsx
// Before
editor.api.foo();

// After
editor.tf.foo();
```

Focus on user impact only. No implementation diary.

## Template

Simple:

```md
---
"@platejs/utils": patch
---

Fix `isEmpty` not handling void elements correctly
```

API change:

````md
---
"@platejs/core": patch
---

Rename `editor.api.foo` to `editor.tf.foo`

```tsx
// Before
editor.api.foo();

// After
editor.tf.foo();
```
````

Breaking change:

````md
---
'@platejs/basic-nodes': major
---

Remove `SkipMarkPlugin`; functionality is built into core

**Migration:** Remove `SkipMarkPlugin` from your plugin list. Configure marks directly:

```tsx
MyMarkPlugin.configure({
  rules: { selection: { affinity: 'outward' } },
});
```
````

## Red Flags

Before shipping:

- [ ] Used `minor` for `@platejs/slate`, `@platejs/core`, or `platejs`? Change to `patch`
- [ ] Multiple packages in frontmatter? Split files
- [ ] Past tense verbs? Fix them
- [ ] Multiple paragraphs? Condense
- [ ] Too much explanation? Cut it
- [ ] API change without before/after? Add one

## Registry Changelog Format

For `apps/www/src/registry` changes:

```md
### [Month Day] #[Version]
- **`component-name`**: Brief description
  - Migration note if actually needed
```

Same style rules: concise, imperative, user impact only.