Skills are living documents that must evolve with the technologies and practices they describe. This skill covers version management strategies, deprecation workflows, update planning, and the complete lifecycle of a skill file from creation through retirement.

## Key Points

- 2.1.0 (2025-12-15): Added WebGPU examples, updated Three.js to r170
- 2.0.0 (2025-06-01): Rewrote for React 19, new approach to Server Components
- 1.2.0 (2025-03-10): Added testing section, new code examples
- 1.1.0 (2025-01-20): Added performance optimization section
- 1.0.0 (2024-11-01): Initial release
1. Identify trigger (tech sunset, better approach available)
2. Create replacement skill (if applicable)
3. Add deprecation notice to current skill:
4. Update cross-references in other skills
5. Notify users/subscribers of deprecation
6. Maintain for transition period (3-6 months)
7. Move to retired status

Skill Versioning and Lifecycle Management

Purpose

Skills are living documents that must evolve with the technologies and practices they describe. This skill covers version management strategies, deprecation workflows, update planning, and the complete lifecycle of a skill file from creation through retirement.

Semantic Versioning for Skills

Version Schema

Skill Version: MAJOR.MINOR.PATCH

MAJOR (breaking changes):
├── Skill's recommended approach fundamentally changes
├── Significant restructuring of content
├── Scope of skill changes (broader or narrower)
├── Prerequisites change substantially
└── User following old version would do something wrong

MINOR (additive changes):
├── New section added
├── New examples or patterns added
├── Updated for new library/tool version
├── Expanded coverage of existing topic
├── Additional platform support
└── Backward-compatible improvements

PATCH (fixes):
├── Typo corrections
├── Formatting fixes
├── Clarification without new content
├── Broken link repair
├── Code example bug fix
└── Output/result correction

Version Tracking

Version History (maintain in skill or externally):

Method 1: Changelog section in skill file
---
## Changelog
- 2.1.0 (2025-12-15): Added WebGPU examples, updated Three.js to r170
- 2.0.0 (2025-06-01): Rewrote for React 19, new approach to Server Components
- 1.2.0 (2025-03-10): Added testing section, new code examples
- 1.1.0 (2025-01-20): Added performance optimization section
- 1.0.0 (2024-11-01): Initial release
---

Method 2: Git-based tracking
├── Version in frontmatter
├── Git tags for releases (skill-name/v1.0.0)
├── Git log provides change history
└── Diff between versions shows exactly what changed

Method 3: External version registry
├── Centralized version catalog
├── Tracks all skills and their versions
├── API for checking latest version
└── Can notify users of updates

Skill Lifecycle

Lifecycle Stages

Skill Lifecycle:
┌─────────┐   ┌──────────┐   ┌──────────┐   ┌───────────┐
│  Draft  │──→│ Published│──→│ Mature   │──→│ Sunset    │
│         │   │          │   │          │   │           │
└─────────┘   └──────────┘   └──────────┘   └─────┬─────┘
                                                   │
                                             ┌─────┴─────┐
                                             │ Retired   │
                                             └───────────┘

Stage Definitions:
├── Draft:
│   ├── Under development, not for production use
│   ├── May be incomplete or inaccurate
│   ├── Flagged as draft in metadata
│   └── Not indexed for discovery
│
├── Published:
│   ├── Reviewed, tested, ready for use
│   ├── Actively maintained
│   ├── Indexed and discoverable
│   └── Feedback collection active
│
├── Mature:
│   ├── Stable, well-tested, widely used
│   ├── Infrequent updates needed
│   ├── Comprehensive coverage of topic
│   └── Community-validated accuracy
│
├── Sunset:
│   ├── Technology/approach becoming outdated
│   ├── Replacement skill identified or in development
│   ├── Warning added: "This skill covers legacy approach"
│   ├── Points to successor skill
│   └── Still available but not recommended for new projects
│
└── Retired:
    ├── No longer applicable (technology EOL)
    ├── Removed from primary discovery
    ├── Archived for historical reference
    └── Clear notice: "This skill is retired. See [replacement]."

Deprecation Process

Deprecation Workflow:
1. Identify trigger (tech sunset, better approach available)
2. Create replacement skill (if applicable)
3. Add deprecation notice to current skill:

   > **Deprecation Notice (2025-06-15)**
   > This skill covers [Legacy Approach] which is being
   > replaced by [New Approach]. For new projects, use
   > the "[New Skill Name]" skill instead.
   > This skill will be retired on [date or milestone].

