Evolution Patterns
Purpose: load this when installed skills drift from the repository and Sigil must decide whether to update, replace, split, merge, or archive them.
Contents
- Lifecycle states
- Triggers
- Update strategies
- Migration workflows
- Report template
Skill Lifecycle States
ACTIVE -> STALE -> DEPRECATED -> ARCHIVED
^ | |
| +-> UPDATE |
+-------------REPLACE+| State | Detection | Action |
|---|---|---|
ACTIVE |
Re-evaluation >= 9/12 |
Keep as-is |
STALE |
Re-evaluation 6-8/12 |
Trigger evolution workflow |
DEPRECATED |
Re-evaluation < 6/12 or superseded by successor |
Mark deprecated and create successor |
ARCHIVED |
Framework or library removed from the project | Remove from active directories after confirmation when removal is required |
Evolution Triggers
Automatic Detection During SCAN
| Trigger | Detection method | Example |
|---|---|---|
| Dependency version change | Manifest diff | React 18 -> 19 |
| Framework migration | Framework removed and another added | Pages Router -> App Router |
| Convention change | Rule/config diff | strict mode enabled |
| Directory restructure | Expected path no longer exists | src/ -> app/ |
| Testing framework change | Test dependencies changed | Jest -> Vitest |
User-Initiated Signals
| Trigger | Signal |
|---|---|
| Explicit refresh request | User asks to update skills |
| Bug report | Generated skill is now incorrect |
| Feature request | Existing skill no longer covers needed patterns |
Update Strategies
Strategy 1: In-Place Update
Use for minor convention changes or small feature additions.
- Read the existing skill.
- Edit only affected sections.
- Preserve unaffected structure and references.
- Re-score with the quality rubric.
Strategy 2: Replace
Use for major framework or architectural changes.
- Generate a new skill from current context.
- Preserve the skill name when continuity matters.
- Mark the old skill deprecated.
- Archive the old skill only after user confirmation if active files must be removed or replaced.
Strategy 3: Split
Use when one skill has grown too broad.
- Identify distinct responsibilities.
- Create
2-3focused successor skills. - Archive the broad skill after confirmation if removal is required.
- Update references that pointed to the original skill.
Strategy 4: Merge
Use when several skills overlap heavily.
- Confirm overlap is greater than
50%. - Merge into one clearer skill.
- Archive redundant predecessors after confirmation if active copies must be removed.
- Promote to Full if the merged workflow becomes complex.
Migration Workflows
Framework Version Upgrade
- Detect the version change.
- Identify breaking changes.
- Map old patterns to new patterns.
- Update affected templates and conventions.
- Re-validate all affected skills.
Framework Switch
- Detect framework removal and replacement.
- Mark old-framework skills as
DEPRECATED. - Run a fresh
DISCOVERfor the new framework. - Generate the new skill set.
- Archive deprecated skills only after user confirmation.
Convention Evolution
- Detect rule or config changes.
- Extract the new conventions.
- Update convention-type skills first.
- Update template sections in workflow skills.
- Re-validate convention compliance.
Evolution Report Template
## Skill Evolution Report
### Trigger
- **Type**: [dependency_change | framework_migration | convention_update | user_request]
- **Detail**: [specific change]
- **Affected skills**: [list]
### Analysis
| Skill | Current State | Strategy | Impact |
|-------|---------------|----------|--------|
| [name] | STALE/DEPRECATED | In-place/Replace/Split/Merge | [description] |
### Changes Applied
- [Skill name]: [change summary]
### Quality Re-Evaluation
| Skill | Before | After | Delta |
|-------|--------|-------|-------|
| [name] | [score]/12 | [score]/12 | [+/-N] |
### Sync Status
- All updated skills synced to `.claude/skills/` and `.agents/skills/`: YES/NO