@hungvv/super-ads-skills 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# SuperAds Skills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bộ skill cho AI agent (Claude Code, Cursor, Codex, Antigravity) khi làm việc với **SuperAds SDK**: gắn SDK, thêm placement, sửa config, debug, đo show rate, test trên thiết bị, kiểm trước phát hành, nâng version SDK. Có CLI cài riêng, một lệnh cài, một lệnh update.
+
+## Cài và update
+
+```bash
+# Cài (lần đầu)
+npx -y @hungvv/super-ads-skills@latest install
+
+# Update (khi có bản mới)
+npx -y @hungvv/super-ads-skills@latest update
+```
+
+- `install` cài **tất cả skill cho tất cả agent**, ở mức global, không hỏi gì.
+- Chạy lại `install` khi đã cài là an toàn: skill đã mới nhất thì bỏ qua, có bản mới thì cập nhật (giống `update`), symlink đúng thì giữ nguyên. Folder trùng tên do bạn tự để vào không bị ghi đè (in `skip`, thoát mã 1); thêm `--force` để ghi đè.
+- `update` còn gỡ skill đã bị loại khỏi bộ.
+
+Cách cài hoạt động: mỗi thư mục agent chứa **symlink** về một bản chung `~/.local/share/super-ads-skills/skills` (bản copy, không phụ thuộc cache npx hay clone).
+
+| Agent | Thư mục skill |
+|---|---|
+| Claude Code | `~/.claude/skills` |
+| Cursor | `~/.cursor/skills` |
+| Codex | `~/.agents/skills` |
+| Antigravity | `~/.gemini/config/skills`, `~/.gemini/antigravity-ide/builtin/skills` |
+
+Đừng sửa trực tiếp file trong thư mục agent: sửa ở đó bị `update` ghi đè khi skill có bản mới. Muốn sửa skill, sửa trong clone, tăng `version`, rồi `update`.
+
+## Agent dùng bộ skill này thế nào
+
+1. Mọi việc liên quan SuperAds bắt đầu ở skill **[super-ads-guide](skills/super-ads-guide/SKILL.md)**: bảng *tác vụ → skill chủ* và các quy tắc chung (dùng MCP `super-ads` cho config, không đoán key hay API, dừng hỏi ở điểm `mustAsk`).
+2. Mỗi skill khai `superAds: ">=4.0.0 <5.0.0"` trong frontmatter: SDK mà nội dung skill đúng cho.
+3. Trước khi làm, agent đọc version SuperAds của app (cách đọc: `skills/super-ads-guide/references/sdk-version-check.md`) và so với range:
+   - **Trong range**: dùng skill bình thường.
+   - **Thấp hơn**: agent không làm tiếp im lặng. Nó báo user và **khuyến khích** dùng [super-ads-upgrade](skills/super-ads-upgrade/SKILL.md) để lên SuperAds mới nhất (core và mọi plugin cùng version), cập nhật logic, key JSON, config, và trả changelog. Không tự nâng khi user chưa đồng ý.
+   - **Cao hơn**: skill có thể cũ; agent dựa vào `MIGRATION.md` và mã SDK.
+
+## Danh mục skill
+
+Version skill nằm trong `version:` của từng `SKILL.md`; `super-ads-skills list` in version và range SDK.
+
+| Skill | Dùng khi | SuperAds |
+|---|---|---|
+| [super-ads-guide](skills/super-ads-guide/SKILL.md) | Điểm vào: định tuyến tác vụ, kiểm version SDK | `>=4.0.0 <5.0.0` |
+| [super-ads-upgrade](skills/super-ads-upgrade/SKILL.md) | Nâng SDK của app lên bản mới nhất, kèm changelog | `>=4.0.0 <5.0.0` |
+| [super-ads-integrate](skills/super-ads-integrate/SKILL.md) | App chưa có ads, gắn SuperAds từ đầu | `>=4.0.0 <5.0.0` |
+| [adspro-to-superads](skills/adspro-to-superads/SKILL.md) | Chuyển app từ AdsPro sang SuperAds | `>=4.0.0 <5.0.0` |
+| [super-ads-add-placement](skills/super-ads-add-placement/SKILL.md) | Thêm hoặc đổi vị trí ad | `>=4.0.0 <5.0.0` |
+| [super-ads-config](skills/super-ads-config/SKILL.md) | Sửa config qua MCP, có điểm dừng bắt buộc | `>=4.0.0 <5.0.0` |
+| [super-ads-ab-test](skills/super-ads-ab-test/SKILL.md) | Tạo A/B test Firebase, sinh 2 file variant | `>=4.0.0 <5.0.0` |
+| [super-ads-debug](skills/super-ads-debug/SKILL.md) | Ad không hiện, load lỗi, hiển thị sai, crash | `>=4.0.0 <5.0.0` |
+| [super-ads-show-rate](skills/super-ads-show-rate/SKILL.md) | Đo và giải thích show rate theo placement | `>=4.0.0 <5.0.0` |
+| [super-ads-adb-test](skills/super-ads-adb-test/SKILL.md) | Chạy kịch bản kiểm trên thiết bị | `>=4.0.0 <5.0.0` |
+| [super-ads-debug-override](skills/super-ads-debug-override/SKILL.md) | Bản debug chạy một lần với config khác asset | `>=4.0.0 <5.0.0` |
+| [super-ads-release-check](skills/super-ads-release-check/SKILL.md) | Rà trước khi phát hành (chỉ báo cáo) | `>=4.0.0 <5.0.0` |
+
+Bảng chi tiết nằm ở `skills/super-ads-guide/references/compatibility.md`. Lịch sử thay đổi: [CHANGELOG.md](CHANGELOG.md).
+
+## Cấu trúc một skill
+
+```
+skills/<name>/
+  SKILL.md        điểm vào: 21 mục theo mẫu android-skills (<= 400 dòng)
+  references/     tài liệu tra cứu, checklist, bảng
+  templates/      boilerplate để copy rồi sửa
+  snippets/       đoạn code ngắn (<= 30 dòng)
+  examples/       ví dụ hoàn chỉnh
+  scripts/        script chạy được (gọi bằng <skill>/scripts/...)
+```
+Thư mục con chỉ có khi có file thật. Quy tắc đầy đủ: [docs/AUTHORING.md](docs/AUTHORING.md).
+
+## Lệnh khác
+
+```bash
+super-ads-skills list              # từng skill: version, range SDK, trạng thái cài
+super-ads-skills remove [skill...] # gỡ (không tên = gỡ hết)
+```
+Cờ tuỳ chọn, chỉ khi cần: `--agent claude,cursor`, `--project` (cài vào thư mục hiện tại), `--copy` (copy thay vì symlink), `--force`, `--dry-run`. Biến môi trường `SUPER_ADS_SKILLS_STORE` đổi nơi đặt bản chung.
+
+## Cài từ clone (người phát triển skill)
+
+```bash
+cd tools/super-ads-skills && npm ci && npm run build && npm link && super-ads-skills install
+git pull && super-ads-skills update
+```
+Máy không có Node: `bash scripts/install-skills.sh` (Windows: `scripts/install-skills.ps1`); chạy lại là update, không có `list`/`remove`.
+
+## Kết nối MCP
+Skill sửa config chỉ qua MCP `super-ads`: xem [../ai_agent_tools/README.md](../ai_agent_tools/README.md) mục 2.
+
+## Gặp lỗi
+| Triệu chứng | Cách xử lý |
+|---|---|
+| `skip ... edited locally`, thoát mã 1 | Thư mục agent đã có folder trùng tên không do CLI tạo. Dùng `--force` nếu muốn thay |
+| Agent vẫn dùng skill cũ | Chạy `update`; mở phiên agent mới |
+| `npm run publish:npm` báo 403 cần 2FA | Thêm `-- --otp=<mã>`, hoặc dùng token granular có bypass 2FA |
+| `npm run validate` đỏ | Đọc dòng lỗi: thiếu `superAds`, sai thứ tự 21 mục, `SKILL.md` > 400 dòng, thư mục rỗng, link chết |
+
+## Phát triển
+[docs/AUTHORING.md](docs/AUTHORING.md): thêm skill, quy ước version, hai lớp kiểm tra, phát hành.

package/bin/super-ads-skills.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js'