🧊 skill-freeze

Save ~90% context tokens by freezing unused skills in Claude Code, Codex, Gemini CLI, and other AI coding agents.

One command. Zero dependencies. Full rollback.

npx skill-freeze setup

The Problem

AI coding agents (Claude Code, OpenAI Codex, Gemini CLI, OpenCode, Kiro) load every installed skill into your context window on every session. Each skill costs ~45 tokens just for its name and description.

| Skills Installed | Tokens Wasted / Session | Monthly Cost (est.) | |-----------------|------------------------|-------------------| | 50 | ~2,250 | Noticeable | | 100 | ~4,500 | Painful | | 200+ | ~9,000+ | Burning money 🔥 |

You use maybe 15 skills daily. The other 200 are dead weight.

How skill-freeze Works

Before:
~/.claude/skills/     → 264 skills → ALL loaded into context
~/.agents/skills/     → 150 skills → ALL loaded into context
                        Total: ~11,880 tokens/session 😱

After:
~/.claude/skills/     → 15 hot skills + skill-router → loaded
~/.claude/skills-cold/ → 249 frozen skills → NOT loaded
~/.agents/skills-cold/ → 150 frozen skills → NOT loaded
                        Total: ~720 tokens/session 🧊
                        Saved: ~94%

1. Freeze — moves low-frequency skills from skills/ to skills-cold/
2. Router — installs a single skill-router skill with a categorized index of everything frozen
3. Activate — need a frozen skill? One command creates a symlink to bring it back
4. Auto-cleanup — Stop hook removes temporary symlinks when your session ends

Quick Start

# Interactive setup — pick what to keep, freeze the rest
npx skill-freeze setup

# See what you saved
npx skill-freeze status

# Need a frozen skill temporarily?
npx skill-freeze activate scanpy

# Full rollback — restore everything
npx skill-freeze thaw

Commands

| Command | Description | |---------|-------------| | setup | Interactive: choose hot skills, freeze rest, install cleanup hook | | freeze | Freeze cold skills to cold storage (interactive) | | thaw | Full rollback — restore ALL frozen skills | | status | Show hot/cold counts and token savings estimate | | activate <name> | Temporarily activate a frozen skill via symlink | | deactivate <name> | Remove a temporary activation | | clean | Remove all temporary symlinks | | index | Regenerate the category index | | install-router | Install/update the skill-router SKILL.md | | install-hook | Add auto-cleanup Stop hook to settings.json |

How the Router Works

When you freeze skills, skill-freeze installs a skill-router — a single lightweight skill that contains a categorized tree index of all your frozen skills:

🧬 Science/Bio (52): scanpy · rdkit · biopython · esm · deepchem ...
📊 Data Science (30): polars · scikit-learn · pytorch-lightning · shap ...
💰 Finance/Quant (9): quant-market · alphaear-stock · okx-trader ...
🛠️ Dev Tools (25): github-actions-docs · vercel-deploy · sentry ...
🎨 UI/Design (9): figma · shadcn · ui-ux-pro-max ...
📝 Writing/Docs (15): article-writing · notion · pdf · pptx ...
🔍 Search/Research (8): agent-reach · paper-lookup · parallel-web ...
🎬 Media (6): imagegen · sora · speech · transcribe ...
🏗️ Infrastructure (6): homelab-cluster · modal · gstack ...
⚛️ Quantum/Physics (6): qiskit · cirq · pennylane · astropy ...
🏥 Clinical (6): pyhealth · pydicom · clinical-reports ...

Your AI agent sees this index and can find + activate any frozen skill by topic. Progressive disclosure — show the table of contents, not the entire book.

Compatibility

skill-freeze works with any AI coding agent that loads skills from the filesystem:

| Agent | Skill Directory | Supported | |-------|----------------|-----------| | Claude Code | ~/.claude/skills/ | ✅ | | OpenAI Codex | ~/.agents/skills/ | ✅ | | Gemini CLI | ~/.agents/skills/ | ✅ | | OpenCode | ~/.agents/skills/ | ✅ | | Kiro | ~/.agents/skills/ | ✅ | | Cursor | ~/.agents/skills/ | ✅ |

All these tools follow the Agent Skills open standard using ~/.agents/skills/. Claude Code also uses ~/.claude/skills/. skill-freeze handles both directories.

Auto-Detection

skill-freeze can automatically decide which skills to keep hot:

npx skill-freeze freeze
> auto    # keeps top 15 by usage frequency
> 20      # keeps top 20 by usage frequency

It reads your skill-usage.jsonl log (if available) and ranks skills by invocation count. No log? It keeps the first N alphabetically — you can always adjust later.

Requirements

• Node.js ≥ 18
• OS: Windows, macOS, Linux
• Windows uses junctions (no admin required), Unix uses standard symlinks

FAQ

No. Skills are moved, not deleted. npx skill-freeze thaw restores everything to the original location.

Yes — via the router. The agent reads the category index, identifies the needed skill, and either:

1. Runs npx skill-freeze activate <name> to create a symlink
2. Directly reads the cold SKILL.md content with Read()

System directories are auto-excluded and never frozen. The freeze command only targets user-installed skills.

• skill-freeze preserves everything — cold storage, not deletion
• The router provides a searchable index so you can find skills later
• One-command rollback with thaw
• Auto-cleanup hook keeps your hot directory clean between sessions

Yes. OMC's internal skills (under omc/) are auto-excluded from freezing. OMC's hook-based skill injection continues to work independently.

How Context Tokens Are Wasted

Claude Code (and similar tools) scan ~/.claude/skills/ and ~/.agents/skills/ at startup, then inject every skill's name + description into a <available_agent_skills> block in the system prompt. This block is included in every message — there's no config to filter, lazy-load, or group skills (Claude Code Issue #11045 proposed this; closed as not_planned).

skill-freeze solves this at the filesystem level: if the SKILL.md isn't physically present, the agent can't scan it.

Contributing

Issues and PRs welcome. See CONTRIBUTING.md.

License

MIT © 2233admin