claudepacks

Cut your Claude Code session overhead from ~7,000 to ~200 tokens. One command per project — pick exactly which skills and agents load, instead of all of them.

简体中文 · Changelog · Troubleshooting · Recipes · Architecture · Contributing · Releasing

Why

Claude Code injects metadata for every skill in ~/.claude/skills/ and every agent in ~/.claude/agents/ into the session preamble. With 50+ skills and a handful of agents installed globally — common once you accumulate tooling across multiple projects — that's ~7k tokens of overhead before you type a single character, in every conversation, in every project.

But most projects only need a handful of them. A backend API project doesn't need front-end design helpers. A data project doesn't need Docker deployment tools.

claudepacks moves your global skills and agents into a stash at ~/.claude/packs/, and each project's .claude/skills/ and .claude/agents/ hold symlinks to only what that project needs. You pick them with an interactive selector.

Before / after

~/.claude/skills/    (50 entries, ~6800 tokens loaded in every session)
~/.claude/agents/    (5  entries, ~600  tokens loaded in every session)

After claudepacks:

~/.claude/packs/                              (the stash — single source of truth)
├── skills/
│   ├── code-review/SKILL.md                  ← plain skill
│   ├── sql-helper/SKILL.md
│   └── devtools -> ~/.claude/skills/devtools ← source pack, symlinked in place
└── agents/
    ├── reviewer.md
    └── migrator.md

my-backend-project/.claude/skills/            (only what this project needs)
├── code-review  → ~/.claude/packs/skills/code-review/
└── sql-helper   → ~/.claude/packs/skills/sql-helper/

my-backend-project/.claude/agents/
└── reviewer.md  → ~/.claude/packs/agents/reviewer.md

Result: ~7000 tokens → a few hundred per conversation. Tokens you can spend on actual code.

Demo

Install

pip install claudepacks

Requires Python 3.9+. macOS / Linux only (curses TUI is not supported on Windows). The only runtime dependency is PyYAML.

First run — automatic migration

The first time you run claudepacks in any project, it offers to migrate your existing global skills and agents into the stash:

First-time setup: migrating to ~/.claude/packs/

Backups (full copy, originals preserved):
  ~/.claude/skills  →  ~/.claude/skills.bak-20260513-120000
  ~/.claude/agents  →  ~/.claude/agents.bak-20260513-120000

Target: ~/.claude/packs/
  skills/  (3 plain skill(s) → move)
    + code-review
    + sql-helper
    + debugger
  skills/  (1 source pack(s) → symlink in place)
    ⟶ devtools -> ~/.claude/skills/devtools
  agents/  (2 agent(s) → move)
    + reviewer.md
    + migrator.md

Proceed? [y/N]:

y runs it; N aborts with zero side effects. The whole pre-existing ~/.claude/skills/ and ~/.claude/agents/ are first copied to timestamped backups before any move — your data is recoverable.

You can also invoke it explicitly: claudepacks init.

Source pack handling

A skill directory with a top-level SKILL.md and nested sub-skills (each sub-dir holding its own SKILL.md) is recognized as a source pack. Migration symlinks these in place rather than moving them — wrappers and tooling that reference absolute paths inside the pack keep working.

Use

cd <your-project>
claudepacks

Opens an interactive selector grouped into 🤖 agent and 📦 skill.

State badges: ✓ on (green) / · off (dim). Pending changes are marked ✱ in yellow.

After applying, restart Claude Code to pick up the new project artifact set. The next /context should show a dramatically smaller Skills / Custom Agents footprint.

Layout

claudepacks/
├── LICENSE                  MIT
├── README.md                This file
├── README.zh-CN.md          Chinese
├── CHANGELOG.md             Release notes
├── CONTRIBUTING.md          Dev workflow + branch strategy
├── RELEASING.md             Release flow + SemVer policy + checklist
├── CLAUDE.md                Guidance for Claude Code in this repo
├── TODOS.md                 Deferred work, prioritized
├── pyproject.toml
├── docs/
│   ├── architecture.md      Design rationale + diagrams
│   ├── troubleshooting.md   Common issues + fixes (incl. zh-CN)
│   ├── recipes.md           Real-world workflows (incl. zh-CN)
│   └── demo.{gif,cast}      Demo assets
├── claudepacks/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py               Entry point — opens TUI / runs init
│   ├── core.py              Paths, artifact discovery, frontmatter
│   ├── migrate.py           First-time setup (~/.claude/{skills,agents} → packs/)
│   └── tui.py               Curses-based selector
└── tests/
    └── smoke.sh             End-to-end smoke tests

Status

v0.2.0. See CHANGELOG.

License

MIT — see LICENSE.