Skip to content

Split SKILL.md (1,114 lines) into a core skill + on-demand references/ for progressive disclosure #1641

Description

@vickaul-ai

The installed Claude Code skill (~/.claude/skills/graphify/SKILL.md, v0.8.14) is a single
1,114-line file. Claude Code loads the whole body every time the skill fires, and its trigger is
deliberately broad ("any question about a codebase … especially if graphify-out/ exists"), so a
quick one-line graph query pays the context cost of the entire pipeline documentation
(~10–12k tokens).

Agent Skills' progressive-disclosure convention handles this: keep the always-needed core in
SKILL.md and move branch-specific documentation into references/ files that the model reads
only when that branch is taken.

Suggested split (v0.8.14 line ranges):

Content Lines Destination
Usage, "what graphify is for", pipeline Steps 0–9 1–~765 keep in SKILL.md
Subagent extraction-prompt template ~332–397 references/extraction-prompt.md
--update incremental rebuild ~786–943 references/subcommands.md
--cluster-only ~947–955 references/subcommands.md
query / path / explain / add ~959–1053 references/subcommands.md
--watch ~1055–1074 references/subcommands.md
git hook integration ~1076–1088 references/subcommands.md
CLAUDE.md integration ~1092–1105 references/subcommands.md

Each moved section is replaced in SKILL.md by a one-line pointer, e.g.
For --update / --watch / query / git-hook / CLAUDE.md integration, read references/subcommands.md.

This keeps the common invocation (build or query a graph) at roughly 60% of the current size
while making the rarely-used branches free until needed. Happy to PR this if the structure is
agreeable.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions