Skill: Deprecation & Migration

Purpose

Manage the lifecycle of deprecating skills, commands, templates, registry entries, or any Vibe Coding OS artifact — distinguishing Compulsory deprecations (security breaks, irrecoverable errors) from Advisory deprecations (replacement available, convenience deprecation). Enforce a 5-question pre-deprecation gate and a structured sunset timeline that protects users from silent breakage.

When to use

Use when an artifact (skill, command, template, registry entry, schema, API contract, external dependency) is being replaced, removed, or marked end-of-life. Triggers include:

• Replacing an existing skill/command with a better-designed one
• Marking a registry entry as deprecated due to a security issue
• Sunset a template that no longer reflects current best practice
• Removing a feature that has been superseded
• Communicating an end-of-life timeline to users

Inputs

• Target artifact (path or identifier)
• Reason for deprecation (security, replacement, redundancy, end-of-life)
• Replacement artifact (if any)
• Migration path (steps users must take)
• Severity classification (compulsory vs advisory)

Workflow

1. Apply the 5 pre-deprecation questions. Before marking ANY artifact as deprecated, answer ALL 5:
   1. System value — what does this artifact still provide that the replacement does not?
   2. Consumers — who depends on this artifact? (count, criticality, migration effort)
   3. Replacement — what is the replacement, and is it fully feature-equivalent? (gaps documented)
   4. Migration cost — what is the cost for consumers to migrate? (lines of config, steps, risk)
   5. Maintenance cost of NOT deprecating — what ongoing cost (bug surface, doc burden, support load) is the project paying to keep this artifact alive?
2. Classify severity.
   • Compulsory — security vulnerability, irrecoverable error, license violation, irreplaceable dependency failure. NOT an option; users MUST migrate by sunset date. Notice period: minimum 2 minor versions OR 30 days, whichever is longer.
   • Advisory — replacement available, redundancy cleanup, end-of-life of a convenience feature. Users SHOULD migrate; no forced deadline. Notice period: minimum 1 minor version OR 14 days.
3. Document the deprecation notice. Use a ## Deprecation section in the skill/command file with: target, reason, replacement, migration path, severity, sunset date, contact.
4. Mark the artifact. Add status: "deprecated" to the relevant registry entry, add a ## Deprecation section to the skill/command file with severity, replacement, sunset date, and migration link.
5. Add the deprecation gate. During validation, surface a warning (advisory) or error (compulsory) for any reference to a deprecated artifact. Track in registry/deprecation-tracker.json (or registry/sources.json extension).
6. Communicate. Add entry to CHANGELOG.md under ### Deprecated. For compulsory deprecations, also update README, layer READMEs, and any docs that reference the artifact.
7. Sunset. On sunset date, remove the artifact (or set status: "sunset" for compulsory migrations with a transitional grace period). Update the deprecation tracker.

Outputs

• ## Deprecation section in target file
• registry/deprecation-tracker.json entry (or extension to registry/sources.json)
• Updated CHANGELOG.md
• For compulsory: updated README + layer READMEs + adapter docs
• ## Deprecation section in the target file
• Validation gate updates

Failure modes

• Deprecating without a replacement (users stranded)
• Marking compulsory when advisory would suffice (panic; users revolt)
• Marking advisory when compulsory is required (security incident)
• Sunset date without notice period (silent breakage)
• Deprecation notice without migration path (users cannot comply)
• Removing the artifact before sunset date (premature)
• Failing to track which consumers are affected (no migration telemetry)

Common rationalizations to reject

Red flags (must produce remediation)

• Compulsory deprecation without 2-version/30-day notice
• Advisory deprecation with no sunset date
• Deprecation notice without migration path
• Removing the artifact before sunset date
• No registry/deprecation-tracker.json entry
• CHANGELOG.md not updated
• README/layer-READMEs reference a deprecated artifact without the deprecation note

Verification checklist

• All 5 pre-deprecation questions answered
• Severity classified (compulsory vs advisory) with justification
• ## Deprecation section in target file with severity, replacement, sunset date
• Artifact marked with status: "deprecated" in registry
• CHANGELOG.md updated under ### Deprecated
• For compulsory: README + layer READMEs + adapter docs updated
• registry/deprecation-tracker.json (or extension) has the entry
• Validation gate warns (advisory) or errors (compulsory) on references
• Sunset date set and communicated

Source alignment

Inspired by addyosmani/agent-skills deprecation-and-migration category (MIT, verified 2026-06-20). Adapted into Vibe Coding OS with original wording, Compulsory/Advisory classification, 5-question pre-deprecation gate, and bilingual maintainability notes. The skill is intentionally framework-agnostic — it applies to any artifact (skill, command, template, registry, schema) in Vibe Coding OS and generalizes to any framework following the same artifact pattern.

Ghi chú tiếng Việt

Trước khi deprecate BẤT KỲ artifact nào (skill, command, template, registry, schema), phải trả lời 5 câu hỏi ở workflow step 1. Phân loại severity: Compulsory (security break, irrecoverable error) cần tối thiểu 2 minor versions hoặc 30 ngày notice; Advisory (replacement sẵn, redundancy cleanup) cần tối thiểu 1 minor version hoặc 14 ngày. Mọi deprecation PHẢI có migration path rõ ràng — không có nghĩa là "người dùng tự biết". Tracking trong registry/deprecation-tracker.json (hoặc extension của registry/sources.json). Validation gate phải warn (advisory) hoặc error (compulsory) khi reference đến deprecated artifact.