dsh-create-upgrade-guidelisted
Install: claude install-skill SOYL-AI/soyl-skills-hub
# DSH Create Upgrade Guide
An upgrade guide tells a reader who runs release vT what to change to run the next release. Write it in the change that introduces the break, as soon as the break is recognized; do not defer it to release preparation.
## Scope
Write a guide only for breaks that someone outside the repository can observe after upgrading:
- `dsh` commands, flags, and profile names;
- `cordis.yml`, patch, overlay, and settings keys or their accepted values;
- persisted user data: Session logs, SQLite stores, and user data directories;
- TypeScript and Python SDK exports, JSON-RPC, HTTP, and ACP messages;
- published package names and entry points.
Pre-stable internal APIs whose consumers are all updated in the same change need no guide. A Session-format change still follows [type acknowledgements](../../../docs/cookbook/reviewing-persistence-type-changes.md); its guide states only the reader's actions and links that record.
## Location
`docs/upgrade-guide/v<version>/<item>/guide.md`
- `<version>` is the `version` field of the root `package.json` when you write the guide, for example `v0.1.7-rc.2`. The guide describes the upgrade from that release to the next one.
- `<item>` is a kebab-case name of the changed surface, for example `profile-flag-rename`.
- Each item directory holds exactly `guide.md`, its Chinese counterpart `guide.zh.md`, and the pairing record `guide.i18n.yaml`: no index, no attachments.
## Maintenance
While the root version is unchanged, the