Hub Index Guide

Build a centralized skill catalog for your organization — no GitHub API or token required.

Why Use a Hub Index?

A hub index is a JSON file (skillshare-hub.json) that lists skills with their name, description, and source. Host it internally and every team member can search and install skills from it.

Use Case	GitHub Search	Hub Index
Organization-wide skill catalog	No	Yes
Private/internal skills	No	Yes
Air-gapped / VPN-only environments	No	Yes
Curated, approved skill sets	No	Yes
No GitHub token needed	No	Yes

For a real-world example, see the Public Hub section.

Quick Start

1. Build an Index

# From your global skills
skillshare hub index

# From a project
skillshare hub index -p

# Output: <source>/skillshare-hub.json

2. Search the Index

# Local file
skillshare search react --hub ./skillshare-hub.json

# Remote URL
skillshare search react --hub https://internal.corp/skills/skillshare-hub.json

# Browse all skills (no query)
skillshare search --hub ./skillshare-hub.json --json

3. Install from Results

The interactive search flow works the same as GitHub search — select a skill and it gets installed.

Audit Enrichment

Add security risk scores to your index so teammates can see skill safety at a glance:

# Build index with audit scores
skillshare hub index --audit

# Combine with full metadata
skillshare hub index --full --audit

When --audit is used, each skill is scanned with skillshare audit rules and the index includes riskScore (0–100), riskLabel (clean/low/medium/high/critical), and auditedAt timestamp. Skills that fail to scan are included without risk fields.

Search results from an audited index display risk badges:

  1. safe-skill               owner/repo/safe-skill         [clean]
  2. risky-skill              owner/repo/risky-skill        [high]

Copy the index file to a shared location:

skillshare hub index -o /shared/team/skillshare-hub.json

Teammates search with:

skillshare search --hub /shared/team/skillshare-hub.json

HTTP Server

Generate the index locally, then upload it to your hosting:

# Step 1: Generate
skillshare hub index -o ./skillshare-hub.json

# Step 2: Upload (use your preferred method)
scp ./skillshare-hub.json server:/var/www/skills/
# or: aws s3 cp ./skillshare-hub.json s3://my-bucket/
# or: rsync, FTP, etc.

Teammates search with:

skillshare search --hub https://skills.company.com/skillshare-hub.json

Git Repository

Commit the index to a shared repo so teammates can pull it:

skillshare hub index -o ./skillshare-hub.json
git add skillshare-hub.json && git commit -m "Update skill index"
git push

Teammates can search via the raw URL or clone locally:

# Via raw URL
skillshare search --hub https://raw.githubusercontent.com/team/skills/main/skillshare-hub.json

# Or clone and search locally
git pull
skillshare search --hub ./skillshare-hub.json

Web Dashboard

The web dashboard (skillshare ui) supports hub search:

Open the Search page
Click Hub tab
Click Manage to add hub sources (URL or local path)
Select a hub from the dropdown and search
Install directly from the UI

Saved hubs persist in browser localStorage.

Hub Search

Select a hub source from the dropdown and search for skills.

Switch Between Hubs

Hub dropdown selector

Use the dropdown to switch between multiple hub sources.

Manage Hubs

Manage hubs modal

Click Manage to add, view, or remove hub sources. Enter a URL or local file path to a skillshare-hub.json file.

Delete Confirmation

Hub delete confirmation

Removing a hub requires confirmation to prevent accidental deletion.

Index Schema

The index follows Schema v1:

{
  "schemaVersion": 1,
  "generatedAt": "2026-02-12T10:00:00Z",
  "sourcePath": "/home/user/.config/skillshare/skills",
  "skills": [
    {
      "name": "my-skill",
      "description": "Does something useful",
      "source": "owner/repo/.claude/skills/my-skill",
      "tags": ["workflow", "productivity"]
    }
  ]
}

Essential Fields (Consumer Contract)

Field	Required	Description
`name`	Yes	Skill display name
`source`	Yes	Install source (GitHub shorthand, URL, or local path)
`description`	Recommended	Short description for search matching
`skill`	No	Specific skill name within a multi-skill repo (used with `install -s`)
`tags`	No	Classification tags for filtering and grouping

Document-Level Fields

Field	Description
`schemaVersion`	Always `1`
`generatedAt`	RFC 3339 timestamp
`sourcePath`	Base path for resolving relative sources

