Russian version

Skill-Hub

Open-source extension manager for AI coding agents. Search, install, and manage skills, agents, and commands from a central catalog.

Supported AI Agents

| Agent | Status | Directories | |-------|--------|-------------| | Claude Code | Full support | ~/.claude/ / .claude/ | | Cursor | Full support | ~/.cursor/ / .cursor/ | | Copilot (VS Code) | Full support | ~/.config/Code/User/ / .github/ | | Codex (OpenAI) | Full support | ~/.codex/ / .codex/ |

Skill-Hub automatically detects the active agent via env vars (CODEX_SANDBOX → codex, GITHUB_COPILOT → copilot, CURSOR_TRACE → cursor) and directory presence (.codex/, .cursor/). You can also set it explicitly:

skill-hub config set agent cursor

Supported Platforms

| OS | Status | Notes | |----|--------|-------| | macOS | Full support | — | | Linux | Full support | — | | Windows | Full support | cmd.exe, PowerShell, Windows Terminal |

Windows

npm install -g @emaxe/skill-hub

Windows-specific behavior:

| Component | Behavior | |-----------|----------| | Agent launcher -A | Generates .bat script (CRLF) instead of .sh; self-deletes via del "%~f0" | | Copilot adapter | Looks for VS Code config in %APPDATA%\Code\User\ | | agents-conventions enable | Creates symlinks: dir → fallback junction → fallback directory copy | | Path comparison | Case-insensitive (relevant for Claude Code adapter) |

Note: Git Bash and WSL are not target platforms. Native Windows is recommended.

What Are Extensions?

Skill-Hub manages three types of extensions:

| Type | Description | Example installation (Claude Code) | |------|-------------|-----------------------------------| | Skill (SKILL.md) | AI instructions activated by context | ~/.claude/skills/{name}/SKILL.md | | Agent (AGENT.md) | Specialized AI assistants | ~/.claude/agents/{name}.md | | Command (COMMAND.md) | Custom slash commands | .claude/commands/{name}.md |

Each agent stores extensions in its own directory structure. Extensions can declare platform support via the platforms field — incompatible combinations are filtered automatically.

Multi-file Skills

Skills can contain additional files besides the main SKILL.md — scripts, templates, configurations, data. The entire skill directory is installed and uploaded as a whole.

skills/clean-runner/
├── SKILL.md              # Main file (required)
├── runner.sh             # Shell script
├── config.json           # Configuration
├── .skillignore          # Files to exclude (not copied)
└── filters/
    ├── common.grep       # Filter patterns
    └── npm.grep

Installation behavior:

| Adapter | Main file | Additional files | |---------|-----------|------------------| | Claude Code / conventions | Full directory copied | In the same directory | | Cursor | Transformed (Cursor frontmatter) | Copied as-is | | Copilot | Marker-injection into config | .github/skills/{name}/ | | Codex | Marker-injection into config | .codex/skills/{name}/ |

.skillignore — files excluded from copying (the .skillignore file itself is also not copied). Symlinks are ignored. Maximum directory size is 1 MB; binary files are prohibited when uploading to the catalog.

Quick Start

Option A: CLI + MCP (recommended)

npm install -g @emaxe/skill-hub

# Configure for your agent (claude-code | cursor | copilot | codex)
skill-hub setup-mcp --agent claude-code

After restarting the agent, MCP tools will be available automatically.

Option B: Bootstrap skill (manual)

# For Claude Code:
mkdir -p ~/.claude/skills/skill-hub
cp "$(npm root -g)/@emaxe/skill-hub/base-skills/claude-code/SKILL.md" ~/.claude/skills/skill-hub/SKILL.md

# For Cursor:
mkdir -p ~/.cursor/skills/skill-hub
cp "$(npm root -g)/@emaxe/skill-hub/base-skills/cursor/SKILL.md" ~/.cursor/skills/skill-hub/SKILL.md

# For Codex:
mkdir -p ~/.codex
cp "$(npm root -g)/@emaxe/skill-hub/base-skills/codex/SKILL.md" ~/.codex/AGENTS.md

Installing Skills from skills.sh

Skill-Hub supports direct installation of skills from skills.sh — a public AI skills registry by Vercel Labs. Works both via CLI and TUI.

Search (CLI)

skill-hub search --source skillssh react --limit 5

Installation (CLI)

