cache skill
Blocks tool use when the prompt cache is cold or context is near compaction to prevent unnecessary token consumption.
- GitHub stars
- 13
- Files
- 1
- Last commit
- Nov 10, 2026
- License
- —
- Allowed tools
- —
What does the cache skill do?
cache blocks tool use when the prompt cache is cold or context is near compaction to prevent unnecessary token consumption.
Summary generated from the skill's SKILL.md.
About the cache skill
Preventing unnecessary token consumption by blocking tool use when the prompt cache is cold or context is near compaction is what this skill accomplishes. It acts as a PreToolUse gate for developers using Claude Code or Gemini CLI who want to avoid the high costs of re-reading context after the five-minute prompt-cache TTL expires. By monitoring usage data, the skill can halt commands that would otherwise burn tokens inefficiently.
Users manage these protections through the /ar:cache slash command family. You can set specific thresholds for the cache hit ratio, minimum cache read tokens, maximum cache age, or context window compaction levels. The skill is off by default and follows a fail-open philosophy, meaning it allows tool use if usage data is unavailable or malformed. It relies on session state filelocks to ensure multiprocess safety during parallel hook invocations.
What an agent can do with it
- 1Protect against cache expiration costsEnable a gate that stops tool execution if the prompt cache has fallen out of its five-minute TTL.
- 2Set a minimum cache hit ratioConfigure the agent to block tool use whenever the cache hit ratio drops below a specific percentage.
- 3Prevent context compaction lossBlock commands when the total input tokens approach the limit of the context window to avoid compaction-triggered loss.
- 4Temporarily override cache blocksAllow tool use for a specific duration or a set number of uses even when cache thresholds are met.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the cache skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the cache skill in Plugin
/plugin marketplace add ahundt/autorun /plugin install ar@autorun
Install the cache skill in Claude Code
~/.claude/skills/cache/SKILL.md
$ npx degit ahundt/autorun/plugins/autorun/skills/cache ~/.claude/skills/cacheInstall the cache skill in Claude Code (project)
.claude/skills/cache/SKILL.md
$ npx degit ahundt/autorun/plugins/autorun/skills/cache .claude/skills/cacheInstall the cache skill in Codex
~/.agents/skills/cache/SKILL.md
$ npx degit ahundt/autorun/plugins/autorun/skills/cache ~/.agents/skills/cacheInstall the cache skill in Gemini CLI
~/.gemini/skills/cache/SKILL.md
$ npx degit ahundt/autorun/plugins/autorun/skills/cache ~/.gemini/skills/cacheInstall the cache skill in Claude.ai
npx degit ahundt/autorun/plugins/autorun/skills/cache cache && zip -r cache.zip cache # claude.ai → Customize → Skills → + → Create skill → Upload a skill → cache.zip
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableSKILL.md is no longer at this path on the default branchgithub.com/ahundt/autorun/tree/HEAD/plugins/autorun/skills/c ↗Finding
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit 2026-11-10github.com/ahundt/autorun/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/ahundt/autorun/blob/HEAD/plugins/autorun/skills/c ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/ahundt/autorun/blob/HEAD/plugins/autorun/skills/c ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 160 linesgithub.com/ahundt/autorun/blob/HEAD/plugins/autorun/skills/c ↗Pass
SKILL.md
View on GitHub/ar:cache — Cache Miss / Compaction Protection Skill
A PreToolUse gate that blocks commands when the prompt cache is effectively cold — saving tokens by preventing full-rate re-reads of context that has just fallen out of the 5-minute prompt-cache TTL. Off by default.
When to use this skill
Invoke when the user asks about any of:
- setting a cache-miss / cache-hit-ratio threshold
- protecting against compaction-triggered context loss
/ar:cache,/ar:cache on,/ar:cache ok 5m,/ar:cache set …- "how do I stop Claude from burning tokens after idle time"
- "what is the cache gate", "cache protection"
Harness note: this is a skill, while /ar:cache is a runtime autorun command.
Claude Code can usually pass the slash form to hooks. Codex may intercept
unknown slash commands before hooks see them, so use ar:cache or
ar cache ... in Codex prompts when you need the runtime command.
1. Philosophy
- Off by default. No block fires unless the user runs
/ar:cache on. - Fail-open. If usage data is unavailable (old Claude Code version, Gemini CLI without cache-token fields, malformed JSONL), the gate allows.
- Reuse, don't reinvent. The gate uses the same
ScopedAllowgrants,parse_scope_argsgrammar,session_statefilelock backend, andcheck_blocked_commandsblock UX that/ar:ok//ar:noalready use. - Stay out of the statusline. The gate does not install or modify the
user's
statusLinesetting. An optional one-line tap exists for users who want to feed their statusline's rich JSON into the gate themselves.
2. Commands
/ar:cache # show status
/ar:cache on [5m|1h|perm] # enable
/ar:cache off [5m|1h|perm] # disable (temporarily or until re-enabled)
/ar:cache set ratio 0.3 # block when cache hit ratio < 30%
/ar:cache set read 50k # block when cache_read_tokens < 50,000
/ar:cache set age 10m # block when last cache hit older than 10 min
/ar:cache set full 0.9 # block when total_input / window > 90%
/ar:cache ok 5m # override for 5 minutes
/ar:cache ok 3 # override next 3 tool uses
/ar:cache ok perm # override until axis clears / session end
/ar:cache no # clear outstanding overrides
Units: tokens accept 50000, 50,000, 50_000, 50k, .5M, 1.5M.
Percent: 85% or bare decimal 0.85. Durations: 5m, 1h, 2h30m, 2d, perm.
3. Grammar decision: /ar:cache ok not /ar:ok cache
The two grammars are semantically distinct. /ar:ok <pattern> allows a
command-string pattern; /ar:cache ok <scope> overrides the feature gate.
Overloading /ar:ok cache would silently collide with any user command named
cache. Decision: no /ar:ok cache alias in v1. A sigil-based
alias (e.g. /ar:ok @cache) is backwards-compatible to add later if users ask.
4. How the decision flows (PreToolUse)
tool use
│
▼
FeatureToggle("cache").is_enabled() ──► false → ALLOW (default)
│ true
▼
CacheGuard._read_usage:
1) cache/last_usage memo (2 s TTL) — reuse on burst calls
2) cache/statusline_snapshot — opt-in fast path
3) JSONL tail (64 KB reverse scan) — find last assistant message.usage
│ none available → ALLOW (fail-open)
▼
CacheThreshold axes:
- cache_hit_ratio_min (cache_read / (input + cache_read + cache_creation))
- cache_read_tokens_min (raw cache_read_input_tokens floor)
- cache_age_max_seconds (age of last assistant timestamp)
- compaction_used_max (total_input / context_window)
- rate_limit_5h_max (from statusline snapshot; rate-limit wording)
- rate_limit_7d_max (from statusline snapshot; rate-limit wording)
│ none tripped → ALLOW
▼
ScopedAllow override active? (/ar:cache ok …)
yes → consume + ALLOW
no → BLOCK with copy-paste override hints
5. Cross-CLI matrix
| Capability | Claude Code | Gemini CLI |
|---|---|---|
hook stdin transcript_path |
yes | yes |
message.usage.cache_read_* in JSONL |
yes | unknown schema; probe |
| Compaction event name | PreCompact / PostCompact / SessionStart(compact) |
PreCompress (advisory) / SessionStart |
cache_hit_ratio_min axis |
active | fail-open (no data) |
cache_read_tokens_min axis |
active | fail-open |
cache_age_max_seconds axis |
active | active |
compaction_used_max axis |
active (with snapshot) | active when total tokens available |
rate_limit_*_max axes |
only with statusline tap | unavailable |
/ar:cache status prints which axes are inactive for the current CLI.
6. Multiprocess safety
The gate uses session_state() — a single shared JSON file with prefixed
keys and filelock + atomic tempfile rename. All writes are serialised; reads
re-load inside the lock. Parallel hook invocations (e.g. rtk-spawned) inherit
the same _PARALLEL_GRACE_SECONDS = 1.0 s window that ScopedAllow already
uses. No new state file, no new lock.
7. Files
| Path | Role |
|---|---|
plugins/autorun/src/autorun/cache_guard.py |
Single-file feature (~500 LOC). |
plugins/autorun/tests/test_cache_guard.py |
Full test matrix (parser → multiprocess). |
plugins/autorun/commands/cache.md |
/ar:cache command definition. |
plugins/autorun/skills/cache/SKILL.md |
This file. |
8. Troubleshooting
- "Gate doesn't fire." Run
/ar:cache status— is it enabled? Are any axes configured? Set at least one axis (/ar:cache set ratio 0.5) after enabling. - "Blocked when I didn't want it."
/ar:cache ok 5mor/ar:cache off. - "Gemini says axes unavailable." Correct — Gemini CLI hooks do not surface
cache-token fields. Use
ageaxis instead; it works on both CLIs. - "I want the rich statusline numbers." Add one line to your own
statusline script:
printf '%s' "$INPUT" | autorun --cache-snapshot >/dev/null 2>&1 &.
9. Implementation reference
See plugins/autorun/src/autorun/cache_guard.py for parsing, usage detection,
block-message construction, and multiprocess-safe override handling. See
plugins/autorun/commands/cache.md for the user-facing command grammar.
Files in this skill
1cache skill questions
How do I install the cache skill in Claude Code?
Run npx degit ahundt/autorun/plugins/autorun/skills/cache ~/.claude/skills/cache. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the cache skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How do I enable cache protection?
You can enable it by running the command /ar:cache on. It is off by default.
What happens if the usage data is unavailable?
The system is designed to fail-open, meaning it will allow the command if usage data cannot be retrieved due to old versions or malformed data.
How can I temporarily bypass the cache block?
You can use the override command /ar:cache ok followed by a duration (e.g., 5m) or a specific number of tool uses.
Why is my cache gate not firing?
Check if it is enabled and if any axes are configured by running /ar:cache status.