4. Update cross-references in other skills
5. Notify users/subscribers of deprecation
6. Maintain for transition period (3-6 months)
7. Move to retired status
8. Archive (don't delete — someone may need it)

Transition Period:
├── Both old and new skills available
├── Old skill clearly points to new one
├── Migration guide provided (how to transition)
├── Support for questions about migration
└── Duration: Depends on technology adoption curve

Update Strategies

Proactive vs. Reactive Updates

Proactive Updates (scheduled):
├── Quarterly review of all published skills
├── Check for library/tool version updates
├── Verify external links still work
├── Review community feedback
├── Update examples with current best practices
└── Schedule: Set calendar reminders per skill

Reactive Updates (triggered):
├── User reports incorrect information
├── Library releases breaking change
├── Security vulnerability discovered in example code
├── New better approach becomes available
├── Platform/runtime changes behavior
└── Response time: Critical → same day; Normal → within 1 week

Update Priority Matrix:
┌──────────────┬───────────────────┬────────────────────┐
│              │ Wide Impact       │ Narrow Impact      │
├──────────────┼───────────────────┼────────────────────┤
│ Incorrect    │ P0 — Fix today    │ P1 — Fix this week │
│ information  │                   │                    │
├──────────────┼───────────────────┼────────────────────┤
│ Missing      │ P1 — Fix this     │ P2 — Next update   │
│ information  │ week              │ cycle              │
├──────────────┼───────────────────┼────────────────────┤
│ Improvement  │ P2 — Next update  │ P3 — Backlog       │
│ opportunity  │ cycle             │                    │
└──────────────┴───────────────────┴────────────────────┘

Breaking Changes

When a skill's recommended approach changes:

1. Assess impact:
   ├── How many users depend on current approach?
   ├── Is the old approach still valid? (just not recommended)
   ├── Can both approaches coexist?
   └── Is migration straightforward?

2. Plan the transition:
   ├── Write new version alongside old (don't overwrite immediately)
   ├── Document migration path
   ├── Provide timeline for old version support
   └── Communicate change prominently

3. Execute:
   ├── Publish new version (MAJOR bump)
   ├── Add deprecation notice to old version
   ├── Update cross-references in other skills
   └── Monitor for issues with new version

4. Example of handled breaking change:
   Old: "Use class components with lifecycle methods"
   New: "Use function components with hooks"

   Migration note in new skill:
   "If migrating from class components, key differences:
   - componentDidMount → useEffect with empty dependency array
   - this.state → useState
   - this.setState → state setter function
   See 'React Migration: Classes to Hooks' skill for details."

Multi-Version Support

Supporting Multiple Versions of Same Skill:

Scenario: Library has multiple active versions
(e.g., Angular 16 and Angular 17 both in production use)

Approach 1: Version-specific skills
├── angular-16-routing.md
├── angular-17-routing.md
└── Pros: Clear, complete per version
    Cons: Content duplication, double maintenance

Approach 2: Version notes within single skill
├── angular-routing.md
│   └── Contains: "In Angular 16: [approach]. In Angular 17+: [approach]"
└── Pros: Single file, comparative
    Cons: Can get cluttered with many versions

Approach 3: Base skill + version diffs
├── angular-routing.md (latest version)
├── angular-routing-v16-notes.md (differences from latest)
└── Pros: Primary skill is clean, historical available
    Cons: Two files to maintain

Recommendation:
├── Use Approach 2 for 2-3 active versions
├── Use Approach 1 for major paradigm shifts
├── Use Approach 3 for gradual deprecation
└── Always state which version the skill targets in Purpose section

Automation

Automated Lifecycle Tasks:

1. Freshness Check (monthly cron):
   - Scan all skills for last-modified date
   - Flag skills not updated in 6+ months
   - Check if technology versions in skill are still current
   - Generate report of stale skills

2. Link Checking (weekly cron):
   - Validate all external URLs
   - Check internal cross-references
   - Report broken or redirected links

3. Version Consistency:
   - Verify frontmatter version matches changelog
   - Check that version was incremented since last publish
   - Validate semver format

4. Dependency Monitoring:
   - Track library versions mentioned in skills
   - Alert when new major versions release
   - Suggest skills that may need updating

5. Usage Analytics:
   - Track which skills are most/least accessed
   - Identify skills with high bounce rate (loaded but not useful)
   - Surface skills that may need improvement

When to Apply This Skill

Use this skill when:

• Setting up version management for a skill repository
• Planning the lifecycle of a new skill from creation to retirement
• Handling a technology change that affects existing skills
• Deciding whether a change warrants a patch, minor, or major version
• Deprecating a skill in favor of an updated replacement
• Automating skill maintenance workflows