# By full ID (recommended)
skill-hub install skillssh:vercel-labs/agent-skills@vercel-react-best-practices --agent claude-code --project

# By slug (skills.sh searches by ID)
skill-hub install skillssh:vercel-react-best-practices --agent claude-code --project

# By owner/repo — lists skills if multiple exist in the repo
skill-hub install skillssh:vercel-labs/agent-skills --agent claude-code --project

How It Works

1. CLI calls https://skills.sh/api/search or download API
2. Downloads all skill files to a temporary directory
3. Installs via the standard adapter (like a regular catalog skill)
4. Saves source: "skillssh:owner/repo@slug" in the registry for updates

Update (CLI)

# Update all skills (including skills.sh)
skill-hub update --agent claude-code

# Update a specific skills.sh skill
skill-hub update vercel-react-best-practices --agent claude-code

For skills.sh skills, the update compares the hash from the API — if changed, it re-downloads and reinstalls.

TUI Support

In the Catalog tab, type a query in the search field — results from the local catalog appear first, followed by live results from skills.sh (marked with [skills.sh] source). Press Enter on a skills.sh result to open its card, then i to install.

Installed skills.sh skills behave like catalog extensions: appear in the Installed tab with version = API hash, support d (remove), m (move), u (update), and startup sync (if recorded in .skill-hub.json).

Note: The c (view content) hotkey is hidden for uninstalled skills.sh items because the skill files are not cached locally until installation.

Interactive TUI

Run skill-hub without arguments for a fullscreen interface:

skill-hub

Minimum terminal size: 60×12. TUI adapts to window size: at width < 80 cols secondary table columns are hidden and labels are shortened; at height < 16 rows the stats panel is hidden.

General Navigation

| Key | Action | |-----|--------| | Tab / Shift+Tab | Switch tabs | | 1 / 2 / 3 | Direct jump: Catalog / Installed / Settings | | Esc | Back (on nested screens) | | Ctrl+Q | Exit |

Catalog Tab

Search and install extensions from the catalog.

| Key | Action | |-----|--------| | / | Focus search field | | ↑ ↓ | Navigate list | | Enter | Open extension card | | i | Install selected extension |

The search field supports type filters: agent:reviewer, skill:git.

Installed Tab

Manage installed extensions.

| Key | Action | |-----|--------| | ↑ ↓ | Navigate list | | Enter | Open extension card | | d | Delete extension (with confirmation) | | m | Move (global ↔ project) | | u | Update selected extension | | U | Update all extensions | | p | Upload to catalog (if you have access) | | / | Focus search field | | s | Toggle scope (global / project / all) |

Pressing Enter opens the extension card with detailed info and available actions:

From the card you can view the extension file content (c):

Settings Tab

Two sub-tabs: General and AI Agents.

General Sub-tab

| Field | Key | Description | |-------|-----|-------------| | Agent | ← → | Switch between claude-code, cursor, copilot, codex, agents-conventions | | Scope | ← → | Default scope: global or project | | Project | — | Current project name | | Registry URL | Enter | Edit catalog repository URL | | Update cache | Enter | Download latest catalog version | | AI agent dirs in .gitignore | ← → | Add agent directories to .gitignore (project config only) | | Install MCP | Enter | Register MCP server for current agent | | Install base skill | Enter | Install bootstrap skill | | Update CLI | Enter | Update skill-hub itself to the latest version | | Save as global | Enter | Copy project config to global | | Reset to global | Enter | Restore project config from global | | Sync | Enter | Check missing/untracked extensions |

AI Agents Sub-tab

Configure AI agent launch through skill-hub:

| Field | Key | Description | |-------|-----|-------------| | claude-code / cursor / copilot / codex | ← → | Enable/disable agent | | Proxy URL | Enter | Common proxy for all agents | | Use proxy (per-agent) | ← → | Toggle proxy for a specific agent |

Upload to Catalog Screen

Upload your own extensions to the catalog repository.

| Key | Action | |-----|--------| | ↑ ↓ | Navigate extension list | | Space | Select/deselect extension | | a | Select all | | s | Toggle scope (global / project) | | c | View selected extension content | | b | Edit branch name | | e | Edit PR title | | Enter | Start upload | | Esc | Back |

After upload: | o | Open link to create a merge request in the browser |

Sync Dialog

When starting TUI, extensions are automatically checked against the project config (.skill-hub.json). If discrepancies are found, a dialog appears:

