SkillScope

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.

Table of contents

• Why
• Install
• Usage
• The .skills manifest
• How it works
• Commands
• FAQ
• Testing
• Contributing
• License

Why

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.

Install

npm install -g @arsyadal/skillscope

Or, for local development against this repo:

git clone https://github.com/arsyadal/SkillScope.git
cd SkillScope
npm link

Either way, this exposes the skil command globally. Requires Node.js 18 or later.

Usage

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 now

Typical 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

The .skills manifest

.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.

How it works

• Skill folders in ~/.claude/skills/ not listed in .skills get 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.

Commands

| 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 |

FAQ

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.

Testing

npm test

Uses 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).

Contributing

Issues and PRs welcome at github.com/arsyadal/SkillScope. Keep changes dependency-free where possible — the project intentionally has zero runtime dependencies.

License

MIT