Claude May Only Preview the First 100 Lines of Your Skill Files: Add a Contents List
Claude's own skill guide says Claude can preview long reference files with head -100. What that means for the rules lower down, the fix from the guide, and a prompt that applies it to every skill you have
When a skill points Claude to another file, Claude does not always read the whole thing. Claude's skill guide says it "might use commands like head -100 to preview content rather than reading entire files, resulting in incomplete information." head -100 shows only the first 100 lines. So in a long reference file, the rules near the bottom can be skipped unless Claude decides the rest is worth reading.
The fix (from the guide)
- Find every reference file in your skills that is over 100 lines (on a Mac or Linux: wc -l ~/.claude/skills/*/*.md).
- At the very top of each one, add a short contents list that matches its headings, for example: ## Contents, then one line per section.
- Link every reference file straight from SKILL.md (one level deep). Files that are only reachable through another file are the ones Claude previews partially.
- Keep the SKILL.md body itself under 500 lines; split the rest into reference files.
Audit every skill in ~/.claude/skills (and .claude/skills in this project if it exists). For each one: 1) List every file SKILL.md links to, and any file that is only linked from another reference file. 2) For every reference file over 100 lines, write a ## Contents list at the very top that matches its headings, one line per section. 3) For every file that is only reachable through another file, add a direct link to it from SKILL.md. 4) Flag any SKILL.md body over 500 lines and suggest what to move into a reference file. Show me a table of the changes per skill and wait for my yes before you edit anything. Do not change any rule's wording.
What the guide's own example looks like
- ## Contents
- - Authentication and setup
- - Core methods (create, read, update, delete)
- - Advanced features (batch operations, webhooks)
- - Error handling patterns
- - Code examples
- "Claude can then read the complete file or jump to specific sections as needed."
Free, for your email
Get the full setup steps + the copy-paste setup prompt
The rest of this guide (2 more sections) opens right here. The setup prompt, one paste into Claude that sets it all up, comes by email only. Use your real address.
50,000+ follow where these guides come from. No spam, unsubscribe in one click.