Skip to content

SKILL.md playbooks larger than 8 KB are silently dropped from the catalog #730

Description

@v1-nce

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions