Skills Manager

A production-grade Model Context Protocol (MCP) server and CLI tool for managing AI agent skills across VS Code, Claude, Antigravity Desktop, Cursor IDE, and Codex.

npm version node version License: MIT Build Status

Overview

Skills Manager MCP provides intelligent, zero-configuration management of AI agent skills and bundles across your development environment. Whether you're working in VS Code with Copilot, Claude, Cursor IDE, Antigravity Desktop, or Codex, this tool automatically handles skill installation, caching, configuration merging, and version management.

Key Features

• 🚀 Zero-Config Setup — Automatic first-run initialization with platform-aware registration
• 🎯 Multi-Editor Support — Unified MCP registration for VS Code, Claude, Cursor IDE, Antigravity Desktop, and Codex
• 📦 Smart Caching — Global skill cache at ~/.ai-skills/cache/ eliminates redundant downloads
• 🔄 Config Merging — Intelligently combines project-specific and personal global skill collections
• 🏗️ Workspace Detection — Automatic project root discovery using multiple heuristics
• 📊 Metadata Tracking — Maintains .agents/skills-manager.json with versioning and schema migrations
• 🔍 Health Diagnostics — Built-in doctor command for troubleshooting
• 🛠️ Headless Installation — Perfect for CI/CD pipelines and unattended environments
• 📝 Full API — Comprehensive MCP tools for programmatic skill management

---

Table of Contents

• Requirements
• Installation
• Getting Started
• Multi-Editor Integration
  • VS Code
  • Claude Desktop
  • Claude Code
  • Cursor IDE
  • Codex CLI
  • Antigravity Desktop
• CLI Commands
• Configuration
• MCP Tools Reference
• Architecture
• Troubleshooting
• Development
• Support & License

---

Requirements

• Node.js: 20.0.0 or newer (LTS recommended)
• Operating System: Windows, macOS, or Linux
• Git: Required for skill repository cloning

The package enforces Node.js version requirements at runtime with a clear error message if an older version is detected.

---

Installation

Global Installation (Recommended)

Install globally to use the CLI and MCP server across all projects:

npm install -g skills-manager-mcp

Or with pnpm:

pnpm add -g skills-manager-mcp

Note: No npm postinstall scripts are required. The tool performs all setup automatically on first use.

Verification

Verify the installation:

skills-manager-mcp --version
skills-manager-mcp status

---

Getting Started

Automatic First-Run Setup

The tool automatically configures itself on first use:

skills-manager-mcp status

This single command:

1. Detects first-time installation
2. Creates global storage at ~/.ai-skills/
3. Initializes the skill cache
4. Auto-registers with all detected editors (VS Code, Claude, Cursor IDE, etc.)
5. Displays initialization summary

Sample Output:

Skills Manager MCP first-time setup detected...

✓ Global storage initialized: ~/.ai-skills
✓ Skills cache ready: ~/.ai-skills/cache
✓ Antigravity MCP registered: ~/.gemini/antigravity-ide/mcp.json
✓ VS Code MCP registered: ~/.config/Code/User/mcp.json
✓ Cursor IDE MCP registered: ~/.config/Cursor/User/mcp.json
✓ Claude Code MCP registered: ~/.claude.json
✓ Codex MCP registered: ~/.config/Codex/User/mcp.json
✓ Server executable path: ~/.local/share/npm/node_modules/skills-manager-mcp/dist/index.js

Initialization complete.

Subsequent runs skip initialization instantly.

Manual Setup

To re-run setup or register with additional editors:

skills-manager-mcp setup

---

Multi-Editor Integration

VS Code Integration

The MCP server automatically registers with all VS Code variants during initialization.

Configuration: mcp.json (automatically updated)

Supported Variants:

• VS Code (stable)
• VS Code Insiders
• VSCodium

Paths by Platform:

• Windows: %APPDATA%\Code\User\mcp.json
• macOS: ~/Library/Application Support/Code/User/mcp.json
• Linux: ~/.config/Code/User/mcp.json

Configuration Format:

{
  "servers": {
    "skills-manager": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/skills-manager-mcp/dist/index.js"]
    }
  }
}

Usage in VS Code:

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Search "MCP: List Servers"
3. Select and start skills-manager
4. Use skills in Copilot Chat agent mode

Claude Desktop Integration

Claude Desktop (the GUI application) uses claude_desktop_config.json with the mcpServers top-level key.

Configuration: claude_desktop_config.json (automatically updated)

Paths by Platform:

• Windows (Standard): %APPDATA%\Claude\claude_desktop_config.json
• Windows (Store / MSIX): %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration Format:

{
  "mcpServers": {
    "skills-manager": {
      "command": "node",
      "args": ["/path/to/skills-manager-mcp/dist/index.js"]
    }
  }
}

Claude Code Integration

Claude Code (the terminal-based CLI agent) uses ~/.claude.json for user-level tools and .mcp.json for project-scoped tools.

Configuration: ~/.claude.json (automatically updated)

Paths by Platform:

• All Platforms: ~/.claude.json
• Windows: %USERPROFILE%\.claude.json
• Project-level: .mcp.json (in project root)

