[Question] Why does the claude-code adapter eagerly load full SKILL.md instead of using progressive disclosure (metadata-only or file passthrough)?

[swchen44]

Question: Skill Loading Strategy in the claude-code Adapter

Hi, I've been studying the gitagent codebase in detail and noticed an interesting design tension worth discussing.

What I observed

skill-loader.ts already implements a clean two-tier progressive disclosure pattern:

• loadSkillMetadata() — lightweight, ~100 tokens, returns only name + description from the YAML frontmatter
• • loadSkillFull() / loadAllSkills() — full parse, returns frontmatter + complete Markdown instructions body
    The gitagent skills list command correctly uses the lightweight path via discoverSkills(). The openclaw adapter also takes a different approach — passing through raw SKILL.md files as standalone workspace files, letting the OpenClaw runtime handle them natively.

However, the claude-code adapter calls loadAllSkills(), eagerly inlining every skill's full instruction body directly into CLAUDE.md.

My question

Was this a deliberate trade-off, or a placeholder for a future improvement?

I'm curious about the reasoning behind not adopting one of these alternatives for the claude-code adapter:

1. Metadata-only initial load — Inline only name, description, and allowed-tools from each skill's frontmatter into CLAUDE.md, then let Claude read the full SKILL.md file on-demand when it needs to execute that capability. This mirrors how knowledge/ already works with always_load.
2. File passthrough — Instead of inlining skill content at all, reference the skill files by path (e.g., @skills/code-review/SKILL.md) and rely on Claude Code's native file-reading capability to pull them in when needed.

Why this matters

With agents that have many skills, eager full-text inlining could significantly inflate the context window on every invocation — even for skills that are rarely or never triggered. The progressive disclosure infrastructure is already built; it just isn't wired up to the export path.

Is there a plan to align the claude-code (and system-prompt) adapters with a smarter loading strategy?

[shreyas-lyzr]

Thanks for the great catch @ruvnet! You're absolutely right — the claude-code adapter was eagerly inlining full SKILL.md instructions even though skill-loader.ts already had the progressive disclosure pattern ready to go.

Fixed in #20 — the claude-code adapter now uses loadAllSkillMetadata() and outputs only name, description, allowed-tools, and a file path reference. Claude Code reads the full SKILL.md on demand when the skill is activated, saving ~5000 tokens per skill.

The system-prompt adapter is intentionally left as-is since it produces standalone prompts for LLMs that can't read files from disk.

[shreyas-lyzr]

thanks for the suggestion fixed the oversight, @swchen44 please create a new issue if you have any more suggestions over impl, this helps the project.