Source Path Resolution

When sourcePath is set and a skill's source is a relative path, the search consumer joins them:

sourcePath: /home/user/.config/skillshare/skills
source:     _team/frontend-skill
→ resolved: /home/user/.config/skillshare/skills/_team/frontend-skill

This prevents relative paths from being misinterpreted as GitHub shorthand (owner/repo).

Absolute paths, URLs, and domain-prefixed paths are never joined:

Source Pattern	Joined?
`_team/my-skill`	Yes
`subdir/skill`	Yes
`/absolute/path`	No
`github.com/owner/repo/skill`	No
`https://...`	No

Hand-Written Indexes

You can create an index manually without using hub index. This is especially useful for internal skills hosted on private infrastructure — sources that GitHub Search and public tools can never reach:

{
  "schemaVersion": 1,
  "skills": [
    {
      "name": "company-style",
      "description": "Company coding standards and review checklist",
      "source": "ghe.internal.company.com/platform/ai-skills/company-style",
      "tags": ["quality", "workflow"]
    },
    {
      "name": "deploy-helper",
      "description": "Internal deployment automation",
      "source": "gitlab.internal.company.com/ops/skills/deploy-helper",
      "tags": ["devops"]
    },
    {
      "name": "onboarding",
      "description": "New hire onboarding skill for AI assistants",
      "source": "ghe.internal.company.com/hr/ai-skills/onboarding",
      "tags": ["workflow"]
    }
  ]
}

Why not just use GitHub Search?

skillshare search only finds public repos on github.com. A hub index can point to any source — GitHub Enterprise, private GitLab, internal servers — things that only your employees behind VPN can access. This is what makes hub the go-to solution for organization-wide skill distribution.

Tips for hand-written indexes:

sourcePath is optional — omit if all sources are absolute
tags is optional — useful for filtering on the website or in search
Skills with empty name are skipped
Results are sorted by name alphabetically

Organization Deployment

A typical end-to-end workflow for rolling out a hub across your organization:

# 1. A skill admin curates skills from internal repos
skillshare install ghe.internal.company.com/platform/ai-skills/coding-standards
skillshare install ghe.internal.company.com/platform/ai-skills/review-checklist
skillshare install ghe.internal.company.com/security/ai-skills/threat-model

# 2. Generate the hub index (with optional audit scores)
skillshare hub index --audit -o ./skillshare-hub.json

# 3. Host it (pick one)
#    - Internal Git repo: commit and push
#    - S3/CDN: aws s3 cp ./skillshare-hub.json s3://skills-bucket/
#    - Intranet server: scp to your hosting

# 4. Team members add the hub once
skillshare hub add https://skills.internal.company.com/skillshare-hub.json --label company

# 5. Search and install — only accessible behind VPN
skillshare search coding --hub company

To keep the index fresh, add skillshare hub index to a CI pipeline that runs after skill changes.

Public Hub

The skillshare-hub is a curated catalog of quality skills. It is the default hub — when you run search --hub without specifying a source, it searches here:

skillshare search --hub              # Browse all skills in the public hub
skillshare search react --hub        # Search for "react" skills

It also serves as a reference for building your own organization's hub:

Index structure — How to organize skillshare-hub.json with names, descriptions, sources, and tags
CI validation — Automated JSON format checks and skillshare audit security scans on every PR
Contribution workflow — Fork → add entry → PR, with CI gates

Want to build an internal hub for your team? Fork the repo, replace the skills with your organization's catalog, and customize the CI pipeline to match your security policies.

Tips

Automate index generation — Add skillshare hub index to your CI pipeline after skill changes
Use --full for auditing — Full mode includes version, install date, and type information
Combine with project mode — skillshare hub index -p indexes only project-level skills

Why Use a Hub Index?​

Quick Start​

1. Build an Index​

2. Search the Index​

3. Install from Results​

Audit Enrichment​

Sharing Strategies​

File Share (Simplest)​

HTTP Server​

Git Repository​

Web Dashboard​

Hub Search​

Switch Between Hubs​

Manage Hubs​

Delete Confirmation​

Index Schema​

Essential Fields (Consumer Contract)​

Document-Level Fields​

Source Path Resolution​

Hand-Written Indexes​

Organization Deployment​

Public Hub​

Tips​

See Also​