Summary
A SKILL.md playbook larger than 8 KB never appears in the skill catalog and
skill <name> cannot load it. Six of my Claude Code skills are affected, and
the split is exact: every skill that loads is <= 8192 bytes, every skill that is
missing is > 8192 bytes.
Root cause
In src/skill_docs.zig, mergeFile reads the catalog head with:
const data = Io.Dir.cwd().readFileAlloc(io, path, arena, .limited(head_cap)) catch return;
where head_cap = 8 * 1024. Zig's .limited(n) returns error.StreamTooLong
when the file exceeds n bytes, so catch return drops the skill entirely.
It is then absent from both promptCatalog and execSkill's rescan, because
both go through the same mergeFile.
This contradicts the documented 256 KB file_cap and the comment's stated
intent ("catalog read: frontmatter + proof of a body"). The catalog read should
truncate to head_cap (enough for frontmatter plus proof of a body), not fail.
Evidence
~/.claude/skills/ on Windows, loaded vs dropped by byte size:
Loads (all <= 8192): code-simplifier 3129, diagnose 7280,
git-guardrails-claude-code 2407, grill-me 2523, grill-with-docs 3727,
improve-codebase-architecture 6599, karpathy-guidelines 2357, obsidian-vault
2337, postmortem 2861, premortem 2339, setup-matt-pocock-skills 6982, tdd 4504,
to-issues 3659, to-prd 2999, triage 4986, zoom-out 437.
Dropped (all > 8192): graphify 33973, interview-prep-generator 12430,
job-description-analyzer 14883, resume-ats-optimizer 9490,
tech-resume-optimizer 10926, ui-ux-pro-max 44776.
Suggested fix
Read the catalog head with a truncating read instead of a failing limit, or
catch StreamTooLong and re-read exactly head_cap bytes. The full body should
remain available for a named skill load under file_cap.
Summary
A SKILL.md playbook larger than 8 KB never appears in the skill catalog and
skill <name>cannot load it. Six of my Claude Code skills are affected, andthe split is exact: every skill that loads is <= 8192 bytes, every skill that is
missing is > 8192 bytes.
Root cause
In
src/skill_docs.zig,mergeFilereads the catalog head with:where
head_cap = 8 * 1024. Zig's.limited(n)returnserror.StreamTooLongwhen the file exceeds
nbytes, socatch returndrops the skill entirely.It is then absent from both
promptCatalogandexecSkill's rescan, becauseboth go through the same
mergeFile.This contradicts the documented 256 KB
file_capand the comment's statedintent ("catalog read: frontmatter + proof of a body"). The catalog read should
truncate to
head_cap(enough for frontmatter plus proof of a body), not fail.Evidence
~/.claude/skills/on Windows, loaded vs dropped by byte size:Loads (all <= 8192): code-simplifier 3129, diagnose 7280,
git-guardrails-claude-code 2407, grill-me 2523, grill-with-docs 3727,
improve-codebase-architecture 6599, karpathy-guidelines 2357, obsidian-vault
2337, postmortem 2861, premortem 2339, setup-matt-pocock-skills 6982, tdd 4504,
to-issues 3659, to-prd 2999, triage 4986, zoom-out 437.
Dropped (all > 8192): graphify 33973, interview-prep-generator 12430,
job-description-analyzer 14883, resume-ats-optimizer 9490,
tech-resume-optimizer 10926, ui-ux-pro-max 44776.
Suggested fix
Read the catalog head with a truncating read instead of a failing limit, or
catch
StreamTooLongand re-read exactlyhead_capbytes. The full body shouldremain available for a named
skillload underfile_cap.