Keep SKILL.md under 500 lines and link out — progressive disclosure is a 140x token win

Claude Docs·medium signal

Anthropic's skill-authoring guidance treats a skill like a manual: SKILL.md is the lean table-of-contents with high-level logic, and detailed procedures live in linked files (reference.md, forms.md) that Claude only reads when a task demands them. A project with 8 well-structured skills loads ~500 tokens at startup versus ~70,000 if everything loaded eagerly. The technique: write a keyword-rich YAML description to trigger intent recognition, then move any section over a few hundred words into its own file.