AGENT SKILL

dsh-create-upgrade-guide

Use when a deepseek-harness change breaks an externally perceptible surface (CLI, profiles, cordis.yml or settings keys, persisted user data, SDK or wire APIs, published package entry points), or when changing a surface that an unreleased upgrade guide already covers, to write or update docs/upgrade-guide/v<version>/<item>/guide.md.

License 许可
MIT
最近更新
2026-10-03
Stars
★ 19
Forks
1

01 前言 Front Matter

name
dsh-create-upgrade-guide
description
Use when a deepseek-harness change breaks an externally perceptible surface (CLI, profiles, cordis.yml or settings keys, persisted user data, SDK or wire APIs, published package entry points), or when changing a surface that an unreleased upgrade guide already covers, to write or update docs/upgrade-guide/v<version>/<item>/guide.md.

03 SKILL.md 正文

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; 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 current version directory describes the delta from vT to current master. When a later change touches a surface a guide there covers, update that guide in the same change; delete the guide when the break is reverted. After the version bump, guides in older version directories are frozen; a new break goes into the new version directory. Never write a guide spanning more than one release.

Format

Start from the upgrade-guide template. verify-upgrade-guides enforces:

  • frontmatter with exactly kind: upgrade-guide and a one-sentence description naming what breaks; add a key only together with its gate check, then backfill every guide;
  • one # title, then exactly the ## Change and ## Migration sections in guide.md, and ## 变更 and ## 迁移 in guide.zh.md, in that order;
  • at most 500 words in guide.md, frontmatter included.

Change states the old and new behavior of the surface and who is affected. Migration lists ordered steps that name exact files, keys, commands, or symbols, and states how to confirm the migration worked.

When a guide needs more than 500 words, the extra text belongs elsewhere: link source files or symbols instead of restating code, move rationale into an Agent Note, and turn repeated mechanical steps into a script or dsh command that the guide invokes.

Follow dsh-prose-standard. Write the Chinese counterpart in the same change under the bilingual pairing rules, then record the pair with pnpm run verify-translation-pairing --write docs/upgrade-guide/v<version>/<item>/guide.md.

Verify

pnpm run verify-upgrade-guides
pnpm run verify-translation-pairing docs/upgrade-guide/v<version>/<item>/guide.md
pnpm run verify-md-links

04 同仓库更多 Skills

Leostrange
Leostrange/DeepSeek-Harness-Desktop-RU

user-only-skill

Prove model-disabled skills stay outside the model catalog.

★ 19
Leostrange
Leostrange/DeepSeek-Harness-Desktop-RU

snapshot-skill

Exercise project skill discovery and loading in snapshot tests.

★ 19
Leostrange
Leostrange/DeepSeek-Harness-Desktop-RU

model-only-skill

Prove user-disabled skills remain available to the model.

★ 19
Leostrange
Leostrange/DeepSeek-Harness-Desktop-RU

office-xlsx

Read, create, and modify Excel workbooks (.xlsx), including data, formulas, formatting, and pandas analysis. Use for Excel inputs or deliverables. Load before running Office commands. Data and formula tasks skip visual inspection; inspect only for formatting or layout needs. Use only bundled LibreOffice unless the user explicitly opts out; without that opt-out, do not search for another LibreOffice executable.

★ 19
Leostrange
Leostrange/DeepSeek-Harness-Desktop-RU

office-pptx

Create, read, edit, and check PowerPoint presentations (.pptx), including slide text, tables, images, and charts. Use when a PPTX file is an input or requested deliverable. Load this skill before running Office commands. Use only bundled LibreOffice unless the user explicitly opts out; without that opt-out, do not search for another LibreOffice executable.

★ 19
Leostrange
Leostrange/DeepSeek-Harness-Desktop-RU

office-docx

Create, read, edit, and check Word documents (.docx), including reports, letters, and formatted tables. Use when a DOCX file is an input or requested deliverable. Load this skill before running Office commands. Use only bundled LibreOffice unless the user explicitly opts out; without that opt-out, do not search for another LibreOffice executable.

★ 19