Comment by DonHopkins

You've nailed the core insight about progressive disclosure. MOOLLM extends this into what we call the Semantic Image Pyramid (or MOO-Maps ;), borrowing from Mip-Maps in graphics. Four resolution levels, each serving different needs.

GLANCE.yml is the smallest, 5-70 lines. Just enough to answer "is this relevant?" You can inject all glances into every prompt because they're tiny. The LLM scans them like a table of contents.

CARD.yml is the interface layer, 50-200 lines. No implementation, just what the skill offers Capability advertisements, activation conditions, scoring, what it composes with. Think of it like The Sims "advertisement" system or CLOS generic function dispatch. The LLM sniffs this to decide whether to load the full SKILL.md implementation.

SKILL.md is the Anthropic-style skill file, 200-1000 lines. The actual instructions, the how. Only loaded when the skill is activated.

README.md is the largest, 500+ lines, and it's for humans. History, design rationale, examples. The LLM can dive in when developing the skill or when curious, but it's not burned on every invocation.

Reading rule: never load a lower level without first loading the level above. Start with GLANCE, sniff the CARD, load SKILL only if needed.

Even more compact than concatenating all glances:

We also found INDEX.md beats INDEX.yml for the skill catalog. YAML repeats the same keys for every entry. Markdown allows narrative explanation of how skills relate, which clusters matter for what tasks, making it both more compact and more useful.

INDEX.yml: 711 lines, 2061 words, 17509 chars, ~4380 tokens, machine readable structure

https://github.com/SimHacker/moollm/blob/main/skills/INDEX.y...

INDEX.md: 124 lines, 1134 words, 9487 chars, ~2370 tokens, human readable prose

https://github.com/SimHacker/moollm/blob/main/skills/INDEX.m...

INDEX.md is 83% fewer lines, 45% fewer words, 46% fewer chars for 121 skills. YAML repeats keys like id, tagline, why for every entry. Markdown uses headers and prose, compresses better, allows narrative grouping of related skills.

And it's simply more meaningful to both LLMs and humans, telling a coherent story instead of representing raw data!

The Semantic Image Pyramid:

https://github.com/SimHacker/moollm/blob/main/designs/LEELA-...

Same principle applies to code. A skill can wrap a sister-script that IS the documentation. A Python script with argparse defines the CLI once, readable by both humans (--help) and LLMs (sniff the top of the python file). No separate docs to maintain, no drift between what the code does and what the docs claim.

sister-script: https://github.com/SimHacker/moollm/blob/main/skills/sister-...

Sniffable-python structures code so the API is visible in the first 50 lines. Imports, constants, CLI structure up front. Implementation below the fold. The LLM can decide relevance and understand the API without reading the whole file. Single source of truth, progressive disclosure, don't repeat yourself.

sniffable-python README.md: https://github.com/SimHacker/moollm/blob/main/skills/sniffab...

sniffable-python SKILL.md: https://github.com/SimHacker/moollm/blob/main/skills/sniffab...