SKILL: Portable Skill Loader Progressive Disclosure

Domain: skill-loading Trigger: Use when an agent must scan thousands of skills but only load detailed prompts for the handful that are actually invoked. Source Pattern: Distilled from reviewed command-surface, skill-discovery, and CLI capability implementations.

Core Method

Separate discovery from loading. During startup, scan only lightweight metadata such as the skill name, summary, trigger text, and file location to build a searchable index. Load the full instruction body only after the agent actually selects that skill, and cache the resolved metadata and file identities so repeated lookups stay cheap. Deduplicate by canonical path, and skip invalid or ignored skill directories without failing the whole scan.

Key Rules

• Read only lightweight metadata during discovery; defer the full skill body until invocation time.
• Resolve canonical paths so duplicate folders, symlinks, and mirrored mounts do not appear as separate skills.
• Treat malformed frontmatter or missing files as warnings to skip, not as fatal startup errors.
• Cache discovery results per source and invalidate them only when the relevant roots or settings change.

Example Application

When building a CLI skill browser for a large monorepo, index every skill folder using only summary metadata at startup, then load the full instructions only for the skills the user or model actually opens.

Anti-Patterns (What NOT to do)

• Don’t eagerly read every SKILL.md file during startup; that blocks discovery and may exceed token budgets.
• Don’t treat invalid frontmatter as fatal—skip the skill instead of crashing.