Skill description and when_to_use frontmatter fields are loaded into the Claude Code system prompt every turn for routing, even when the skill body itself is not invoked. Verbose phrasing in those fields is therefore a permanent steady-state token tax across every session.
Trimming maintainer-review, pr-triage, and pr-stats frontmatter saved roughly 500 tokens/turn:
maintainer-review: ~420 → ~170 tokens
pr-triage: ~300 → ~125 tokens
pr-stats: ~170 → ~105 tokens
The description / when_to_use fields only need what the router uses: what the skill does, how it picks targets where that matters, trigger phrases. Anything else (file-path cross-refs, mutation enumerations, history footnotes, "successor to X" notes) belongs in the SKILL.md body — which loads only on invocation.
Proposed
- Add a "caveman" (or similarly named — terse-by-design) write-skill that all skill authoring and editing flows pipe through.
- The skill enforces lean phrasing in frontmatter: drop the categories above, keep what the router needs.
- Update existing skill-authoring guidance and any agent prompts to reference the new write-skill so it gets used by default.
- Sweep existing skills once, applying the new style.
Why: every token in skill frontmatter is paid on every turn across every session; lean phrasing is a multiplicative win.
Skill
descriptionandwhen_to_usefrontmatter fields are loaded into the Claude Code system prompt every turn for routing, even when the skill body itself is not invoked. Verbose phrasing in those fields is therefore a permanent steady-state token tax across every session.Worked example — apache/airflow#66444
Trimming
maintainer-review,pr-triage, andpr-statsfrontmatter saved roughly 500 tokens/turn:The
description/when_to_usefields only need what the router uses: what the skill does, how it picks targets where that matters, trigger phrases. Anything else (file-path cross-refs, mutation enumerations, history footnotes, "successor to X" notes) belongs in the SKILL.md body — which loads only on invocation.Proposed
Why: every token in skill frontmatter is paid on every turn across every session; lean phrasing is a multiplicative win.