AgentSkillsCN

documenting-breaking-changes

针对重大变更，撰写清晰易懂的文档说明，帮助用户充分理解变更影响，并顺利完成迁移。适用于发布需要用户主动操作以维持功能正常运行的变更时使用。

SKILL.md
--- frontmatter
name: documenting-breaking-changes
description: Create clear documentation for breaking changes that helps users understand impact and migrate successfully. Use when releasing changes that require user action to maintain functionality.

Documenting Breaking Changes

Quick start

Collect or infer:

  • •What specifically changed (API, behavior, configuration)
  • •Who is affected (all users, specific integrations, specific versions)
  • •What breaks if users don't act
  • •How to migrate (step-by-step)
  • •Timeline (grace period, deprecation date, removal date)

Then produce output using TEMPLATES.md. Validate with RUBRIC.md.

Workflow

  1. •Identify the change type and scope precisely.
  2. •Document what worked before and what works now.
  3. •Explain who is affected and how to detect if impacted.
  4. •Provide step-by-step migration instructions.
  5. •Include before/after code examples.
  6. •Set clear timelines with specific dates.
  7. •Link to related documentation and support.
  8. •Run the rubric check. Revise until it passes.

Degrees of freedom

  • •Low: Migration documentation structure must be followed strictly.
  • •Allowed variation: Level of technical detail based on audience, as long as rubric passes.

State awareness

  • •If change affects security, prioritize and expedite communication.
  • •If change has workarounds, document temporary and permanent solutions.
  • •If change affects subset of users, help users self-identify.
  • •If migration is complex, consider migration tooling.

Failure modes to avoid

  • •Describing what changed without explaining impact
  • •Missing migration steps
  • •Vague timelines ("soon", "in a future release")
  • •Not helping users identify if they're affected
  • •Assuming technical knowledge without stating prerequisites

References