Configuration Format:

{
  "preferences": { ... },
  "mcpServers": {
    "skills-manager": {
      "command": "node",
      "args": ["/path/to/skills-manager-mcp/dist/index.js"]
    }
  }
}

For detailed Claude setup instructions, see CLAUDE_SETUP.md.

Cursor IDE Integration

Cursor IDE uses mcp.json with the mcpServers top-level key.

Configuration: ~/.cursor/mcp.json (automatically updated)

Paths by Platform:

• Global / User: ~/.cursor/mcp.json (all platforms)
• Project-level: .cursor/mcp.json (in project root)

Configuration Format:

{
  "mcpServers": {
    "skills-manager": {
      "command": "node",
      "args": ["/path/to/skills-manager-mcp/dist/index.js"]
    }
  }
}

Codex CLI Integration

OpenAI Codex CLI uses config.toml in TOML format with [mcp_servers.<name>] tables.

Configuration: ~/.codex/config.toml (automatically updated)

Paths by Platform:

• Global / User: ~/.codex/config.toml (all platforms)
• Project-level: .codex/config.toml (in project root)

Configuration Format (TOML):

[mcp_servers.skills-manager]
command = "node"
args = ["/path/to/skills-manager-mcp/dist/index.js"]

Antigravity Desktop Integration

Antigravity Desktop is the primary MCP target with specialized registration.

Configuration Files:

• ~/.gemini/config/mcp_config.json — Primary
• ~/.gemini/antigravity-ide/mcp.json — Secondary

Configuration Format:

{
  "mcpServers": {
    "skills-manager": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/skills-manager-mcp/dist/index.js"]
    }
  }
}

---

CLI Commands

skills-manager-mcp status

Displays a comprehensive status dashboard including configuration, cache statistics, MCP registration status across all editors, workspace detection, and installed skills.

Usage:

skills-manager-mcp status [projectPath]

Output Includes:

• Global configuration presence
• Cache skill count
• MCP registration status per editor
• Detected workspace and detection source
• List of installed skills in workspace

skills-manager-mcp doctor

Runs comprehensive diagnostic health checks on installation, configuration, cache, and MCP registration.

Usage:

skills-manager-mcp doctor

Checks Performed:

• ✓ dist/index.js exists and is valid
• ✓ Antigravity configuration file
• ✓ MCP path validity and file existence
• ✓ VS Code MCP registration
• ✓ Claude MCP registration
• ✓ Cursor IDE MCP registration
• ✓ Codex MCP registration
• ✓ Global cache availability
• ✓ skills.config.json validity

Sample Output:

Skills Manager Doctor

✓ dist/index.js exists
✓ Antigravity configuration exists
✓ MCP path valid
✓ VS Code MCP registered
✓ Claude MCP registered
✓ Global cache available
✓ skills.config.json valid

Everything is healthy.

skills-manager-mcp bootstrap [projectPath]

Initializes a project workspace for skill management.

Usage:

skills-manager-mcp bootstrap [projectPath]

Operations:

1. Detects or validates workspace root
2. Creates .agents/skills/ directory structure
3. Loads and merges project and global skill configurations
4. Installs all configured skills (from cache or remote repository)
5. Creates .agents/skills-manager.json metadata tracker
6. Generates detailed installation report

Output Example:

Workspace: /path/to/project [Source: package.json]

Installed: 3
- find-skills
- frontend-design
- mattpocock-skills (bundle)

Skipped: 0
Failed: 0

skills-manager-mcp sync [projectPath]

Synchronizes workspace skills with global personal collection.

Usage:

skills-manager-mcp sync [projectPath]

Operations:

• Fetches latest global skill configuration
• Re-downloads all configured skills (updates)
• Updates metadata and cache
• Validates installation integrity

Use Case: When you've updated ~/.ai-skills/skills.config.json globally and want to apply changes across all projects.

skills-manager-mcp install [projectPath]

Installs only missing skills, skipping already-installed ones.

Usage:

skills-manager-mcp install [projectPath]

Useful for:

• Adding new skills to an existing project
• Recovering from partial installations
• CI/CD pipelines requiring idempotent operations

skills-manager-mcp remove <skill1> [skill2] [...skillN]

Removes specified skills from the project workspace.

Usage:

# Remove single skill
skills-manager-mcp remove find-skills

# Remove multiple skills
skills-manager-mcp remove find-skills frontend-design mattpocock-skills

# Remove from both filesystem and config (prevents re-installation)
skills-manager-mcp remove find-skills --from-config
skills-manager-mcp remove find-skills -c

Options:

• --from-config, -c — Also remove skill entries from skills.config.json

Output Example:

Removed: 1
- find-skills

Skipped: 0
Failed: 0

skills-manager-mcp setup

Manually re-run setup and MCP registration for all editors.

Usage:

skills-manager-mcp setup

Useful for:

• Re-registering after editor installation
• Fixing MCP configuration issues
• Manual initialization on different platforms

---

Configuration

Global Skills Collection (~/.ai-skills/skills.config.json)

Manage your master skills collection globally:

