{"id":"cb365022-d036-4eda-aa35-919dcee583c1","shortId":"bxNrdD","kind":"skill","title":"deferred-refresh-flag-contract","tagline":"Decide when to auto-refresh plugins after marketplaces change and when to defer to a manual `/reload-plugins` via the `needsRefresh` flag.","description":"# SKILL: Deferred Refresh Flag Contract\n**Domain:** extensions-mcp  \n**Trigger:** `performBackgroundPluginInstallations` completes `reconcileMarketplaces` and must decide whether to auto-refresh plugins or set `plugins.needsRefresh` via AppState.\n**Source Pattern:** Distilled from reviewed extension lifecycle and source-reconciliation patterns.\n\n## Core Method\nWhen new marketplaces are installed (`result.installed.length > 0`), treat the change as urgent: clear both marketplace and plugin caches, then call `refreshActivePlugins(setAppState)` so MCP connections re-establish with the freshly cloned sources. If that auto-refresh fails, log the error, clear the plugin cache with a reason string, and set `plugins.needsRefresh = true` so the UI prompts `/reload-plugins`. When only updates are available (`result.updated.length > 0`), do not auto-refresh; instead clear caches and set `needsRefresh` so the user opts into the reload. `needsRefresh` updates must be idempotent: the setter checks `prev.plugins.needsRefresh` and returns early if already true.\n\n## Key Rules\n- Always run `clearMarketplacesCache()` before refreshing or flagging; it ensures the cached metadata is rebuilt before the next plugin load.\n- For installs, wrap `refreshActivePlugins(setAppState)` in a try/catch. On failure, call `clearPluginCache('performBackgroundPluginInstallations: auto-refresh failed')` and fall back to the `needsRefresh` guard that sets the flag to true only once.\n- For updates-only, clear the plugin cache with `clearPluginCache('performBackgroundPluginInstallations: marketplaces reconciled')` so stale plugin bundles are not re-used, but leave control in the user’s hands by setting `needsRefresh` instead of forcing a reload.\n- The `needsRefresh` setter uses `setAppState(prev => { if (prev.plugins.needsRefresh) return prev; return { ...prev, plugins: { ...prev.plugins, needsRefresh: true } }; })` so the UI can show a single prompt and avoid redundant re-renders.\n\n## Example Application\nAfter `reconcileMarketplaces` returns `result.installed = [ ... ]`, the manager clears caches and calls `refreshActivePlugins`. If the refresh completes, caches stay clear and MCP reconnects automatically. If the refresh throws, the catch logs the failure, clears the plugin cache with a descriptive reason, and the guard flips `plugins.needsRefresh` so `/reload-plugins` shows up instead. When only `result.updated` is populated, the same cache-clearing and guard runs, but without trying to refresh automatically.\n\n## Anti-Patterns (What NOT to do)\n- Do not auto-refresh when only marketplace updates exist; forcing a reload can interrupt long-running contexts when an update can safely wait for an explicit `/reload-plugins`.\n- Do not leave cache-clearing out of either branch—stale marketplace metadata or plugin bundles will confuse the auto-refresh or manual reload paths.\n- Do not set `needsRefresh` by overwriting the object blindly; always check the previous flag so a failed refresh path does not recreate the AppState slice on every error log.","tags":["deferred","refresh","flag","contract","cskill","agents","ychampion","agent-skills","ai-agents","cli","coding-agents","context-engineering"],"capabilities":["skill","source-ychampion","skill-deferred-refresh-flag-contract","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/deferred-refresh-flag-contract","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,053 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:48.006Z","embedding":null,"createdAt":"2026-04-18T22:20:14.806Z","updatedAt":"2026-04-22T06:56:48.006Z","lastSeenAt":"2026-04-22T06:56:48.006Z","tsv":"'/reload-plugins':23,127,336,394 '0':75,134 'alreadi':166 'alway':170,430 'anti':360 'anti-pattern':359 'applic':290 'appstat':54,444 'auto':10,47,105,138,203,369,415 'auto-refresh':9,46,104,137,202,368,414 'automat':312,358 'avail':132 'avoid':284 'back':208 'blind':429 'branch':404 'bundl':237,410 'cach':86,114,142,180,228,298,306,325,348,399 'cache-clear':347,398 'call':88,199,300 'catch':318 'chang':15,78 'check':160,431 'clear':81,111,141,225,297,308,322,349,400 'clearmarketplacescach':172 'clearplugincach':200,230 'clone':100 'complet':39,305 'confus':412 'connect':93 'context':384 'contract':5,32 'control':245 'core':67 'decid':6,43 'defer':2,19,29 'deferred-refresh-flag-contract':1 'descript':328 'distil':57 'domain':33 'earli':164 'either':403 'ensur':178 'error':110,448 'establish':96 'everi':447 'exampl':289 'exist':375 'explicit':393 'extens':35,60 'extensions-mcp':34 'fail':107,205,437 'failur':198,321 'fall':207 'flag':4,27,31,176,216,434 'flip':333 'forc':256,376 'fresh':99 'guard':212,332,351 'hand':250 'idempot':157 'instal':73,190 'instead':140,254,339 'interrupt':380 'key':168 'leav':244,397 'lifecycl':61 'load':188 'log':108,319,449 'long':382 'long-run':381 'manag':296 'manual':22,418 'marketplac':14,71,83,232,373,406 'mcp':36,92,310 'metadata':181,407 'method':68 'must':42,155 'needsrefresh':26,145,153,211,253,260,273,424 'new':70 'next':186 'object':428 'opt':149 'overwrit':426 'path':420,439 'pattern':56,66,361 'performbackgroundplugininstal':38,201,231 'plugin':12,49,85,113,187,227,236,271,324,409 'plugins.needsrefresh':52,121,334 'popul':344 'prev':264,268,270 'prev.plugins':272 'prev.plugins.needsrefresh':161,266 'previous':433 'prompt':126,282 're':95,241,287 're-establish':94 're-rend':286 're-us':240 'reason':117,329 'rebuilt':183 'reconcil':233 'reconcilemarketplac':40,292 'reconcili':65 'reconnect':311 'recreat':442 'redund':285 'refresh':3,11,30,48,106,139,174,204,304,315,357,370,416,438 'refreshactiveplugin':89,192,301 'reload':152,258,378,419 'render':288 'result.installed':294 'result.installed.length':74 'result.updated':342 'result.updated.length':133 'return':163,267,269,293 'review':59 'rule':169 'run':171,352,383 'safe':389 'set':51,120,144,214,252,423 'setappst':90,193,263 'setter':159,261 'show':279,337 'singl':281 'skill':28 'skill-deferred-refresh-flag-contract' 'slice':445 'sourc':55,64,101 'source-reconcili':63 'source-ychampion' 'stale':235,405 'stay':307 'string':118 'throw':316 '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' 'treat':76 'tri':355 'trigger':37 'true':122,167,218,274 'try/catch':196 'ui':125,277 'updat':130,154,223,374,387 'updates-on':222 'urgent':80 'use':242,262 'user':148,248 'via':24,53 'wait':390 'whether':44 'without':354 'wrap':191","prices":[{"id":"dba558ab-a717-4d41-becd-00b6b835fc82","listingId":"cb365022-d036-4eda-aa35-919dcee583c1","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:14.806Z"}],"sources":[{"listingId":"cb365022-d036-4eda-aa35-919dcee583c1","source":"github","sourceId":"ychampion/cskill-agents/deferred-refresh-flag-contract","sourceUrl":"https://github.com/ychampion/cskill-agents/tree/main/skills/deferred-refresh-flag-contract","isPrimary":false,"firstSeenAt":"2026-04-18T22:20:14.806Z","lastSeenAt":"2026-04-22T06:56:48.006Z"}],"details":{"listingId":"cb365022-d036-4eda-aa35-919dcee583c1","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"ychampion","slug":"deferred-refresh-flag-contract","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":"2807fc84878ec0f682d350b430547a688f40a079","skill_md_path":"skills/deferred-refresh-flag-contract/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/ychampion/cskill-agents/tree/main/skills/deferred-refresh-flag-contract"},"layout":"multi","source":"github","category":"cskill-agents","frontmatter":{"name":"deferred-refresh-flag-contract","description":"Decide when to auto-refresh plugins after marketplaces change and when to defer to a manual `/reload-plugins` via the `needsRefresh` flag."},"skills_sh_url":"https://skills.sh/ychampion/cskill-agents/deferred-refresh-flag-contract"},"updatedAt":"2026-04-22T06:56:48.006Z"}}