SkillHub

# SkillHub

[![Tests](https://img.shields.io/badge/tests-122%20passed-brightgreen)](#testing)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)

Git-based skill package manager for AI coding agents. Share AI agent skills (rules, instructions, prompts) across your team.

## Why SkillHub?

- **One source, many tools**: Write rules once, deploy to Cursor, Claude Code, Copilot, and 10+ other AI tools
- **Git-native**: Store skills in Git repos, version them, review changes
- **Team-friendly**: Global installation with per-project linking
- **Zero lock-in**: Standard file formats, easy to eject

## Supported Tools

| Tool | Config Path |
|------|-------------|
| Cursor | `.cursor/rules/` |
| GitHub Copilot | `.github/copilot-instructions.md` |
| Claude Code | `CLAUDE.md` |
| OpenCode / Codex | `AGENTS.md` |
| Windsurf | `.windsurf/rules/` |
| Aider | `.aider/instructions.md` |
| Cline | `.cline/instructions.md` |
| Roo | `.roo/rules/` |
| Continue | `.continue/rules/` |
| Zed | `.zed/instructions.md` |
| Void | `.void/instructions.md` |
| Witboost | `.witboost/instructions.md` |

## Installation

```bash
git clone https://github.com/cloudvalley/skillhub.git
cd skillhub
npm install
npm run build
npm link
```

Verify:
```bash
skillhub --version
```

## Quick Start

### Option 1: Global Setup (Recommended)

Install skills once, use everywhere:

```bash
# Initialize global config
skillhub init --global

# Add skill sources
skillhub add https://github.com/your-org/skills.git --global

# Install skills globally
skillhub install --global

# In any project, link to global skills
cd your-project
skillhub link
```

### Option 2: Project-Local

Install skills only in current project:

```bash
cd your-project
skillhub init
skillhub add https://github.com/your-org/skills.git
skillhub install my-skill
```

## Commands

| Command | Description |
|---------|-------------|
| `skillhub init [--global]` | Create config file |
| `skillhub add <url> [--global]` | Add a skill source |
| `skillhub remove <name>` | Remove a skill source |
| `skillhub list [--global]` | List sources and skills |
| `skillhub sync [--global]` | Fetch latest from sources |
| `skillhub install [skills...] [--global]` | Install skills |
| `skillhub update [--global]` | Sync and reinstall |
| `skillhub link [--force]` | Link global skills to project |

### Command Options

```bash
skillhub add <url> --ref <branch|tag>  # Git ref (default: main)
skillhub add <url> --name <name>       # Custom source name
skillhub link --force                  # Overwrite existing files
```

## Configuration

### Project Config (`skillhub.yaml`)

```yaml
sources:
  - name: company-skills
    url: git@github.com:your-org/skills.git
    ref: main

skills:
  - typescript-best-practices
  - security-baseline

# Optional: Custom output paths
output:
  cursor:
    rulesDir: .custom/cursor-rules
  claude-code:
    path: docs/CLAUDE.md

# Optional: Disable specific targets
targets:
  windsurf: false
  aider: false
```

### Global Config

Located at `~/.config/skillhub/skillhub.yaml`. Same format as project config.

## Creating Skills

### With Manifest

```
my-skill/
├── skillhub.skill.yaml
├── cursor-rules.md
└── claude.md
```

**skillhub.skill.yaml:**
```yaml
id: my-skill
name: My Skill
version: 1.0.0
description: What this skill does
tags:
  - typescript
  - quality

artifacts:
  - target: cursor
    source: cursor-rules.md
    strategy: replace
  - target: claude-code
    source: claude.md
    strategy: append
```

### Merge Strategies

| Strategy | Behavior |
|----------|----------|
| `replace` | Overwrite target file |
| `append` | Add at end with markers |
| `prepend` | Add at start with markers |
| `section` | Add/update named section |

### Auto-Detection

SkillHub auto-detects skills from standard layouts (no manifest needed):

```
your-skill-repo/
├── .cursor/rules/     → detected as cursor skill
├── CLAUDE.md          → detected as claude-code skill
└── AGENTS.md          → detected as opencode skill
```

## File Locations

| Type | Path |
|------|------|
| Global config | `~/.config/skillhub/skillhub.yaml` |
| Global skills | `~/.skillhub/installed/` |
| Source cache | `~/.cache/skillhub/sources/` |
| Project config | `./skillhub.yaml` |
| Project lockfile | `./skillhub.lock` |

## Workflows

### Team Setup

```bash
# One-time setup per developer
skillhub init --global
skillhub add git@github.com:company/skills.git --global
skillhub install --global

# Per project
cd any-project
skillhub link
```

### Keep Up to Date

```bash
skillhub update --global  # Sync and reinstall
```

### CI/CD

```yaml
steps:
  - name: Install Skills
    run: |
      skillhub sync
      skillhub install
```

## Documentation

- [Demo Guide](docs/DEMO.md) - Step-by-step examples
- [User Manual](docs/USER_MANUAL.md) - Complete reference
- [Architecture](docs/DESIGN.md) - Design docu

... (truncated)