---
title: Skill — claude code token hygiene
type: reference
tags: [skill, aria, claude-code-token-hygiene]
date: 2026-05-23
status: aktiv
related: [[02-Wissen/nate-herk-token-saving-anthropic-2026-05-21]], [[02-Wissen/anthropic-personal-guidance-2026-05-21]], [[HOOKS]]
linear: KAR-471, KAR-426, KAR-251
---

# Skill — claude-code-token-hygiene

## Zweck

Operative Diszplin damit der Aria-Hauptthread nicht in den 250k-Cap rennt, und damit Subagent-Spawns nicht durch Cache-Loss teuer werden. Konsolidiert die Lessons aus KAR-251, KAR-426 und der Nate-Herk-Analyse (KAR-471) zu einem deterministischen Decision-Tree.

## Why we built this

Bei laengeren Sessions sammelt der Hauptthread schnell Compactions, was Token-Cost (Re-Read des zu komprimierenden Context) und Cache-Hit-Rate massiv senkt. Nate-Herk hat 2026-05 dokumentiert dass Anthropic-interne Engineers ~300M Tokens/Woche durch Caching sparen — vorausgesetzt sie achten auf Cache-Hygiene (keine unnoetigen System-Prompt-Changes, klare Subagent-Briefs, kein "kreatives" Tool-Switching).

Ohne deterministische Regeln degradiert Aria-Verhalten ueber Session-Laenge: mehr Compactions, weniger Cache-Hits, langsamere Antworten, hoehere Kosten. Dieser Skill ist der Anker, der bei Trigger-Events sicherstellt dass die richtige Strategie (Inline vs. Subagent, Effort-Level, Tool-Wahl) gewaehlt wird.

## Architektur

**Trigger-Quellen** (siehe SKILL.md "Wann triggern"):
1. `/context` zeigt > 30 Compactions oder > 70% Cap
2. Kais sagt: "context wird voll", "token-cap", "compaction", "/effort", "/context"
3. Vor jedem Subagent-Spawn mit hohem Output-Budget
4. Vor jedem inline Tool-Read der > 200 Zeilen produzieren wird

**Decision-Tree** (im SKILL.md kodiert):
- **Lookup** → inline (Read mit offset/limit, Grep mit files_with_matches)
- **Investigation** → Subagent Explore (breadth quick/medium)
- **Bulk-Process** → Subagent general-purpose (Report < 500 Worte)
- **Spec/Plan-Writing** → inline wenn < 50% Cap, sonst Subagent

**Cache-Hygiene-Layer** (aus Nate-Herk-Analyse):
- System-Prompt nie inline modifizieren — Cache wird invalidiert
- Sub-Agents bekommen short briefs (< 300 Worte), nicht "do everything"
- Tools werden NICHT mid-task gewechselt (von Read auf Bash zurueck auf Read) — Cache-Tier-Wechsel kostet
- Bei Multi-Round-Dialog: User-Reply moeglichst kurz halten, damit der gesharte Prefix nicht durch Aria-Re-Statement gebrochen wird

## Anti-Cognitive-Debt-Checkliste

- [x] SKILL.md mit DoR/DoD vorhanden (81 LOC, status aktiv)
- [x] Brain-Note (diese Datei) mit Why+How
- [x] Tests / Golden-Questions in SKILL.md
- [x] Linked-KAR-Issue: KAR-471 (this), KAR-426, KAR-251

## Tests

Siehe SKILL.md Section "Tests / Golden Questions" — 5 konkrete Trigger-Cases vom Lookup bis zur 80%-Cap-Recovery.

## Open Follow-Ups

- **KAR-472** — `nateherkai/token-dashboard` Setup-Evaluation. Wenn das Dashboard genutzt wird: Aria sollte die Live-Token-Counts in eine Brain-Daily-Log-Summary schreiben (cron-getriggert).
- **Hook-Wiring**: Heute triggert der Skill nur via User-Phrase oder agentic decision. Kuenftig moeglich: pre-tool-use Hook auf `Read`/`Bash` mit File-Size-Limit > 8 KB, der den Skill auto-vorschlaegt.

## Verwandt

- [[/root/.claude/skills/claude-code-token-hygiene/SKILL.md]] (Skill-Definition, kanonisch)
- [[02-Wissen/nate-herk-token-saving-anthropic-2026-05-21]] (Source-Material)
- [[02-Wissen/anthropic-personal-guidance-2026-05-21]] (Cross-Reference)
- [[HOOKS]] (Potential Hook-Wiring)