skill-hub

English | 中文

Web UI for managing skills from GitHub repositories and local directories — with a focus on reducing unnecessary token overhead.

Why skill-hub?

Managing agent skills shouldn't waste tokens. skill-hub centralizes skill discovery, installation, and versioning so you spend less time describing what skills do and more time using them.

• One source of truth — skills live in ~/.skills_repo/, not scattered across chat histories
• Visual discovery — browse skill metadata in the Web UI instead of reading full SKILL.md files through your agent
• Sync-once, use-everywhere — install to ~/.claude/skills/ and ~/.agents/skills/ in one click, avoiding repeated "please install this skill" conversations
• Version awareness — yellow badges tell you when a skill is outdated, preventing stale instructions from silently consuming tokens
• Install only what you need — keep your global skill space lean. Install project-specific skills to .agents/skills/ (private) and only widely-used skills to ~/.agents/skills/ (global). The fewer irrelevant skills in scope, the less token waste on false-positive matches

How It Works

Data Flow

Directory Structure

Take anthropics/skills as an example — a well-known community skill repository. After adding it via the UI, the local layout looks like:

~/.skills_repo/
├── repos.yaml                  # repo list config
├── repos/
│   └── anthropics__skills/     # cloned from github.com/anthropics/skills
│       ├── web-design/
│       │   └── SKILL.md        # discovered as a skill
│       ├── excel-sheets/
│       │   └── SKILL.md
│       └── ...
├── mappings/
│   └── anthropics__skills.yaml # skill → installed path mapping
└── intros/
    └── anthropics__skills.json # cached repo intro (README summary)

skill-hub scans SKILL.md files in each repo, builds a mapping, and installs (symlink or copy) to both target directories.

Steps

1. Add a GitHub repo or local directory via the UI — remote repos get cloned into ~/.skills_repo/repos/, local paths are scanned in place
2. Skills are discovered automatically via SKILL.md files in the repo
3. Install skills to ~/.claude/skills/ and ~/.agents/skills/ with one click
4. Sync status — green badges mean installed version matches source, yellow means outdated, gray means not installed
5. Repo sync — detect and pull remote updates, with a sync status indicator per repo (local paths skip cloning)

Installation

pip install skill-hub

# Or from GitHub
pip install git+https://github.com/wuerping/skill-hub.git

# Development
pip install -e .

Quick Start

# Start the web UI
skill-hub web

# Check version
skill-hub version

# Update to the latest version
skill-hub self-update

The web UI opens at http://127.0.0.1:7860 where you can add GitHub repos or local directories, browse skills, and install them to ~/.claude/skills/ and ~/.agents/skills/.

# Custom port
skill-hub web --port 8080

# Don't auto-open browser
skill-hub web --no-open

# Check for updates without installing
skill-hub version --check

CLI Commands

Command	Description
skill-hub web	Start the web UI
skill-hub version	Show current version
skill-hub version --check	Check if a newer version is available
skill-hub self-update	Upgrade skill-hub via pip
skill-hub summarize <repo>	Generate a structured summary of a repo's README
skill-hub set-summary <repo> <json>	Save a generated summary for a repo

Features

• Skills grouped by repository (remote and local)
• Per-directory install status badges (green = up-to-date, yellow = outdated, gray = not installed)
• Install to both ~/.claude/skills and ~/.agents/skills simultaneously
• Click green badges to uninstall from that directory; click yellow/gray badges to install or update
• Click skill names to view metadata from SKILL.md frontmatter
• Add/remove repos, with remote update detection
• Async clone with progress — remote repos clone in the background with a real-time progress bar, retry on failure
• Local directory support — add any local path (e.g. ~/code/my-skills) as a skill source
• Suggested default repo — anthropics/skills is pre-filled in the Add Repo form as a quick-start suggestion
• Repository diagnostics — 🔍 button runs comprehensive health checks (git, network, SKILL.md files, mappings)
• Bulk install/uninstall — "Install All" / "Uninstall All" buttons per repo to manage all skills at once
• Install Directories panel — standalone panel for managing target install directories (~/.claude/skills/, ~/.agents/skills/, and custom paths)
• Repo Introduction — AI-generated structured summary from README (purpose, features, value, target users) with Markdown rendering; click repo name to expand/collapse. Cached in ~/.skills_repo/intros/
• Author Information — display repo owner and top contributors from GitHub API (auto-hide when unavailable)
• Agent Callback — generate summaries by calling your local AI agent (e.g., opencode, claude) directly from the web UI

SKILL.md Format

---
name: skill-name
description: A brief description of the skill
license: MIT
compatibility: cursor, claude, opencode
metadata:
  version: 1.0.0
  author: you@example.com
---

## Skill Content

Your skill instructions here...

Architecture

src/skill_hub/
├── cli.py              # Click CLI entrypoint (web, version, self-update)
├── models.py           # SkillMetadata dataclass
├── version.py          # Version parsing and GitHub release checking
├── utils/
│   ├── __init__.py     # Path helpers (expand_path, derive_name)
│   └── yaml_parser.py  # SKILL.md YAML frontmatter parser
└── web/
    ├── app.py          # Flask app factory
    ├── api.py          # REST API routes
    ├── repos.py        # Repo management (clone, scan, install)
    ├── state.py        # Installed skills state tracking
    └── templates/
        └── index.html  # Single-page web UI

License

MIT