SkillsMap

Universal CLI tool for managing AI agent skills across Cursor, Claude, Windsurf and 40+ AI agents.

Features

• 🚀 Universal Agent Support: Automatically detects and supports Cursor, Claude, and Windsurf
• 🔗 Symlink-based Distribution: Skills stored once in .agents/skills/, linked to all agents
• 📦 Multiple Source Types: Install from GitHub (user/repo), URLs, or local paths
• 🔍 Smart Discovery: Automatically finds SKILL.md files in repositories
• ✅ Metadata Validation: Ensures skills have required name and description fields

Installation

npm install -g skillsmap

Usage

Add a skill from GitHub

# Short format
skillsmap add user/repo

# With path
skillsmap add user/repo/path/to/skill

# Full URL
skillsmap add https://github.com/user/repo

Add a skill from local path

skillsmap add ./path/to/skill
skillsmap add /absolute/path/to/skill

List installed skills

skillsmap list

Show environment info

skillsmap info

How It Works

1. Universal Skills Directory

All skills are stored in .agents/skills/ (the "Universal Path"). This ensures:

• Skills are stored only once
• Easy management and updates
• Consistent structure across projects

2. Agent Detection

SkillsMap automatically detects which AI agents are present by checking for:

• .cursor/ - Cursor IDE
• .claude/ - Claude Desktop
• .windsurf/ - Windsurf

3. Symlink Distribution

When you add a skill, SkillsMap:

1. Downloads/copies the skill to .agents/skills/[skill-name]/
2. Creates symlinks in each detected agent's skills directory
3. Example: .cursor/skills/my-skill → .agents/skills/my-skill

Windows Note: On Windows, you need either:

• Run as Administrator, or
• Enable Developer Mode in Windows Settings

4. Skill Discovery Algorithm

SkillsMap searches for skills in this order:

1. Root SKILL.md
2. skills/ folder
3. Recursive search in subdirectories (max depth: 2)

A valid skill must have a SKILL.md file with frontmatter:

---
name: My Skill
description: A helpful skill for doing X
version: 1.0.0
tags: [ai, automation]
---

# Skill content here...

Architecture

Built with modern tools:

• Commander: CLI framework
• Ink: React for CLI (interactive UI)
• simple-git: Git operations
• gray-matter: YAML frontmatter parsing
• tsup: Fast TypeScript bundler
• chalk: Terminal colors
• ora: Elegant spinners

Project Structure

skillsmap/
├── src/
│   ├── commands/
│   │   ├── add.ts       # Add skill command
│   │   └── list.ts      # List skills command
│   ├── utils/
│   │   ├── agents.ts    # Agent detection
│   │   ├── parser.ts    # SKILL.md parsing
│   │   ├── source.ts    # Source parsing
│   │   └── symlink.ts   # Symlink management
│   ├── types.ts         # TypeScript types
│   └── index.ts         # CLI entry point
├── package.json
├── tsconfig.json
└── tsup.config.ts

Development

# Install dependencies
npm install

# Development mode (watch)
npm run dev

# Build
npm run build

# Type check
npm run typecheck

# Test locally
npm start -- add user/repo

Examples

Install a skill from GitHub

skillsmap add anthropics/claude-skills

Install from a specific path in a repo

skillsmap add vercel/next.js/.claude-plugin/plugins/cache-components

Check what's installed

skillsmap list

Output:

📦 Installed Skills (3):

  ✓ Cache Components
    Expert guidance for Next.js Cache Components
    Version: 1.0.0
    Tags: nextjs, performance
    Path: /Users/you/project/.agents/skills/cache-components

  ✓ TypeScript Helper
    Advanced TypeScript utilities
    Path: /Users/you/project/.agents/skills/typescript-helper

License

MIT