claude-code - 💡(How to fix) Fix Support @-include syntax in plugin SKILL.md files and their transitive .md includes [1 participants]

Feature request

Extend the @path/to/file.md inline-include syntax (currently supported in CLAUDE.md project instructions) to plugin SKILL.md files and any .md files they transitively include.

Current behavior

The @AGENTS.md / @KARPATHY_CLAUDE.md syntax in CLAUDE.md causes the harness to resolve the reference at load time and inject the file content inline — no model-issued Read tool call is needed.

Plugin SKILL.md files (and the .md reference files they load) do not support this syntax. Any shared content that must be present at skill invocation time must instead be loaded via an explicit Read tool call, which adds a round-trip: the model must issue the call, wait for the result, and only then proceed.

Requested behavior

Allow @path/to/file.md (and @${CLAUDE_PLUGIN_ROOT}/path/to/file.md with existing variable substitution) to work as a load-time include in:

1. SKILL.md — the top-level skill definition file.
2. Any .md file reachable from SKILL.md — i.e., the transitive closure of .md files that a skill loads during its execution.

The harness would resolve these includes at skill-load time (before the model sees the file), injecting the referenced file's content inline, exactly as it does for CLAUDE.md.

Use case / motivation

Large plugin suites (e.g. larch) have shared reference files that must be loaded on every skill invocation. Currently this requires MANDATORY READ ENTIRE FILE directives that force the model to issue Read tool calls before it can proceed. Across a skill with 5–10 such mandatory shared files, this adds 5–10 synchronous tool-call round-trips to every invocation.

With @-include support in SKILL.md and its transitive .md includes, unconditional shared content could be pre-embedded at load time, eliminating the round-trips for those files. Conditional/tiered loads — e.g. "load digest by default, full file only when needed" — would intentionally remain as model-directed Read calls, since they require runtime decision-making.

Scope note

Only unconditional, session-start mandatory files benefit from this change. Conditional/tiered reads cannot and should not be replaced by load-time includes.

Related

• larch internal tracker: character-ai/larch#1788