cc-kit

CLI cài qua npm để scaffold/cấu hình nhanh một project Claude Code từ một catalog repo private của bạn. Chạy npx @leobranding/cc-kit init, chọn từ menu checkbox các item muốn cài — skills, plugins, MCP servers, file mẫu (.gitignore…), và các mảnh settings.json — rồi cc-kit tự ghi/merge vào project.

cc-kit là "cỗ máy" mỏng (chỉ chứa logic), còn nội dung nằm ở catalog repo riêng của bạn. Thêm một item mới = push một thư mục vào catalog, không cần publish lại npm.

Cài đặt nhanh

npx @leobranding/cc-kit init

Chạy trong thư mục project đích. cc-kit sẽ hiện menu checkbox các item trong catalog (gom nhóm theo loại), bạn chọn rồi nó áp vào project.

Yêu cầu

• Node ≥ 18
• git (cc-kit gọi git clone / git pull để tải catalog)
• Quyền truy cập catalog repo private — cc-kit dùng credentials git sẵn có của máy (Windows Credential Manager / SSH agent / gh). cc-kit không tự quản token. Nếu clone thất bại, kiểm tra: quyền truy cập repo, gh auth login, hoặc cấu hình SSH key.

Cấu hình catalog source

cc-kit resolve URL catalog theo thứ tự ưu tiên:

1. --source <git-url> (flag) — ưu tiên cao nhất.
2. Biến môi trường CC_KIT_CATALOG.
3. DEFAULT_CATALOG hardcode trong src/config.js.

Quan trọng: DEFAULT_CATALOG mặc định là https://github.com/leonguyenst/cc-kit-catalog.git (xem src/config.js). Nếu bạn dùng catalog repo khác, hãy đổi DEFAULT_CATALOG trong src/config.js thành URL repo của bạn, hoặc luôn truyền qua --source / CC_KIT_CATALOG.

Cache: catalog được clone (shallow --depth=1) vào ~/.cc-kit/catalog. Lần chạy sau, cc-kit git pull --ff-only để cập nhật. Nếu URL --source đổi so với origin đã cache, cc-kit tự xóa cache và clone lại. Nếu git pull thất bại (mất mạng, history bị rewrite…), cc-kit cảnh báo và tiếp tục dùng cache hiện có thay vì dừng.

Flags

npx @leobranding/cc-kit init [options]

| Flag | Mô tả | |---|---| | --skills=a,b | Chọn sẵn skills theo id (phân tách bằng dấu phẩy). | | --plugins=x | Chọn sẵn plugins theo id. | | --mcp=y | Chọn sẵn MCP servers theo id. | | --files=z | Chọn sẵn file mẫu theo id. | | --settings=s | Chọn sẵn settings preset theo id. | | -y, --yes | Bỏ qua menu tương tác. Có flag chọn → cài đúng những gì flag chỉ định; không có flag chọn nào → cài TẤT CẢ item trong catalog. | | --source <url> | Override catalog repo. | | --dir <path> | Project đích (mặc định: thư mục hiện tại). | | --refresh | Xóa cache và tải lại catalog. | | --offline | Chỉ dùng cache, không gọi mạng (lỗi nếu chưa có cache). | | --force | Ghi đè không hỏi — chỉ áp dụng cho skill (xem lưu ý bên dưới). | | -h, --help | In trợ giúp. | | --version | In phiên bản. |

Lưu ý về cách chọn item:

• Chỉ cần xuất hiện bất kỳ flag chọn nào (--skills / --plugins / --mcp / --files / --settings) là cc-kit bỏ qua menu tương tác và lọc theo flag.
• Không có flag chọn và không có -y → hiện menu checkbox.
• Nếu sau khi lọc/chọn không có item nào → cc-kit in Không có item nào được chọn — không thay đổi gì. và thoát với code 0 (không thay đổi project).

Cài gì / vào đâu / bước thủ công

| Loại | Cài vào đâu | Khi đã tồn tại | Bước thủ công còn lại | |---|---|---|---| | skill | Copy thư mục → .claude/skills/<id>/ (loại trừ meta.json). | Bỏ qua, trừ khi --force (khi đó xóa cũ rồi copy lại). | — | | file | Ghi nội dung → meta.target (vd .gitignore). | Theo meta.onConflict: append (gộp + dedupe dòng), overwrite (backup rồi ghi đè), skip. | — | | settings | Deep-merge mảnh vào .claude/settings.json. | Merge, giữ nguyên key có sẵn; backup trước khi ghi. | — | | mcp | Merge server.json vào mcpServers của .mcp.json. | Merge theo tên server; backup. | Mở claude và approve MCP server — không thể tự approve (lý do bảo mật của Claude Code). | | plugin | Ghi enabledPlugins vào .claude/settings.json (thêm extraKnownMarketplaces chỉ khi meta.marketplace có cả name và url). | Merge; backup. | Có thể cần chạy claude plugin install <name> để cài đầy đủ từ marketplace. |

Cuối mỗi lần chạy, cc-kit in summary (✅ đã cài / ⚠️ bỏ qua / ❌ lỗi) kèm danh sách bước thủ công còn lại cho các item mcp/plugin. Nếu có bất kỳ item nào lỗi (❌), cc-kit thoát với exit code 1 để CI/script phát hiện được.

Lưu ý an toàn

• Deep-merge cho mọi file JSON (.claude/settings.json, .mcp.json): chỉ thêm/cập nhật key của item, giữ nguyên phần còn lại của file. Mảng được merge có dedupe.
• Backup .backup (không phá huỷ): trước khi ghi đè một file đã tồn tại (file JSON, hoặc file overwrite/append), cc-kit copy file đó thành <file>.backup. Nếu <file>.backup đã tồn tại (lần ghi sau, kể cả ở lần chạy cc-kit khác), cc-kit tạo <file>.<timestamp>.backup thay vì đè lên — nhờ vậy <file>.backup luôn giữ bản gốc đầu tiên trước khi cc-kit động vào, không bị mất.
• .gitignore (và file append khác): gộp dòng mới + dedupe dòng trùng, không ghi đè nội dung sẵn có.
• --force chỉ áp dụng cho skill. File dùng meta.onConflict của riêng nó; settings/mcp/plugin luôn merge (không bị --force chi phối).
• File JSON đích bị hỏng (không parse được) → cc-kit báo lỗi item đó và không merge mù; các item khác vẫn tiếp tục.

Tạo catalog repo

Xem hướng dẫn cấu trúc thư mục và ví dụ từng loại item tại examples/catalog/README.md.

License

MIT