antigravity-skill-sync

CLI đồng bộ (sync) Superpowers skills từ repo obra/superpowers vào cấu trúc Antigravity dưới ./.agents/.

Yêu cầu

• Node.js >= 18

Dùng với npx (khuyến nghị)

Sau khi package đã publish lên npm, bạn không cần cài global. Chạy trực tiếp trong thư mục gốc project Antigravity (nơi cần tạo .agents/):

Đồng bộ tất cả skills (mặc định)

Source mặc định đã nhúng sẵn: https://github.com/obra/superpowers/tree/main.

npx antigravity-skill-sync --force

Xem trước (không ghi file)

npx antigravity-skill-sync --dry-run

Đồng bộ một vài skills

npx antigravity-skill-sync --skills brainstorming,writing-plans --force

Xóa skill không còn trong selection

npx antigravity-skill-sync --skills brainstorming,writing-plans --clean --force

Ghim version cụ thể

npx [email protected] --force

Ghi chú khi dùng npx

• npx tải package tạm (hoặc dùng cache) rồi chạy binary antigravity-skill-sync.
• File output (./.agents/skills, ./.agents/workflows, …) được tạo theo cwd hiện tại, không phải thư mục cài npm.
• Lần đầu có thể hỏi xác nhận cài package; thêm --yes nếu muốn không hỏi:

npx --yes antigravity-skill-sync --force

Cài đặt global (tùy chọn)

npm install -g antigravity-skill-sync
antigravity-skill-sync --force

Phát triển trong repo này

npm install
node bin/antigravity-skill-sync.js --force

Các lệnh/flags

Binary: antigravity-skill-sync

antigravity-skill-sync [github-tree-url] \
  [--url <github-tree-url>] \
  [--source <github-tree-url>] \
  [--dest <path>] \
  [--all | --skills <csv>] \
  [--ref <ref>] \
  [--dry-run] \
  [--force] \
  [--clean] \
  [--report <path>]

• --url <url>: thay link GitHub mặc định (ưu tiên cao nhất).
• --source <url>: alias của --url (mặc định: Superpowers main nếu không truyền --url / positional).

URL có thể là repo hoặc tree:

• https://github.com/owner/repo → tự thêm /tree/main (hoặc /tree/<ref> nếu có --ref)
• https://github.com/owner/repo/tree/main → dùng nguyên

Thứ tự ưu tiên nguồn: --url → --source → positional URL → mặc định nhúng sẵn.

npx antigravity-skill-sync --url https://github.com/obra/superpowers/tree/main --force

• --ref <ref>: override ref (branch/tag/sha) nếu muốn pin version.
• --dest <path>: thư mục đích cho skills (mặc định ./.agents/skills).
• --skills <csv>: chỉ sync các skill trong danh sách (tên folder).
• --all: sync tất cả (mặc định nếu không truyền --skills).
• --dry-run: chỉ in “plan”, không ghi file.
• --force: overwrite khi dest khác source; luôn tạo/cập nhật .agents/skills/_index.json (kể cả khi mọi skill đã skip).
• --clean: xóa các skill do tool quản lý nhưng không còn nằm trong selection hiện tại.
• --report <path>: ghi report JSON.

Xóa skill (--clean)

--clean xóa các folder trong ./.agents/skills/ không nằm trong keep-set (danh sách skill sẽ giữ sau sync):

| Trường hợp | Keep-set là gì | |------------|----------------| | Mặc định --all | Tất cả skills từ upstream Superpowers | | --skills a,b | Chỉ a, b |

Điều kiện xóa:

1. Managed (_index.json ghi managed: true cho skill đó) và không thuộc keep-set.
2. Orphan (có SKILL.md nhưng không managed) — chỉ xóa khi thêm --force.

Ví dụ: chỉ giữ 2 skills, xóa phần còn lại

npx antigravity-skill-sync --skills brainstorming,writing-plans --clean --force

Ví dụ: xóa folder skill thừa (test/tạo tay) khi sync full

npx antigravity-skill-sync --clean --force

Folder thừa (có SKILL.md) sẽ bị xóa nếu không nằm trong upstream keep-set.

Xem trước clean (dry-run)

npx antigravity-skill-sync --skills brainstorming --clean --dry-run

In ra Clean plan: trước khi ghi file.

Lưu ý: --clean --all không xóa các skill upstream vẫn còn — chỉ xóa skill local thừa / không còn trong --skills selection.

Khi dùng --clean, tool cũng xóa và sync lại thư mục docs Superpowers:

• ./.agents/docs/superpowers/ (copy lại từ docs/ upstream sau khi clean)

Output mà tool tạo ra

Sau khi sync, tool sẽ tạo/cập nhật:

• Skills: ./.agents/skills/<skill-name>/**

  • Copy toàn bộ cây thư mục trong skills/<skill-name>/** từ Superpowers (không chỉ SKILL.md).
  • Quản lý sync trong ./.agents/skills/_index.json (managed, source, syncedAt — không còn file marker từng skill).

• Workflows (mặc định 3 cái): ./.agents/workflows/

  • brainstorming.md → invoke .agents/skills/brainstorming/SKILL.md
  • writing-plans.md → invoke .agents/skills/writing-plans/SKILL.md
  • executing-plans.md → invoke .agents/skills/executing-plans/SKILL.md

• Docs: ./.agents/docs/superpowers/

  • Copy toàn bộ thư mục docs/ từ Superpowers sang đây (namespaced).

Nguồn upstream

• Repo: obra/superpowers