skillsmanager

A CLI tool for managing AI agent skills with proper namespace resolution. Prevents skill name conflicts when installing from multiple repositories, supports multiple agents (Claude Code, Cursor, Kiro, etc.), and tracks updates via remote hash comparison.

Heads up — this project is built around evobug internal requirements and will change frequently and without warning. Breaking changes are expected. If you want a stable tool, fork it or pin a commit.

Scope: manages skills and Claude Code plugins. When add sees a .claude-plugin/plugin.json in the target repo, the plugin is auto-installed into a local marketplace alongside any loose skills.

Credit & relationship to Vercel skills: inspired by and interoperable with Vercel Labs' skills CLI (MIT). skillsmanager is an independent reimplementation — it does not vendor, fork, or copy any of their source. It can migrate from an existing Vercel skills install by reading the .skill-lock.json file format. Huge thanks to the Vercel team for the original concept and ecosystem.

The Problem

AI coding agents (Claude Code, Cursor, etc.) use "skills" — markdown prompt files that extend agent capabilities. Skills come from GitHub repos and get installed into agent-specific directories. When two repos provide a skill with the same name (e.g., frontend-design), they clash in the slash command menu with no way to distinguish them.

skillsmanager solves this by auto-namespacing skills on install (impeccable:frontend-design, marketing:copywriting), rewriting cross-references, and managing the full lifecycle.

Install

# Clone
git clone https://github.com/evobug-com/skillsmanager.git
cd skillsmanager

# Install dependencies
bun install

# Or run directly without linking:
bun run src/index.ts <command>

Global CLI Setup (Linux / macOS)

After bun install, create a launcher in ~/.bun/bin/ (which should already be in your PATH after installing Bun):

cat > ~/.bun/bin/skillsmanager <<'EOF'
#!/usr/bin/env bash
exec bun run "$HOME/projects/skillsmanager/src/index.ts" "$@"
EOF
chmod +x ~/.bun/bin/skillsmanager

Replace $HOME/projects/skillsmanager with wherever you cloned the repo. If ~/.bun/bin is not in your PATH, add this to your shell rc (~/.bashrc, ~/.zshrc):

export PATH="$HOME/.bun/bin:$PATH"

Then skillsmanager works from anywhere.

Global CLI Setup (Windows)

After bun install, create launcher scripts in ~/.bun/bin/ (which should be in your PATH):

Replace <path-to-repo> below with the absolute path to your cloned repo (e.g., C:\src\skillsmanager).

For bash / Git Bash:

REPO="<path-to-repo>"
cat > ~/.bun/bin/skillsmanager <<EOF
#!/usr/bin/env bash
exec bun run "$REPO/src/index.ts" "\$@"
EOF

For PowerShell / cmd:

set REPO=<path-to-repo>
echo @echo off > %USERPROFILE%\.bun\bin\skillsmanager.cmd
echo bun run "%REPO%\src\index.ts" %%* >> %USERPROFILE%\.bun\bin\skillsmanager.cmd

Then skillsmanager works from anywhere.

Commands

