SKILL: Three-Layer Extension Sync
Domain: plugin-installation
Trigger: Apply when extensions exist simultaneously as declared settings, on-disk installs, and live runtime components, and those layers must stay coherent.
Source Pattern: Distilled from reviewed plugin, extension, and MCP synchronization implementations.
Core Method
Split extension management into three layers: intent in configuration, materialization on disk, and active runtime state. Use the diff/reconcile phase to move layer 1 toward layer 2 without touching UI state, then use a separate refresh phase to rebuild layer 3 from the materialized result. This keeps each transition explicit, makes fallback rules clear, and prevents partial reload logic from smearing together configuration, installation, and activation responsibilities.
Key Rules
- Give each layer a single owner: configuration declares desired state, reconciliation mutates on-disk artifacts, and runtime refresh repopulates active commands, agents, hooks, and servers.
- Compare intent to materialization before doing work so you know whether to install, update, skip, or defer.
- Treat reconciliation as additive and side-effect-bounded; it should not directly mutate live AppState beyond progress or recovery flags.
- Refresh the active layer from cleared caches after materialization changes so runtime loaders rebuild from the new disk state instead of patching stale objects in place.
- Make escalation explicit: urgent changes can auto-refresh, while less urgent ones can stop at a needs refresh contract.
Example Application
In a desktop agent with third-party extensions, treat settings as the declared catalog, a local extensions directory as the materialized layer, and the in-memory command registry as the active layer. Reconcile settings to disk first, then run a distinct reload step that repopulates the active registry from the updated install set.
Anti-Patterns (What NOT to do)
- Do not let a single function both clone marketplaces and directly mutate live component registries; that blurs error handling and recovery.
- Do not compare runtime state back to settings as a proxy for disk state; materialization needs its own truth source.
- Do not patch active components incrementally against stale caches when the on-disk layer changed underneath them.
1---2name: three-layer-extension-sync3description: Model extension lifecycle as intent, materialization, and active runtime layers, then sync each layer with dedicated transitions.4---56# SKILL: Three-Layer Extension Sync7**Domain:** plugin-installation8**Trigger:** Apply when extensions exist simultaneously as declared settings, on-disk installs, and live runtime components, and those layers must stay coherent.9**Source Pattern:** Distilled from reviewed plugin, extension, and MCP synchronization implementations.1011## Core Method12Split extension management into three layers: intent in configuration, materialization on disk, and active runtime state. Use the diff/reconcile phase to move layer 1 toward layer 2 without touching UI state, then use a separate refresh phase to rebuild layer 3 from the materialized result. This keeps each transition explicit, makes fallback rules clear, and prevents partial reload logic from smearing together configuration, installation, and activation responsibilities.1314## Key Rules15- Give each layer a single owner: configuration declares desired state, reconciliation mutates on-disk artifacts, and runtime refresh repopulates active commands, agents, hooks, and servers.16- Compare intent to materialization before doing work so you know whether to install, update, skip, or defer.17- Treat reconciliation as additive and side-effect-bounded; it should not directly mutate live AppState beyond progress or recovery flags.18- Refresh the active layer from cleared caches after materialization changes so runtime loaders rebuild from the new disk state instead of patching stale objects in place.19- Make escalation explicit: urgent changes can auto-refresh, while less urgent ones can stop at a needs refresh contract.2021## Example Application22In a desktop agent with third-party extensions, treat settings as the declared catalog, a local extensions directory as the materialized layer, and the in-memory command registry as the active layer. Reconcile settings to disk first, then run a distinct reload step that repopulates the active registry from the updated install set.2324## Anti-Patterns (What NOT to do)25- Do not let a single function both clone marketplaces and directly mutate live component registries; that blurs error handling and recovery.26- Do not compare runtime state back to settings as a proxy for disk state; materialization needs its own truth source.27- Do not patch active components incrementally against stale caches when the on-disk layer changed underneath them.
vishuwa2004