claude-code - 💡(How to fix) Fix [FEATURE] Conditional section loading in skills based on $ARGUMENTS [2 comments, 2 participants]

Summary

When a skill is invoked, the entire SKILL.md is injected into the context regardless of which subcommand/argument the user passes. For skills with multiple subcommands, this creates significant token waste — the model receives instructions for all operations when it only needs one.

Problem

Consider a skill with 4 subcommands (~500 tokens total prompt):

---
name: my-tool
argument-hint: "[create|list|delete|info] [name]"
---

## Argument parsing
Parse $ARGUMENTS to extract subcommand...

## Subcommand: create
(~150 tokens of instructions)

## Subcommand: list
(~100 tokens of instructions)

## Subcommand: delete
(~80 tokens of instructions)

## Subcommand: info
(~60 tokens of instructions)

When the user runs /my-tool list, all ~500 tokens are injected — but only ~100 are relevant. The other ~400 tokens are dead weight.

Current workaround: Split into separate skills (my-tool-create, my-tool-list, etc.). This works but:

• Clutters the skills list (each entry costs ~14 tokens in the listing, always present)
• Loses the ergonomic single-command UX (/my-tool list vs /my-tool-list)
• Duplicates shared context (common paths, conventions) across files

Token cost analysis

Proposed solution

Allow SKILL.md to define conditional sections that are only included when $ARGUMENTS matches a pattern. Possible syntax options:

Option A: Multi-file skill with argument routing (recommended)

my-tool/
├── SKILL.md           # shared context (always loaded)
├── create.md          # loaded when $ARGUMENTS starts with "create"
├── list.md            # loaded when $ARGUMENTS starts with "list"
└── ...

With frontmatter routing:

---
name: my-tool
routes:
  - match: "^create"
    include: create.md
  - match: "^list"
    include: list.md
---

# Shared context (always loaded)
...

Option B: Frontmatter-based sections

---
name: my-tool
sections:
  create:
    match: "^create"
    file: create.md
  list:
    match: "^list"
  default:
    match: "*"
---

Option C: Markdown directive syntax

<!-- @if $ARGUMENTS starts with "create" -->
## Create instructions
...
<!-- @endif -->

<!-- @if $ARGUMENTS starts with "list" -->
## List instructions
...
<!-- @endif -->

Benefits

1. Token efficiency — only load relevant instructions per invocation
2. Clean UX — keep single skill with subcommands (/tool action)
3. Lower skills list overhead — one entry instead of N
4. Scales well — skills with many subcommands don't bloat context proportionally

Environment

• Claude Code version: Latest (April 2026)
• Platform: All