{"id":"d96f4f6e-6b2d-41d0-92d6-df3eff8866a4","shortId":"Vn4knU","kind":"skill","title":"materialization-aware-refresh-escalation","tagline":"React to marketplace materialization diffs by refreshing plugins when new installs land and escalating to needsRefresh when updates or refresh failures occur.","description":"# SKILL: Materialization-Aware Refresh Escalation\n**Domain:** extensions-mcp  \n**Trigger:** When background plugin installation reconcilers detect that declared marketplaces differ from what is materialized, use the diff to decide whether to auto-refresh plugins or escalate to a manual refresh prompt.\n**Source Pattern:** Distilled from reviewed extension lifecycle and source-reconciliation patterns.\n\n## Core Method\n1. Before reconciling, read the declared marketplaces (`getDeclaredMarketplaces()`), the previously materialized config (`loadKnownMarketplacesConfig()`), and compute `diffMarketplaces()` so you know which names are missing or changed.\n2. Build `pendingNames` from `diff.missing` plus `diff.sourceChanged` so the UI reports exactly which marketplaces are still being processed; return early when that array is empty so no work runs unless there is material change.\n3. Call `reconcileMarketplaces({ onProgress })`, map the `installing`/`installed`/`failed` events to AppState, track metrics for installed/updated/failed/up-to-date counts, and log them via `logEvent` and diagnostics helpers.\n4. After reconciliation, inspect the result:\n   - When `result.installed.length > 0`, clear the marketplace cache, log the auto-refresh path, and await `refreshActivePlugins(setAppState)` inside a try/catch so MCP caches are rebuilt. On refresh failure, log the error, clear the plugin cache, and set `plugins.needsRefresh` via AppState only if it was previously false.\n   - When there are no fresh installs but `result.updated.length > 0`, clear both marketplace and plugin caches and set the `needsRefresh` flag so the UI invites `/reload-plugins` while avoiding an automatic refresh.\n   - When there are neither installs nor updates, skip cache invalidation and refresh so the reconciliation stays lightweight.\n\n## Key Rules\n- Only auto-refresh when brand-new marketplaces were installed; updates-only reconciliations should not trigger the refresh path.\n- Clear both marketplace and plugin caches before touching `refreshActivePlugins` or setting `needsRefresh` so stale artifacts cannot leak into the new plugin state.\n- Always wrap `refreshActivePlugins` in a try/catch, log failures (`logError`, `logForDebugging`), and fall back to `needsRefresh` rather than silently suppressing the error.\n- Guard the `needsRefresh` setter so it only flips once per failure path and never reassigns while the flag is already true.\n\n## Example Application\nInstalling a curated marketplace during background startup on a fresh homespace uses this path so the new tools become available without forcing the user to manually run `/reload-plugins`.\n\n## Anti-Patterns (What NOT to do)\n- Do not refresh plugin state when `result.installed.length === 0`; the caches were already populated and redundant refreshes slow startup.\n- Do not swallow refresh failures; the fallback `needsRefresh` flag exists so the UI can surface `/reload-plugins` once the auto-path fails.\n- Do not clear caches only after calling `refreshActivePlugins`; stale cache entries must be removed before the refresh attempt or the refresh may still resolve to old code.","tags":["materialization","aware","refresh","escalation","cskill","agents","ychampion","agent-skills","ai-agents","cli","coding-agents","context-engineering"],"capabilities":["skill","source-ychampion","skill-materialization-aware-refresh-escalation","topic-agent-skills","topic-ai-agents","topic-cli","topic-coding-agents","topic-context-engineering","topic-developer-tools","topic-mcp","topic-multi-agent","topic-terminal-ui"],"categories":["cskill-agents"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/ychampion/cskill-agents/materialization-aware-refresh-escalation","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add ychampion/cskill-agents","source_repo":"https://github.com/ychampion/cskill-agents","install_from":"skills.sh"}},"qualityScore":"0.467","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 34 github stars · SKILL.md body (3,136 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T06:56:50.679Z","embedding":null,"createdAt":"2026-04-18T22:20:40.358Z","updatedAt":"2026-04-22T06:56:50.679Z","lastSeenAt":"2026-04-22T06:56:50.679Z","tsv":"'/reload-plugins':245,384,425 '0':177,229,399 '1':85 '2':110 '3':144 '4':169 'alreadi':353,403 'alway':313 'anti':386 'anti-pattern':385 'applic':356 'appstat':155,214 'array':132 'artifact':305 'attempt':449 'auto':61,185,272,429 'auto-path':428 'auto-refresh':60,184,271 'automat':249 'avail':376 'avoid':247 'await':189 'awar':3,31 'back':325 'background':40,362 'becom':375 'brand':276 'brand-new':275 'build':111 'cach':181,197,209,235,259,296,401,435,441 'call':145,438 'cannot':306 'chang':109,143 'clear':178,206,230,291,434 'code':458 'comput':99 'config':96 'core':83 'count':160 'curat':359 'decid':57 'declar':46,90 'detect':44 'diagnost':167 'diff':10,55 'diff.missing':114 'diff.sourcechanged':116 'differ':48 'diffmarketplac':100 'distil':73 'domain':34 'earli':129 'empti':134 'entri':442 'error':205,333 'escal':5,19,33,65 'event':153 'exact':121 'exampl':355 'exist':419 'extens':36,76 'extensions-mcp':35 'fail':152,431 'failur':26,202,320,344,414 'fall':324 'fallback':416 'fals':220 'flag':240,351,418 'flip':341 'forc':378 'fresh':225,366 'getdeclaredmarketplac':92 'guard':334 'helper':168 'homespac':367 'insid':192 'inspect':172 'instal':16,42,150,151,226,255,280,357 'installed/updated/failed/up-to-date':159 'invalid':260 'invit':244 'key':268 'know':103 'land':17 'leak':307 'lifecycl':77 'lightweight':267 'loadknownmarketplacesconfig':97 'log':162,182,203,319 'logerror':321 'logev':165 'logfordebug':322 'manual':68,382 'map':148 'marketplac':8,47,91,123,180,232,278,293,360 'materi':2,9,30,52,95,142 'materialization-awar':29 'materialization-aware-refresh-escal':1 'may':453 'mcp':37,196 'method':84 'metric':157 'miss':107 'must':443 'name':105 'needsrefresh':21,239,302,327,336,417 'neither':254 'never':347 'new':15,277,310,373 'occur':27 'old':457 'onprogress':147 'path':187,290,345,370,430 'pattern':72,82,387 'pendingnam':112 'per':343 'plugin':13,41,63,208,234,295,311,395 'plugins.needsrefresh':212 'plus':115 'popul':404 'previous':94,219 'process':127 'prompt':70 'rather':328 'react':6 'read':88 'reassign':348 'rebuilt':199 'reconcil':43,87 'reconcilemarketplac':146 'reconcili':81,171,265,284 'redund':406 'refresh':4,12,25,32,62,69,186,201,250,262,273,289,394,407,413,448,452 'refreshactiveplugin':190,299,315,439 'remov':445 'report':120 'resolv':455 'result':174 'result.installed.length':176,398 'result.updated.length':228 'return':128 'review':75 'rule':269 'run':138,383 'set':211,237,301 'setappst':191 'setter':337 'silent':330 'skill':28 'skill-materialization-aware-refresh-escalation' 'skip':258 'slow':408 'sourc':71,80 'source-reconcili':79 'source-ychampion' 'stale':304,440 'startup':363,409 'state':312,396 'stay':266 'still':125,454 'suppress':331 'surfac':424 'swallow':412 'tool':374 'topic-agent-skills' 'topic-ai-agents' 'topic-cli' 'topic-coding-agents' 'topic-context-engineering' 'topic-developer-tools' 'topic-mcp' 'topic-multi-agent' 'topic-terminal-ui' 'touch':298 'track':156 'trigger':38,287 'true':354 'try/catch':194,318 'ui':119,243,422 'unless':139 'updat':23,257,282 'updates-on':281 'use':53,368 'user':380 'via':164,213 'whether':58 'without':377 'work':137 'wrap':314","prices":[{"id":"969a19be-02db-4e5d-ba1d-bd50fa5bbb92","listingId":"d96f4f6e-6b2d-41d0-92d6-df3eff8866a4","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"ychampion","category":"cskill-agents","install_from":"skills.sh"},"createdAt":"2026-04-18T22:20:40.358Z"}],"sources":[{"listingId":"d96f4f6e-6b2d-41d0-92d6-df3eff8866a4","source":"github","sourceId":"ychampion/cskill-agents/materialization-aware-refresh-escalation","sourceUrl":"https://github.com/ychampion/cskill-agents/tree/main/skills/materialization-aware-refresh-escalation","isPrimary":false,"firstSeenAt":"2026-04-18T22:20:40.358Z","lastSeenAt":"2026-04-22T06:56:50.679Z"}],"details":{"listingId":"d96f4f6e-6b2d-41d0-92d6-df3eff8866a4","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"ychampion","slug":"materialization-aware-refresh-escalation","github":{"repo":"ychampion/cskill-agents","stars":34,"topics":["agent-skills","ai-agents","cli","coding-agents","context-engineering","developer-tools","mcp","multi-agent","terminal-ui"],"license":"mit","html_url":"https://github.com/ychampion/cskill-agents","pushed_at":"2026-04-04T14:13:23Z","description":"Agent skills for coding CLIs, multi-agent runtimes, context engines, MCP extensions, and terminal tooling. Instead of using claude code's source code, give your agent skills to create your own!","skill_md_sha":"79a54ff9dae48bfc5705e8235cd34482ca88b2f7","skill_md_path":"skills/materialization-aware-refresh-escalation/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/ychampion/cskill-agents/tree/main/skills/materialization-aware-refresh-escalation"},"layout":"multi","source":"github","category":"cskill-agents","frontmatter":{"name":"materialization-aware-refresh-escalation","description":"React to marketplace materialization diffs by refreshing plugins when new installs land and escalating to needsRefresh when updates or refresh failures occur."},"skills_sh_url":"https://skills.sh/ychampion/cskill-agents/materialization-aware-refresh-escalation"},"updatedAt":"2026-04-22T06:56:50.679Z"}}