Skip to content

Adopt 'caveman'-style skill-authoring write-skill to cut per-turn token cost #80

@potiuk

Description

@potiuk

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.

Worked example — apache/airflow#66444

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.

Metadata

Metadata

Assignees

Labels

area:docsDocs, MISSION.md, READMEskind:perfToken / latency / API-call budgetmode:cross-cuttingSpans multiple modes

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions