# Deferred Refresh Flag Contract

> Decide when to auto-refresh plugins after marketplaces change and when to defer to a manual `/reload-plugins` via the `needsRefresh` flag.

- **Type:** Skill
- **Install:** `agentstack add skill-ychampion-cskill-agents-deferred-refresh-flag-contract`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ychampion](https://agentstack.voostack.com/s/ychampion)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ychampion](https://github.com/ychampion)
- **Source:** https://github.com/ychampion/cskill-agents/tree/main/agents/claude-code/skills/deferred-refresh-flag-contract
- **Website:** https://x.com/YashasGunderia/status/2039990540016693692?s=20

## Install

```sh
agentstack add skill-ychampion-cskill-agents-deferred-refresh-flag-contract
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SKILL: Deferred Refresh Flag Contract
**Domain:** extensions-mcp  
**Trigger:** `performBackgroundPluginInstallations` completes `reconcileMarketplaces` and must decide whether to auto-refresh plugins or set `plugins.needsRefresh` via AppState.
**Source Pattern:** Distilled from reviewed extension lifecycle and source-reconciliation patterns.

## Core Method
When 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.

## Key Rules
- Always run `clearMarketplacesCache()` before refreshing or flagging; it ensures the cached metadata is rebuilt before the next plugin load.
- 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.
- 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.
- 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.

## Example Application
After `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.

## Anti-Patterns (What NOT to do)
- 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`.
- Do not leave cache-clearing out of either branch—stale marketplace metadata or plugin bundles will confuse the auto-refresh or manual reload paths.
- 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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ychampion](https://github.com/ychampion)
- **Source:** [ychampion/cskill-agents](https://github.com/ychampion/cskill-agents)
- **License:** MIT
- **Homepage:** https://x.com/YashasGunderia/status/2039990540016693692?s=20

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ychampion-cskill-agents-deferred-refresh-flag-contract
- Seller: https://agentstack.voostack.com/s/ychampion
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.