@thanhnv6702/skill-hub

CLI để push (đẩy) và pull (kéo) skills dùng chung cho Claude Code và OpenCode qua một Git repo làm registry.

Skill registry là gì?

Chỉ là một Git repo (GitHub / GitLab / Bitbucket / self-hosted — bất kỳ) có cấu trúc:

your-skill-registry/
└── skills/
    ├── my-skill/
    │   ├── SKILL.md          ← bắt buộc
    │   └── ... (mọi file khác tùy skill)
    └── another-skill/
        └── SKILL.md

Mỗi thư mục trong skills/ là 1 skill. File SKILL.md là metadata (frontmatter description, hướng dẫn, v.v.) — định dạng chuẩn của Claude Code / OpenCode.

Không cần server, không cần hosting — cứ git push là xong.

Cài đặt

npm install -g @thanhnv6702/skill-hub
shub --help

Yêu cầu: Node.js ≥ 18, git đã cài, SSH key hoặc HTTPS credential đã cấu hình cho registry repo (CLI không quản token).

Bắt đầu trong 3 phút

1. Tạo registry repo

Tạo 1 repo trống trên GitHub (public hoặc private đều OK), ví dụ your-username/my-skills.

2. Config local

shub init

Sẽ hỏi:

• Registry Git URL — ví dụ https://github.com/your-username/my-skills.git hoặc [email protected]:your-username/my-skills.git
• Branch — mặc định main
• Default target — chọn Ask every time (khuyến nghị) hoặc cố định 1 target

Config lưu ở ~/.skill-hub/config.json. Registry được clone cache vào ~/.skill-hub/cache/.

3. Push skill đầu tiên

Giả sử bạn đã có skill tự viết ở ~/.claude/skills/my-awesome-skill/SKILL.md:

shub push

CLI sẽ:

1. Quét tất cả skills local trong 4 target dir
2. Hiện checkbox list → space để tick, enter để confirm
3. Hỏi có overwrite skill cùng tên trong registry không
4. Nhập commit message (có placeholder tự sinh)
5. Tự động clone/fetch registry, copy skill, git commit, git push

4. Kéo skill từ registry về máy khác

shub pull

CLI sẽ:

1. Sync registry mới nhất
2. Hỏi cài vào target nào (Claude global / Claude project / OpenCode global / OpenCode project)
3. Hiện checkbox list skills từ registry → tick để chọn nhiều skill một lúc
4. Hỏi overwrite nếu đã có skill trùng tên
5. Copy vào đúng thư mục skills của Claude/OpenCode

Commands

| Lệnh | Mô tả | | --- | --- | | shub init | Cấu hình registry URL, branch, default target. Ghi ~/.skill-hub/config.json. | | shub list | Sync registry rồi in ra toàn bộ skills (kèm description trích từ SKILL.md). | | shub pull [-t <target>] | Chọn target → multiselect skills → cài về. | | shub push [-m <msg>] | Multiselect skills local → commit + push lên registry. | | shub config | In config hiện tại. |

Options

-t, --target <id> (cho pull) — bỏ qua prompt chọn target, dùng trực tiếp. Ví dụ shub pull -t claude-global.

-m, --message <msg> (cho push) — commit message tùy chỉnh (không hỏi nữa).

4 target directory được hỗ trợ

Cả push (quét skill local) và pull (cài skill về) đều dùng 4 target này:

| id | Path | Dùng khi | | --- | --- | --- | | claude-global | ~/.claude/skills/ | Skill dùng chung cho Claude Code trên toàn máy | | claude-project | ./.claude/skills/ | Skill gắn với project hiện tại | | opencode-global | ~/.config/opencode/skills/ | Skill dùng chung cho OpenCode | | opencode-project | ./.opencode/skills/ | Skill gắn với project hiện tại (OpenCode) |

Khi push, nếu 1 skill cùng tên nằm ở nhiều target, ưu tiên project > global, Claude > OpenCode.

Cấu trúc 1 skill

my-skill/
├── SKILL.md          ← bắt buộc
├── reference.md      ← optional
├── scripts/
│   └── helper.py     ← optional
└── ...

SKILL.md tối thiểu:

---
name: my-skill
description: Làm việc X với Y — activate khi user hỏi về Z
---

# My Skill

Nội dung skill ở đây...

Workflow đề xuất

Cá nhân hóa skills dùng nhiều máy:

1. Tạo 1 repo private my-skills
2. shub init → trỏ về repo đó trên máy A
3. shub push — đẩy skills đã viết
4. Trên máy B: shub init (cùng repo) → shub pull → tick hết → xong

Share skills với team:

1. Team có 1 repo chung team-skills
2. Mỗi member shub init trỏ repo team
3. Ai viết skill mới → shub push (có code review qua PR nếu muốn — CLI push lên branch đã config)
4. Người khác shub pull để sync

Troubleshooting

Not configured. Run shub init first. — chưa chạy shub init.

git is not installed or not in PATH — cài git trước.

Registry sync failed — sai URL, không có quyền truy cập, hoặc branch không tồn tại. Check shub config rồi sửa ~/.skill-hub/config.json trực tiếp hoặc chạy lại shub init.

No skills found in registry — registry đúng là Git repo nhưng thiếu folder skills/. Tạo folder + push ít nhất 1 skill có SKILL.md.

No local skills found (khi push) — không có skill nào trong 4 target dir. Tạo skill đầu tiên ở ~/.claude/skills/my-skill/SKILL.md.

Push bị reject (permission denied) — SSH key / HTTPS token chưa setup. Thử git push trực tiếp vào repo cache để test: cd ~/.skill-hub/cache/<repo-slug> && git push.

Config format

File ~/.skill-hub/config.json:

{
  "registryUrl": "https://github.com/your-username/my-skills.git",
  "registryBranch": "main",
  "defaultTarget": null
}

Có thể edit tay thay vì chạy shub init. defaultTarget = null (hỏi mỗi lần) hoặc 1 trong 4 id target.

License

MIT