The most common misconception about agent skills is that they are “just markdown files.” In practice, a skill is a folder that can include scripts, assets, data, and reference documents that the agent discovers and reads at appropriate times. This reframes the file system itself as a Skill graphs enable progressive disclosure for complex domains mechanism — you split detailed API signatures into references/api.md, output templates into assets/, and helper libraries into scripts/, and the agent navigates this structure progressively rather than loading everything upfront.
This is a concrete implementation of the principle that Files are the universal interface between humans and agents: the folder hierarchy becomes deliberate information architecture, not just file organization. The same way CLAUDE.md should be a routing table, not a knowledge base keeps the top-level file minimal and points deeper, a well-structured skill keeps its SKILL.md as a workflow outline with pointers to reference files that get loaded only when needed — reducing context waste while preserving access to the full knowledge.