# Frontmatter FTW: How to Make Agent Skills Discoverable

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`](http://SKILL.md)) should split cleanly into two layers:

1.  **Discoverability Interface (Frontmatter):** Minimal YAML metadata (`name` and `description`) loaded into the agent's permanent system index (~15-20 tokens per skill).
    
2.  **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`](http://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.

# **Sources**

*   Code samples: [https://github.com/flashlabs/kiss-samples/tree/main/agent-skills-discoverable-frontmatter](https://github.com/flashlabs/kiss-samples/tree/main/agent-skills-discoverable-frontmatter)
    
*   Agent Skills Specification: [https://agentskills.io/specification](https://agentskills.io/specification)
    
*   YAML Front Matter Specification: [https://jekyllrb.com/docs/front-matter/](https://jekyllrb.com/docs/front-matter/)
    
*   Model Context Protocol: [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/)