{
  "skills": [
    {
      "name": "find-skills",
      "repository": "https://github.com/vercel-labs/skills",
      "skill": "find-skills"
    },
    {
      "name": "frontend-design",
      "repository": "https://github.com/anthropics/skills",
      "skill": "frontend-design"
    },
    {
      "type": "bundle",
      "name": "mattpocock-skills",
      "repository": "https://github.com/mattpocock/skills"
    }
  ]
}

Project-Specific Configuration (./skills.config.json)

Override or extend global configuration per project:

{
  "skills": [
    {
      "name": "tdd",
      "repository": "https://github.com/custom/skills",
      "skill": "tdd"
    }
  ]
}

Merge Behavior: Project skills with matching name override global skills.

Configuration Schema

Field	Type	Required	Description
name	string	✓	Unique skill identifier (alphanumeric, hyphens, underscores)
repository	string	✓	Git HTTPS repository URL containing skill(s)
skill	string		Folder name in repository; defaults to name
type	string		'skill' (default) or 'bundle'

Metadata Tracker (.agents/skills-manager.json)

Automatically maintained project metadata:

{
  "version": "1.6.0",
  "updatedAt": "2026-08-14",
  "migrations": {
    "1.0": "completed",
    "1.6.0": "completed"
  },
  "skills": {
    "find-skills": {
      "type": "skill",
      "source": "https://github.com/vercel-labs/skills",
      "installedAt": "2026-08-14",
      "version": "latest"
    }
  }
}

---

MCP Tools Reference

When running within VS Code (Copilot Chat agent mode), Claude, or Antigravity Desktop, the following MCP tools are available:

Tool	Purpose
get_workspace_info	Diagnose workspace detection and configuration
bootstrap_project	Initialize project with skills
sync_skills	Update skills from global collection
install_skills	Install missing skills only
remove_skills	Remove skills from project
list_installed_skills	Audit current installation
check_missing_skills	Validate skill completeness

---

Architecture

Directory Structure

~/.ai-skills/
├── skills.config.json          # Global skill collection
├── config.json                 # Workspace detection settings
└── cache/
    ├── find-skills/
    └── mattpocock-skills/

<project>/
├── .agents/
│   ├── skills/                 # Installed skills
│   └── skills-manager.json     # Installation metadata
└── skills.config.json          # Project config (optional)

Design Patterns

• Layered Architecture — Clear separation between CLI, orchestration, services, and utilities
• Idempotent Operations — All commands are safe to run multiple times
• Lazy Initialization — Zero-config setup on first use
• Configuration Merging — Smart override semantics for project + global configs
• Schema Versioning — Automatic metadata migrations for forward compatibility

---

Troubleshooting

MCP Server Not Connecting

Symptom: Editor doesn't recognize the MCP server.

Solution:

1. Run diagnostics:

   skills-manager-mcp doctor
   

2. Re-run setup:

   skills-manager-mcp setup
   

3. Restart the editor
4. Check file permissions on MCP config files

Skills Installation Fails

Symptom: Error during bootstrap or install.

Solution:

1. Verify workspace detection:

   skills-manager-mcp status
   

2. Check network connectivity (repositories must be accessible)
3. Validate skills.config.json JSON syntax
4. Ensure repository URLs use HTTPS
5. Review doctor output for configuration issues

Workspace Not Detected

Symptom: status shows incorrect or no workspace.

Solution:

1. Run with explicit path:

   skills-manager-mcp bootstrap /path/to/project
   

2. Ensure project contains a marker file: package.json, .git, pnpm-lock.yaml, etc.
3. Check ~/.ai-skills/config.json for custom detection settings

Cache Issues

Symptom: Skill installation is slow or cached versions are stale.

Solution:

1. Clear cache manually:

   rm -rf ~/.ai-skills/cache
   

2. Rebuild cache:

   skills-manager-mcp sync
   

---

Development

Prerequisites

• Node.js 20.0.0+
• pnpm (or npm)
• TypeScript

Setup & Build

git clone https://github.com/your-org/skills-manager-mcp.git
cd skills-manager-mcp
pnpm install
pnpm run build

Testing

# Run tests
pnpm test

# Watch mode
pnpm test:watch

Project Structure

src/
├── cli.ts                  # CLI entry point
├── index.ts               # MCP server entry point
├── skillManager.ts        # Core orchestration
├── commands/              # CLI command handlers
└── services/              # Platform-specific services
    ├── antigravityRegistry.ts
    ├── vscodeRegistry.ts
    ├── claudeCodeRegistry.ts
    ├── cursorRegistry.ts
    └── codexRegistry.ts

---

Support & License

Documentation

• Claude Setup Guide — Detailed Claude integration instructions
• Configuration Reference — Skills config schema
• Architecture Overview — System design and data flow

Issues & Feedback

Report issues on GitHub Issues.

License

MIT License — Copyright © 2024-2026. See LICENSE for details.

Security & Privacy

• No telemetry — Your usage remains private
• Local-only operation — All processing happens on your machine
• No automatic updates — Manual npm updates only
• Unencrypted configs — Treat ~/.ai-skills/ like sensitive configuration

---

Questions? Consult the CLAUDE_SETUP.md guide or open an issue on GitHub.