Why CLAUDE.md Files Waste Tokens and How Skills Offer a Better Alternative
This technical analysis argues that the common practice of using large CLAUDE.md or agent.md files in AI coding agents is inefficient and costly. These files inject thousands of tokens into every conversation turn, often repeating information the model can already infer from the codebase, such as framework usage or file types. This redundancy wastes context window space and increases costs without improving performance. The article suggests that for most projects, these files are unnecessary except for conveying proprietary methodologies. Instead, it recommends using 'skills,' a feature employing progressive disclosure. Skills load only a brief name and description into the context initially, keeping detailed instructions on disk until the agent specifically needs them for a relevant task. This approach significantly reduces token consumption. Furthermore, the author warns against writing skills based on guesswork, emphasizing that effective skills should be derived from recorded successful workflows to ensure the agent understands practical application rather than just mechanical steps.
Editorial responsibility
- No named human review is recorded for this page.
- Reports are grouped by semantic similarity and deterministic rules. Language models may assist titles, summaries, translation and cross-source analysis; the page itself is projected from evidence records.
- Current automated evidence projection
Wire timeline
Why CLAUDE.md Files Waste Tokens and How Skills Offer a Better Alternative
This technical analysis argues that the common practice of using large CLAUDE.md or agent.md files in AI coding agents is inefficient and costly. These files inject thousands of tokens into every conversation turn, often repeating information the model can already infer from the codebase, such as framework usage or file types. This redundancy wastes context window space and increases costs without improving performance. The article suggests that for most projects, these files are unnecessary except for conveying proprietary methodologies. Instead, it recommends using 'skills,' a feature employing progressive disclosure. Skills load only a brief name and description into the context initially, keeping detailed instructions on disk until the agent specifically needs them for a relevant task. This approach significantly reduces token consumption. Furthermore, the author warns against writing skills based on guesswork, emphasizing that effective skills should be derived from recorded successful workflows to ensure the agent understands practical application rather than just mechanical steps.