claude-code - 💡(How to fix) Fix [FEATURE] Add `when:` frontmatter field to SKILL.md for context-gated skill listing [2 comments, 2 participants]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Every installed skill appears in the system-reminder skill listing on every session turn, regardless of whether it is relevant to the current project. A developer working in a Python repository pays the token cost of SwiftUI skills. A repository with no .planning/ directory pays for 86 workflow-orchestration skills from a planning tool like GSD. A CI environment pays for scheduling skills it cannot invoke.

This is the "Tools Tax" — the per-turn overhead from stateless eager injection of all tool schemas, documented in recent research as ranging from 10k–60k tokens in typical multi-skill deployments. Claude Code's skill listing overhead is a direct instance of this problem.

The cost is not just tokens. Research on context utilization identifies a reasoning quality fracture point at ~70% context fill: model accuracy measurably degrades when context is more than 70% full (arXiv:2604.21816). Long sessions with large skill inventories hit this earlier, producing worse planning and routing decisions — silently, with no indication to the user.

Currently there is no way for a skill author to declare when their skill is relevant, so CC must include all skills always. The only workaround is install-time filtering (reducing what is installed), which is a blunt instrument: it removes capabilities permanently rather than surfacing them only when useful.

Proposed Solution

Add a when: field to SKILL.md frontmatter. Claude Code evaluates this condition at session start before building the system-reminder skill listing. Skills whose when: condition is false are omitted from the listing for that session. They remain installed and are still invocable by direct name — they just don't occupy listing tokens in irrelevant contexts.

Syntax

---
name: gsd:workflow
description: "phase pipeline | discuss spec plan execute verify"
when: ".planning/ exists"
---

---
name: swiftui-mvvm
description: "SwiftUI MVVM patterns, @Observable, ViewModels"
when: "*.swift in project"
---

---
name: python-expert
description: "Python best practices, type hints, async patterns"
when: "*.py or pyproject.toml in project"
---

Condition grammar (proposed minimal set)

Conditions are evaluated against the current working directory at session start using the same file-system access CC already has. No network calls, no subprocess, no LLM call required — pure fs.existsSync / glob check.

What does NOT change

• Skills omitted from the listing are still invocable by direct name via Skill("skill-name")
• Install behavior is unchanged — when: is a runtime filter, not an install filter
• Skills without when: behave exactly as today
• The --minimal install flag and MINIMAL_SKILL_ALLOWLIST remain valid orthogonal mechanisms

Alternative Solutions

Install-time filtering (--minimal flags, allowlists): Requires users to decide at install time which skills they will ever need. Permanently removes capabilities from the install. Does not adapt to context — a user who works in both Swift and Python projects must choose one install profile.

Manual disabledSkills config (related: #53746): Requires the user to maintain a list of skills to suppress. Places the burden on the user rather than the skill author who knows when the skill is relevant. Does not adapt automatically as the user switches projects.

Namespace meta-skills (workaround, no platform change needed): Wrap many skills under one listed entry that routes internally. Reduces listing count but cannot gate on project context — all namespace entries still appear regardless of relevance.

None of these scale. A when: field puts the relevance declaration in the skill itself, evaluated automatically, requiring zero user configuration.

Priority

High — Significant impact on productivity

The impact scales with skill inventory size. Users with 50+ installed skills (common with plugin ecosystems and workflow tools) pay the overhead on every single session turn, whether or not those skills are relevant. The reasoning degradation at high context fill is a quality problem that users experience as inconsistent model behavior, not as a token cost — making it harder to diagnose.

Feature Category

Performance and speed (reduces per-session token overhead and preserves context headroom for reasoning)

Use Case Example

Scenario: A developer uses Claude Code across three project types: an iOS app (Swift/SwiftUI), a backend service (Python/FastAPI), and a project using GSD for workflow orchestration (86 gsd-* skills).

Today:

1. Open Claude Code in the iOS project → all 86 GSD skills + all Python skills listed → ~12k tokens of irrelevant listing overhead before the first message
2. Open Claude Code in the Python backend → all SwiftUI skills listed → model occasionally routes to Swift skills on ambiguous queries
3. Long GSD session → context fills with skill listing + plan files + execution traces → reasoning quality degrades after ~2 hours of work

With when::

1. iOS project: when: "*.swift in project" → SwiftUI/Swift skills listed, GSD and Python skills absent → ~1k tokens, all relevant
2. Python backend: when: "*.py or pyproject.toml in project" → Python skills listed, Swift and GSD skills absent
3. GSD project: when: ".planning/ exists" → GSD skills listed only in GSD directories → context headroom preserved for actual work content

Zero configuration change required from the user between projects.

Additional Context

Research basis

Four 2025–2026 papers independently arrive at the same conclusion — selective, context-aware tool exposure reduces token cost and improves routing accuracy simultaneously:

The when: field is the simplest possible version of this pattern — a static declarative condition evaluated cheaply at session start, requiring no embeddings, no vector index, and no per-turn computation. It is the "minimum viable context gate."

Implementation complexity

Low. The required changes are:

1. Parse when: from SKILL.md frontmatter (same YAML parse pass that reads name: and description: today)
2. Evaluate the condition against process.cwd() using fs.existsSync and glob
3. Filter the skill listing array before building system-reminder

No changes to skill invocation, the Skill tool, install behavior, or agent definitions.

Real-world quantification

A GSD full install contributes ~12,000 tokens of skill+agent listing overhead per session turn. With when: ".planning/ exists", that overhead drops to ~0 in any non-GSD directory. For a developer who uses GSD in 2 of 10 projects, this is an 80% reduction in skill listing overhead across their daily Claude Code usage.