Trim Claude Code skill descriptions to cut per-turn token cost#66444
Trim Claude Code skill descriptions to cut per-turn token cost#66444jedcunningham merged 1 commit intoapache:mainfrom
Conversation
The `description` and `when_to_use` fields in each SKILL.md are loaded into the system prompt every turn so Claude can route to the right skill; the body only loads when the skill is invoked. Frontmatter is the lever for steady-state context cost. Trims maintainer-review, pr-triage, and pr-stats to keep only what's useful for routing: what the skill does, how it picks its targets where that matters (maintainer-review's "my reviews" working list, pr-triage's `ready for maintainer review` label), and the trigger phrases that hint when to invoke it. Drops file-path cross-refs, mutation names, "successor to breeze X" history, and verbose action enumerations — all still present in the SKILL.md bodies, which are unchanged. Saves roughly 500 tokens off the available-skills listing loaded each turn: maintainer-review: ~420 → ~170 tokens pr-triage: ~300 → ~125 tokens pr-stats: ~170 → ~105 tokens
jedcunningham
requested review from
amoghrajesh,
ashb,
choo121600,
jason810496,
jscheffl,
kaxil,
potiuk and
shahar1
as code owners
boring-cyborg
Bot
added
area:dev-tools
backport-to-v3-2-test
Backport failed to create: v3-2-test. View the failure log Run detailsNote: As of Merging PRs targeted for Airflow 3.X In matter of doubt please ask in #release-management Slack channel.
You can attempt to backport this manually by running: cherry_picker f9ae53c v3-2-testThis should apply the commit to the v3-2-test branch and leave the commit in conflict state marking After you have resolved the conflicts, you can continue the backport process by running: cherry_picker --continueIf you don't have cherry-picker installed, see the installation guide. |
|
@potiuk it may be worth doing a similar pass on the skills in airflow-steward. |
Oh absolutely. I will port it there. To be honest I have not done yet "optimization" phase - but I noticed that the agent is very chatty for those (i did not have to worry about the tokens yet - but yes optimization and making those more affordable is a good idea and we have it definitely plnned. |
BTW. My plan is to actulally incorporate https://github.com/JuliusBrussee/caveman/blob/main/README.md ... THIS is a real saving :) |
|
Haha, reminds me of Kevins small talk from the office! |
4 participants
The
descriptionandwhen_to_usefrontmatter fields of every availableSKILL.mdare loaded into the Claude Code system prompt at the start of every turn so it can route to the right skill; the body of each skill only loads on invocation. So frontmatter is the lever for steady-state context cost.Trims
maintainer-review,pr-triage, andpr-statsto keep only what's useful for routing — what the skill does, how it picks its targets where that matters (maintainer-review's "my reviews" working list,pr-triage'sready for maintainer reviewlabel), and the trigger phrases. Drops file-path cross-refs, mutation names, "successor to breeze X" history, and verbose action enumerations — all still present in the SKILL.md bodies, which are unchanged.Saves roughly 500 tokens off the available-skills listing loaded each turn:
The
maintainer-reviewskill was spitting out an warning before as well in/doctor:Was generative AI tooling used to co-author this PR?
Generated-by: Claude Code (Opus 4.7) following the guidelines