• Missing — extensions from config not present on disk
• Untracked — extensions on disk not in config

| Key | Action | |-----|--------| | Enter | Sync (install + add to config) | | p | Upload to catalog (for extensions not in the catalog) | | Esc | Skip |

.gitignore Dialog

If gitignoreAgentDirs is enabled in the project config, TUI checks whether all AI agent folders (.claude/, .cursor/, .github/, .codex/, .agents/, .cursorrules) are added to .gitignore. If any are missing, a dialog appears:

| Key | Action | |-----|--------| | Enter | Add to .gitignore | | Esc | Skip |

Note: all hotkeys work in Russian keyboard layout (й→q, ц→w, у→e, etc.)

Working with AI Agents

Connecting via MCP

The MCP server provides 7 tools for managing extensions from within an AI agent:

# Automatic setup
skill-hub setup-mcp --agent claude-code

After setup, the agent gets access to:

• search_extensions — catalog search
• install_extension — installation with automatic dependency resolution
• remove_extension — removal
• move_extension — move between scopes
• list_extensions — list installed
• suggest_extensions — project-based recommendations
• get_extension_info — full extension info

Proxy Configuration

If AI agents work through a proxy (e.g., for API access):

Via TUI:

1. Open Settings → AI Agents sub-tab
2. Go to Proxy URL → press Enter
3. Enter the proxy URL
4. Enable "Use proxy" for the desired agents

Via CLI:

skill-hub config set aiAgents.proxy "http://proxy.example.com:8080"

Launching AI Agents via Skill-Hub

Skill-Hub can launch AI agents directly, applying proxy and other settings:

# Launch via exec
skill-hub -a claude-code "write a test for auth.ts"

# Launch via temporary script
skill-hub -A cursor "review this code"

Switching Catalog Repository

By default skill-hub uses the catalog at https://github.com/emaxe/skill-hub-catalog.git. You can switch to your own fork or corporate catalog.

Via TUI

1. Open Settings → Registry URL → Enter
2. Enter the new repository URL (HTTPS or SSH)
3. Confirm — old cache will be removed
4. Catalog will auto-download from the new repository

When switching repositories, the extension list in the project config .skill-hub.json will be cleared since they are tied to a specific catalog. Extension files on disk will remain.

Via CLI

skill-hub config set registryUrl "https://gitlab.example.com/team/my-catalog.git"

Catalog Requirements

Your catalog must contain:

• catalog.json — extension index (auto-generated by skill-hub-catalog scripts)
• Directories skills/, agents/, commands/ with extensions

A history of used URLs is kept (up to 6 entries) and available when editing via TUI.

Uploading Extensions to the Catalog

You can upload your own extensions to the catalog repository directly from skill-hub.

Prerequisites

• You have write access to the catalog repository (git push)
• The extension has a filled frontmatter (name, description, version, author)

Note: built-in base CLI skills (skill-hub, agents-conventions, init-agents, exit-agents) are automatically excluded from the upload candidate list.

Upload Process

1. Open the upload screen via one of:

   • In the Installed tab press p
   • In an installed extension card select "Upload to catalog"
   • In the sync dialog press p (for extensions not in the catalog)

2. Select extensions to upload:

   • Space — select/deselect
   • a — select all
   • s — toggle scope
   • c — preview content before upload

3. Configure options:

   • Branch name (auto: upload/{username}-{timestamp})
   • PR title (auto-generated from selected extensions)

4. Press Enter to upload — extensions will be:

   • Validated (frontmatter, kebab-case names)
   • Copied into the catalog structure
   • Committed and pushed to a separate branch

5. Create a merge request — press o to open the MR/PR form in the browser

Frontmatter Format

---
name: my-extension
description: "Extension description"
version: 1.0.0
author: "Author Name"
tags: tag1, tag2, tag3
platforms: claude-code, cursor
---

Agents-Conventions Mode

Mode for multi-agent projects — a shared .agents/ directory with extensions available to all agents via symlinks.

Enabling

skill-hub agents-conventions enable

Or via TUI: Settings → Agent → agents-conventions → Init Conventions.

What happens:

• .agents/ is created with skills/, agents/, commands/ subdirectories
• AGENTS.md is created (common project rules)
• Symlinks are created: .claude/ → .agents/, .cursor/ → .agents/, .codex/ → .agents/
• For Copilot a thin pointer is created at .github/copilot-instructions.md
• Bootstrap skill agents-conventions is installed globally in all AI agents
• Skills init-agents / exit-agents are installed to ~/.skill-hub/bootstrap/

