skill-listing-reset-on-real-skill-changes

SKILL: Skill Listing Reset on Real Skill Changes

Domain: command-surfaces
Trigger: Apply when a system tracks which skills have already been announced and must decide when that sent-state should be cleared. Source Pattern: Distilled from reviewed command-surface and listing-control patterns.

Core Method

Tie announcement-state resets to real changes in the underlying skill inventory, such as plugin reloads or skill file changes on disk. Do not clear the sent-state for compaction, transcript recovery, or other conversation-level churn, because that would force expensive re-injections of essentially unchanged listings. This keeps listing deltas meaningful and avoids paying thousands of tokens to restate the same inventory after every context-management event.

Key Rules

• Reset the sent-state when the registry itself changes, not when the conversation representation changes.
• Keep reset triggers narrow and explicit, such as plugin reload or skill-file mutation hooks.
• Do not piggyback listing resets onto compaction, resume, or transcript maintenance paths unless those paths also change the actual registry.
• Clear any paired suppression flags together with the sent-state so the next genuine delta announcement starts from a clean slate.

Example Application

If a desktop agent reloads plugins and the available skill set changes, clear the sent-skill tracking map so the next listing can announce the new tools. If the conversation merely compacts or rehydrates from transcript, leave the sent-state alone so the agent does not spend tokens repeating an unchanged listing.

Anti-Patterns (What NOT to do)

• Do not reset announcement state on every compaction or replay event; that turns context maintenance into repeated full-list reinjection.
• Do not leave suppression flags out of sync with the reset; partial resets create confusing one-off gaps in later announcements.