Command	Description
add <owner/repo>	Install skills from a GitHub repo
remove <owner/repo>	Remove all skills from a repo
list	List installed skills by repo/namespace
update [owner/repo]	Check for remote updates and reinstall changed skills
check	Detect namespace conflicts and show status
fix [owner/repo]	Retroactively namespace existing skills
migrate [owner/repo]	Migrate from the vercel skills CLI
repair	Fix stale /command cross-references and reconcile plugins (install any plugin from an already-tracked repo that isn't in the lock yet)

Usage

Adding skills from a repo

skillsmanager add pbakaus/impeccable

On first run, you'll be prompted to:

1. Select agents — which agents should skills be available to (auto-detects installed agents)
2. Choose install mode — copy files (recommended) or symlink
3. Pick a namespace — suggested based on repo name, or enter a custom one

Skills are installed to ~/.agents/skills/ (canonical) and copied/linked to each agent's skills directory.

Migrating from vercel skills CLI

# Interactive — prompts for namespace per repo
skillsmanager migrate

# Auto-accept suggested namespaces
skillsmanager migrate --yes

# Re-migrate everything as copies (fix symlink issues)
skillsmanager migrate --force --copy --yes

Checking for conflicts

skillsmanager check

Shows namespace conflicts, repos without namespaces, and a summary of installed skills.

Updating skills

# Update all repos
skillsmanager update

# Update a specific repo
skillsmanager update pbakaus/impeccable

Compares the remote Git tree SHA with the stored hash. Only re-installs when changes are detected.

Fixing cross-references

# Scan for stale /command references across all skills
skillsmanager repair --dry-run

# Fix them
skillsmanager repair

Detects references like /frontend-design that should now be /impeccable:frontend-design and rewrites them.

Options

Flag	Description
--namespace <name>	Override the auto-derived namespace
--no-namespace	Install without namespace (not recommended)
--copy	Copy files instead of symlinking (persisted)
--agent <ids>	Comma-separated agent IDs (e.g., claude-code,cursor)
--force	Re-process already-managed repos
--dry-run	Preview changes without applying them
--yes, -y	Skip confirmation prompts

How It Works

Namespace Resolution

1. Derives namespace from the repo name: pbakaus/impeccable → impeccable, coreyhaines31/marketingskills → marketing
2. Strips common suffixes: -skills, -skill, -pack, -plugin
3. If conflicts exist with already-installed skills, namespaces ALL skills from the repo
4. Skips already-namespaced skills (those with : in the name field)

Skill Discovery

Searches cloned repos in priority order:

1. .agents/skills/*/SKILL.md
2. .claude/skills/*/SKILL.md
3. skills/*/SKILL.md
4. **/SKILL.md (recursive fallback)

Cross-Reference Rewriting

When namespacing, rewrites both:

• The name: field in SKILL.md frontmatter
• Intra-pack /command references (e.g., /audit → /impeccable:audit)

Storage

• Canonical skills: ~/.agents/skills/ — one copy per skill
• Agent directories: ~/.claude/skills/, ~/.cursor/skills/, etc. — copies or symlinks
• Lock file: ~/.agents/.skillsmanager-lock.json — tracks repos, namespaces, hashes, settings
• Vercel lock (read-only): ~/.agents/.skill-lock.json — read for migration, cleaned after

Supported Agents

Claude Code, Cursor, Windsurf, Cline, Codex, Kiro, Amp, OpenCode, Gemini CLI, Warp, GitHub Copilot.

Plugin support

When skillsmanager add <owner/repo> detects a .claude-plugin/plugin.json at the repo root (or one directory deep), it:

1. Installs the plugin into a local marketplace at ~/.agents/.skillsmanager-marketplace/plugins/<name>/.
2. Rewrites plugin.json name (and all intra-plugin /command cross-references) to use the chosen namespace, so plugins from different repos never collide.
3. Stamps plugin.json version as <upstream>+sm.<content-hash> — identical upstream content keeps the stamp stable (Claude reuses its cache), changed content rotates it (Claude refreshes).
4. Regenerates ~/.agents/.skillsmanager-marketplace/.claude-plugin/marketplace.json.
5. Patches ~/.claude/settings.json to register the marketplace in extraKnownMarketplaces and flip the plugin on in enabledPlugins. No manual /plugin marketplace add step needed — restart Claude Code and the plugin is live.
6. Also installs any loose skills from the repo that live outside the plugin directory, using the existing skill flow.

Plugins are Claude Code only — other agents don't consume the plugin format.

Lifecycle

• add — installs the plugin, auto-enables it in settings. Restart Claude Code to pick it up.
• update — when the upstream tree hash changes, re-runs install, wipes ~/.claude/plugins/cache/skillsmanager/<name>/ so the next Claude launch copies the fresh content, and re-asserts the settings entry in case it was cleared manually.
• remove — uninstalls the plugin directory, wipes Claude's cache for it, removes the enabledPlugins entry, and drops the whole skillsmanager marketplace registration when the last plugin is removed.

Settings patching only touches the extraKnownMarketplaces.skillsmanager key and the <plugin>@skillsmanager entries inside enabledPlugins. Anything else in your settings file is left alone.

Dependencies

• Bun runtime
• yaml — YAML frontmatter parsing
• @clack/prompts — interactive CLI UI
• picocolors — terminal colors

License

MIT