Disabling

skill-hub agents-conventions disable

Extensions migrate back to individual agent directories, symlinks are removed.

CLI Commands Reference

search

Search extensions by name, tags, keywords.

skill-hub search git
skill-hub search agent:reviewer
skill-hub search "testing typescript"

install

Install an extension. Without prefix — skill, with prefix — by type.

skill-hub install git-commit-and-push
skill-hub install agent:code-reviewer
skill-hub install command:deploy-check
skill-hub install git-helper --scope=global
skill-hub install git-helper -y              # no confirmation

remove

Remove an installed extension.

skill-hub remove git-commit-and-push
skill-hub remove agent:code-reviewer

list

List installed extensions with versions and scope.

skill-hub list
skill-hub list --type=agent

move

Move an extension between scopes.

skill-hub move git-helper project
skill-hub move agent:code-reviewer global

info

Detailed info about a catalog extension.

skill-hub info git-commit-and-push
skill-hub info agent:code-reviewer

update

Update extensions to the latest versions.

skill-hub update                     # update all
skill-hub update agent:code-reviewer # update specific
skill-hub -u code-reviewer           # shorthand
skill-hub -U                         # update all (shorthand)

config

Manage configuration.

skill-hub config set agent cursor
skill-hub config set registryUrl "https://gitlab.example.com/catalog.git"
skill-hub config set defaultScope global
skill-hub config get agent
skill-hub config reset

setup-mcp

Register MCP server for an AI agent.

skill-hub setup-mcp --agent claude-code
skill-hub setup-mcp --agent cursor
skill-hub setup-mcp --agent copilot
skill-hub setup-mcp --agent codex

agents-conventions

Manage multi-agent mode.

skill-hub agents-conventions enable
skill-hub agents-conventions disable

help

Full help on commands, flags, and options.

skill-hub help
skill-hub -h
skill-hub --help

Special Flags

skill-hub -a claude-code "task"   # launch agent via exec
skill-hub -A cursor "task"        # launch via temp script
skill-hub --then                     # chain two commands

Project Config (.skill-hub.json)

The .skill-hub.json file in the project root allows you to:

• Pin the set of extensions for the project (team sync)
• Override global settings for a specific project
• Auto-sync extensions when opening the project in TUI
• Control adding AI agent folders to .gitignore

{
  "registryUrl": "https://github.com/emaxe/skill-hub-catalog.git",
  "project": "my-project",
  "gitignoreAgentDirs": true,
  "extensions": [
    { "type": "skill", "name": "git-commit-and-push", "version": "1.0.0", "scope": "project" },
    { "type": "agent", "name": "code-reviewer", "version": "1.0.0", "scope": "global" }
  ]
}

Colleagues cloning the project will see the sync dialog on first skill-hub launch and can auto-install all listed extensions.

Architecture

skill-hub (this repo)
├── cli/                     # CLI + MCP server (npm: @emaxe/skill-hub)
│   ├── src/
│   │   ├── adapters/        # Agent adapters (claude-code, cursor, copilot, codex)
│   │   ├── commands/        # CLI commands
│   │   └── tui/             # Interactive TUI (Ink/React)
│   └── base-skills/         # Bootstrap skills for each agent
├── docs/                    # Feature documentation
└── CLAUDE.md                # Instructions for AI agents

skill-hub-catalog (separate repo)
├── skills/                  # Published skills
├── agents/                  # Published agents
├── commands/                # Published commands
├── catalog.json             # Auto-generated index
├── schema/                  # Frontmatter validation schemas
└── docs/                    # Extension creation guides

Delivery flow:

1. git clone --depth 1 skill-hub-catalog → ~/.skill-hub/ (local cache)
2. Installation = adapter copies extension to the agent's target directory
3. Update = git pull in cache, re-copy installed extensions

Local CLI Development

cd cli && npm run build       # build
npm link                      # global link
skill-hub search git          # test
npm unlink -g @emaxe/skill-hub # remove link
cd cli && npm test            # tests (290 tests)

After source changes, just rebuild (npm run build) — the link updates automatically.

Contributing

Extensions (skills, agents, commands) are published to skill-hub-catalog. See the docs/ directory there for creation guides.

For CLI improvements — open a PR in this repository. Details in CONTRIBUTING.md.

License

MIT