Skill manager

Skill forhadkhan/skill-manager/skills/skill-manager

Three-tier activation for Claude Code skills, subagents, commands & workflows — keep a big library dormant, activate only what each project needs. Stdlib-only, security-audited, MIT.

Install

npx -y skills add forhadkhan/skill-manager --skill skill-manager

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Three-tier activation manager for agent assets (skills, subagents, commands, workflows): keep a large library dormant at zero context cost and activate only what each project needs. Use whenever the user wants to enable, disable, activate, or organize skills or agents; asks which skills are active or loaded; complains about context overhead, bloat, or token cost from installed skills; wants to install or import many skills or a skill pack without them loading everywhere; starts work in a project whose skills haven't been configured; or says things like "set up skills for this project", "skill status", "add/remove a skill here", "clean up my skills". Also use right after installing new skills to decide their tier.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

8.2 KB, as published. Nobody here has run it

Skill Manager

Every skill and subagent installed globally adds its description to the context of every session, in every project. The cost is bounded (agent hosts budget the listing), but the bound is the trap: with many assets installed, descriptions get truncated to fit, auto-triggering degrades for everything, and irrelevant entries become selection noise. The fix is scoped activation — an asset should cost context only where it's useful.

The three-tier model

Tier	Location	Context cost	Belongs here
Library (dormant)	`~/.agents/library/<kind>/`	zero	Everything. Grows freely.
Global (always on)	`~/.claude/<kind>/`	every session	Universal tools only — keep under ~8
Project (scoped)	`<project>/.claude/<kind>/`	that project's sessions	Whatever the project's stack needs

Kinds: skills (directories), agents, commands, workflows (single files). Activation = presence: a symlink where possible, or a tracked copy (hash-recorded in a manifest, so drift is detectable and sync-able).

The library deliberately lives at ~/.agents/library/, not ~/.agents/skills/ — several agent CLIs (Gemini, Cursor, Codex, Zed) now auto-scan ~/.agents/skills/, so assets stored there are not dormant on multi-agent machines.

The engine

All mechanics go through scripts/skillmgr.py (Python 3.8+, stdlib only, no network, no subprocess). Run commands with --json when you need to parse results:

python3 <skill-dir>/scripts/skillmgr.py <command> [--kind skills|agents|commands|workflows] [--json]

Command	Purpose
`scaffold`	create library layout + config (idempotent)
`index` / `index --check`	rebuild the library index / report staleness
`status [--kind all] [--project DIR]`	every asset's tier + problems needing attention
`detect [--project DIR]`	stack signals: manifests, languages, deps, infra, git-ness
`link NAME... --tier global\|project [--copy]`	activate (symlink, else tracked copy)
`unlink NAME... --tier ... [--force]`	deactivate; refuses foreign/modified content without --force
`adopt NAME... --tier ... [--relink] [--force]`	move real content into the library, transactionally (batch OK; `--relink` keeps it active, plain adopt = adopt + demote in one step; refuses to drop embedded symlinks without --force)
`import SRC [--name N] [--kind ...]`	copy an external asset in (single files need a file kind; embedded symlinks are stripped)
`sync --tier ... [--force]`	refresh drifted tracked copies from the library
`doctor [--fix] [--project DIR]`	find/repair dangling links, orphans, drifted/modified copies, corrupt state
`uninstall [--project DIR] [--all]`	remove managed activations — global tier by default, only the project's with `--project`, both with `--all`; library untouched

Every mutating command supports --dry-run. The engine handles mechanics; you supply judgment: which assets matter here, and what to ask the user.

Workflows

`status` — what's active where

Run status (it auto-detects the project when the cwd has a .claude/ dir; --project overrides). Summarize by tier; surface the attention entries with their built-in hints — including copied-drifted (library moved ahead of a copy; sync fixes) and copied-modified (local edits; decide between sync --force and keeping them). Offer doctor --fix for dangling links.

`init` — first-time setup and migration

This is the critical path for users who already have many skills. Never lose data; prefer --dry-run previews before mutating.

scaffold, then status --kind all to see the existing landscape.
Existing global assets: real directories/files get adopt --tier global --relink (content moves to the library, activation stays). Existing symlinks into some other store (e.g. ~/.agents/skills/ from the npx skills CLI): leave the store in place, import each asset into the library, then replace the old link via unlink --force
- link — or, if the user prefers the npx-skills store as-is, manage only new assets and say so plainly.
Interview: propose a minimal always-on set (this skill, skill-creation and discovery tools, anything genuinely used in every project). One question, their context budget, their call.
Demote the rest (unlink from global). Remind: everything stays in the library, one link away; changes land in new sessions.
Plugin packs (marketplace installs): do not move their files. Gate them per-project with enabledPlugins in settings.json instead — see references/mechanisms.md.

`setup` — configure a project

index (cheap — always refresh), detect --project DIR, then read <library>/index.json.
Match signals against asset descriptions across all kinds. Be honest: a Dockerfile alone doesn't justify kubernetes tooling. Drop candidates already active in the global tier. If the global tier is bloated (well over ~8), suggest init.
Bundle every decision into one exchange: a multi-select of proposed assets (include near-misses you rejected so the user can add them), plus — only if detect reported a git repo — personal vs team: personal = links + gitignore .claude/ additions (say so before editing .gitignore); team = link --copy
- commit, refreshed later with sync. Default personal.
link the chosen set with --tier project. Show final status --project.
Say when it lands: typically the next session; some builds hot-reload watched directories — check the live listing before promising either. Suggest verifying the assets appear (e.g. /skills or asking Claude); host loaders have had symlink-discovery regressions, and if one bites, link --copy is the fallback.

`add` / `remove` — manual toggles

Map to link / unlink. Default tier: project when inside one, else global. On name misses, check the index for near-matches; offer import for assets that exist elsewhere on disk.

`import` — grow the library

Local dir/file: import SRC. Repo: clone to a temp dir, import each asset, delete the clone. Plugin packs: prefer per-project enabledPlugins; import individual pieces only when the license permits.

Safety rules

The library is sacred: nothing in this skill ever deletes or edits library content. Deactivation removes links/tracked copies in tier directories only.
Never unlink --force or sync --force without telling the user what will be discarded; prefer showing the --dry-run output first.
Don't edit .gitignore, settings files, or anything outside tier directories without saying so first.
If a command errors, read its message — the engine's errors are specific (traversal-safe names, case collisions, lock contention) and usually name the fix.
In managed/enterprise environments, admin policy can override or block local assets entirely; if assets don't load despite correct linking, say so and point at references/mechanisms.md.

Platform notes

Windows without Developer Mode can't create symlinks — the engine silently falls back to tracked copies; nothing for you to do, but mention sync for copy freshness after library updates. Filesystem assets only load in Claude Code CLI/desktop/IDE surfaces, not claude.ai web or mobile. Deeper facts: references/mechanisms.md.