If your AI agent loads 30 complete Markdown skill files directly into its system prompt, you're burning 40,000 tokens of input budget before the user even types a single word. Worse, drowning the model in thousands of lines of procedural steps triggers context rot: reasoning accuracy drops, instruction following degrades, and request latency spikes.

The fix isn't keeping fewer skills. It's decoupling skill discoverability from skill execution using YAML frontmatter as a hard boundary.

The Frontmatter Boundary

Every skill file (SKILL.md) should split cleanly into two layers:

Discoverability Interface (Frontmatter): Minimal YAML metadata (name and description) loaded into the agent's permanent system index (~15-20 tokens per skill).
Execution Body: Step-by-step instructions and edge-case handlers, fetched dynamically via tool calls (view_file / read_file) only when the agent matches user intent against the frontmatter description.

Keeping only frontmatter in the initial prompt index drops the permanent context footprint of 50 skills from ~40,000 tokens down to under 800.

Agent Self-Governance Rules

When agents generate or update their own skills dynamically (f.e. after running automated learning routines or saving custom workflows), relying on human prompt discipline breaks down. The agent itself must enforce strict skill hygiene when persisting files to disk.

Mandatory Frontmatter Generation

An agent saving a learned workflow must never output raw Markdown without metadata. The skill-writing prompt must mandate extracting a concise name and a trigger-focused description header before writing the implementation body.

Conflict & Overlap Detection

Before writing a new SKILL.md file, the agent must inspect existing frontmatters in the skills directory. If the proposed trigger description overlaps with an existing skill, the agent must either merge the new instructions into the existing file or sharpen the description to make the trigger boundary mutually exclusive.

Without this pre-write check, ambiguous frontmatters cause the agent to fetch the wrong instruction sets or pull multiple competing skills into context at runtime.

Treat skill frontmatter as a public API signature: the system prompt only needs to know what a skill does and when to trigger it. The agent should only read how it works at the exact moment of execution.