skill-manager

Skill Manager (skm)

CLI tool for managing agent skills via directory symlinks.

Features

• Discover skill directories from configured source paths
• Create directory symlinks to manage skills across projects
• Interactive selection with multi-select interface
• Source management - configure multiple skill repositories
• GitHub URL support - automatically clone GitHub repositories
• Multi-type skills - support for universal and platform-specific skills, including Codex
• Cross-platform with Windows fallback (copy if symlink fails)

Installation

pnpm install -g skill-manager

Or from source:

cd packages/skill-manager
pnpm install
pnpm build
pnpm link --global

Quick Start

1. Add a source directory

You can add either local directories or GitHub URLs:

# Local directory
skm source add ~/my-skills-repo
skm source add /path/to/another/skills-repo

# GitHub URL (HTTPS)
skm source add https://github.com/user/skills.git

# GitHub URL (SSH - automatically converted to HTTPS)
skm source add git@github.com:user/skills.git

When you add a GitHub URL, skill-manager will:

• Automatically convert SSH format to HTTPS if needed
• Clone the repository using repo-do (rpd)
• Use the local path as the source

2. List configured sources

skm source ls

3. List available skills

skm list
# or
skm ls

4. Add skills to your current project

cd /path/to/your/project
skm add

This will:

• Scan all configured sources for skills
• Show an interactive multi-select list
• Create symlinks in the selected project skill directory (Codex uses ./.agents/skills/)

5. Search for specific skills

skm search debugging

6. Remove skills from current project

skm remove
# or
skm rm

7. View configuration

skm config

Source Directory Structure

Your source directories should contain any of these supported skill directories:

Universal Skills (skills/) - Available for all platforms

my-skills-repo/
└── skills/
    ├── skill-one/
    │   └── SKILL.md
    ├── skill-two/
    │   └── SKILL.md
    └── another-skill/
        └── SKILL.md

Platform-Specific Skills

my-skills-repo/
├── .agents/skills/       # Only for Codex
│   ├── codex-skill-one/
│   └── codex-skill-two/
├── .claude/skills/       # Only for Claude
│   ├── claude-skill-one/
│   └── claude-skill-two/
├── .opencode/skills/      # Only for OpenCode
│   ├── opencode-skill-one/
│   └── opencode-skill-two/
└── .openclaw/skills/      # Only for OpenClaw
    ├── openclaw-skill-one/
    └── openclaw-skill-two/

Directory name = Skill name. When you add a skill, the entire directory is symlinked to your project. For Codex and the open agent skills convention, each skill directory should contain SKILL.md.

Skill Types:

• Universal (skills/) - Available for all platforms (Codex, Claude, OpenCode, OpenClaw)
• Platform-specific (.agents/skills/, .claude/skills/, .opencode/skills/, .openclaw/skills/) - Only available for the corresponding platform

Configuration

Configuration is stored in .skmrc.json (project root or home directory).

Example configuration:

{
  "sources": [
    "~/my-skills-repo",
    "/path/to/team-skills",
    "./local-skills"
  ]
}

Commands

Main Commands

skm add

Interactively select and add skills to the selected current project skill directory.

• No arguments needed
• Scans all configured sources
• Creates directory symlinks

skm list (alias: ls)

Display all discoverable skills from configured sources, grouped by source.

skm remove (alias: rm)

Select and remove skills from current project skill directories.

• Scans current project only
• Interactive multi-select
• Confirmation before deletion

skm search <keyword>

Search skills by name across all configured sources.

skm config

Display current configuration (sources list).

Source Management

skm source add [path]

Add a source directory or GitHub URL. If path is not provided, prompts for input.

Supported formats:

• Local path: ~/my-skills or /path/to/skills
• GitHub HTTPS: https://github.com/user/skills.git
• GitHub SSH: git@github.com:user/skills.git (automatically converted to HTTPS)

skm source list (alias: ls)

List all configured source directories with validation status.

skm source remove (alias: rm)

Interactively remove a source directory from configuration.

skm source update

Update all git source repositories by running git pull on each configured source that is a git repository.

Options:

• No options: Automatically update all git sources
• -i, --interactive: Select which git sources to update via multi-select interface

Behavior:

• Scans all configured sources from .skmrc.json
• Filters sources that are git repositories (have .git directory)
• Runs git pull for each git source
• Shows progress spinner and summary report
• Non-git sources are skipped silently
• Sources that don't exist are skipped with warning
• Reports sources already up to date separately from those with updates

Example:

# Update all git sources
skm source update

# Select which sources to update
skm source update --interactive

How It Works

1. Source Configuration: You configure source directories using skm source add (supports local paths and GitHub URLs)
2. GitHub Cloning: If source is a GitHub URL, skm automatically clones it using repo-do
3. Skill Discovery: skm scans skills/, .agents/skills/, .claude/skills/, .opencode/skills/, and .openclaw/skills/ subdirectories
4. Type-Based Filtering: Universal skills (skills/) work on all platforms, platform-specific skills only on their respective platforms
5. Directory Linking: When you add a skill, the entire skill directory is symlinked (not individual files)
6. Project Isolation: Each project has its own platform skill directory (Codex uses .agents/skills/) with symlinks to selected skills
7. Easy Updates: Update source repositories with skm source update, changes reflect in all projects via symlinks

Example Workflow

# One-time setup: add your skills repository
skm source add ~/my-skills-library

# In any project
cd ~/my-project
skm add                    # Select skills to add
# Work with Codex skills in .agents/skills/

# Later, remove unused skills
skm remove                 # Select skills to remove

# Add more sources anytime
skm source add /team/shared-skills
skm list                   # See all available skills

Windows Notes

On Windows, creating symlinks requires either:

• Administrator privileges, OR
• Developer Mode enabled

If symlink creation fails, skm will automatically fall back to copying directories (using junction points for better compatibility).

License

MIT