Toggle Claude Code skills on a per-project basis so you never hit the discovery ceiling or pay constant token tax for skills the current project doesn't need.
Claude Code loads the name + description of every installed skill into context on every turn, capped at ~1% of the context window (~8,000 characters). Install a large skill collection (e.g. a CLI tool that ships dozens of skills) and descriptions start truncating — the agent can no longer tell what a skill does, so it stops using it. Even skills that do fit still cost tokens on every turn of every project, whether or not that project ever needs them.
SkillScope keeps your full skill library on disk but only exposes the
subset a given project actually needs, by moving the rest out of
~/.claude/skills/ into a sibling ~/.claude/skills-disabled/
directory. Nothing is deleted; every move is reversible.
npm install -g @arsyadal/skillscopeOr, for local development against this repo:
git clone https://github.com/arsyadal/SkillScope.git
cd SkillScope
npm linkEither way, this exposes the skil command globally. Requires Node.js
18 or later.
In any project directory:
skil init # scaffold ./.skills from your currently active skills
skil apply # enable only the skills listed in ./.skills
skil list # show what's active vs disabled right nowTypical flow when starting a new project:
cd my-react-app
skil list # see everything you have installed
echo "react-best-practices" >> .skills
echo "composition-patterns" >> .skills
skil apply # only those two stay active here
git add .skills # share the same skill set with your team.skills is a plain text file in your project root, one skill name
per line. Blank lines and lines starting with # are ignored:
# frontend project
react-best-practices
composition-patterns
ui-ux-pro-max
Commit .skills to your repo so the whole team gets the same active
skill set when they run skil apply.
- Skill folders in
~/.claude/skills/not listed in.skillsget moved to~/.claude/skills-disabled/. - Skill folders in
~/.claude/skills-disabled/that ARE listed get moved back. - Symlinked skills (e.g. system-level skills installed elsewhere) are left untouched — SkillScope only touches real directories, never symlinks.
- Name collisions and unknown skill names are reported as warnings, never silently dropped or overwritten.
| Command | Effect |
|---|---|
skil init |
Write ./.skills from your currently active skill folders |
skil apply |
Enable only skills in ./.skills, disable everything else |
skil list |
Print active vs disabled skills |
skil disable-all |
Move every active skill to disabled |
skil enable-all |
Move every disabled skill back to active |
skil --version |
Print the installed version |
skil --help |
Print usage |
Does this delete any skills?
No. Every operation is a filesystem move (rename) between two
directories. Nothing is ever deleted.
What happens to skills that are symlinks? They're left alone. SkillScope only moves real directories, so system-level or externally-managed skills installed as symlinks are never touched.
What if two skills have the same folder name in both directories? SkillScope skips the move and prints a warning rather than overwriting either one.
Does this work with Cursor, Copilot, or other Agent Skills–compatible
tools?
Any tool that reads skills from a folder on disk works the same way —
point ACTIVE_DIR/DISABLED_DIR (see lib/skillscope.js) at its
skills directory if it differs from Claude Code's default.
npm testUses Node's built-in test runner (node:test) against a
temp-directory sandbox — no dependencies, no touching your real
~/.claude/skills/. CI runs the suite on Ubuntu, macOS, and Windows
across Node 18/20/22 (see .github/workflows/test.yml).
Issues and PRs welcome at github.com/arsyadal/SkillScope. Keep changes dependency-free where possible — the project intentionally has zero runtime dependencies.
MIT