@hungvv/super-ads-skills 1.0.0 → 1.1.0

package/README.md

@@ -1,14 +1,22 @@
 # SuperAds Skills
 
-Bộ skill SuperAds cho AI agent (Claude Code, Cursor, Codex, Antigravity), có CLI cài riêng. Danh mục và cây chọn skill: [skills/README.md](skills/README.md).
+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 (một lệnh)
+## Cài và update
 
 ```bash
-cd tools/super-ads-skills && npm ci && npm run build && npm link && super-ads-skills install
+# 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, bằng symlink về một bản chung `~/.local/share/super-ads-skills/skills`. Không có câu hỏi nào.
+- `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 |
 |---|---|
@@ -17,27 +25,77 @@ cd tools/super-ads-skills && npm ci && npm run build && npm link && super-ads-sk
 | Codex | `~/.agents/skills` |
 | Antigravity | `~/.gemini/config/skills`, `~/.gemini/antigravity-ide/builtin/skills` |
 
-## Update (một lệnh)
+Đừ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`.
 
-```bash
-git pull && super-ads-skills 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).
 
-Nhờ symlink, skill sửa trong clone có hiệu lực ngay cho mọi agent; `update` còn làm mới bản chung, ghi version vào manifest và gỡ skill đã bị loại khỏi bộ. Skill bị sửa tay trong thư mục agent được giữ nguyên, trừ khi thêm `--force`.
+## 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              # trạng thái từng skill
+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.
 
-Máy không có Node: `bash scripts/install-skills.sh` (Windows: `scripts/install-skills.ps1`). Cùng kết quả, chạy lại là update, không có `list`/`remove`.
+## 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
-Thêm skill, quy ước version, kiểm tra: [docs/AUTHORING.md](docs/AUTHORING.md).
+[docs/AUTHORING.md](docs/AUTHORING.md): thêm skill, quy ước version, hai lớp kiểm tra, phát hành.

package/dist/cli.js

@@ -174,7 +174,13 @@ var SkillFrontmatterSchema = z.object({
   name: z.string().regex(/^[a-z0-9-]+$/, "name must be kebab-case [a-z0-9-]").refine(isKitSkillName, `name must start with "${SKILL_PREFIX}-" or be one of: ${UNPREFIXED_SKILLS.join(", ")}`),
   description: z.string().min(1, "description is required"),
   version: z.string().refine((v) => !!semver.valid(v), "version must be valid semver"),
-  group: z.enum(GROUPS).optional()
+  group: z.enum(GROUPS).optional(),
+  /** SuperAds SDK versions this skill was written for, as a semver range. Agents compare it to the app's SDK. */
+  superAds: z.string().refine((range) => semver.validRange(range) !== null, 'superAds must be a valid semver range, e.g. ">=4.0.0 <5.0.0"')
+}).superRefine((data, ctx) => {
+  if (data.description.length > 120) {
+    ctx.addIssue({ code: z.ZodIssueCode.too_big, maximum: 120, type: "string", inclusive: true, path: ["description"], message: "description must be <= 120 chars" });
+  }
 });
 var IGNORED_ENTRIES = /* @__PURE__ */ new Set([".DS_Store", "Thumbs.db", ".super-ads-skills-meta.json"]);
 function listSkillFiles(dir) {
@@ -630,7 +636,7 @@ function runList(opts) {
   for (const skill of loadSkills()) {
     const s = skillStatus(skill, scope);
     const tag = { new: pc.dim("not installed"), installed: pc.green("installed"), outdated: pc.yellow("outdated"), modified: pc.red("modified") }[s.state];
-    console.log(`${skill.name.padEnd(28)} v${skill.version.padEnd(8)} ${tag}${s.agents.length ? pc.dim(`  [${s.agents.join(", ")}]`) : ""}`);
+    console.log(`${skill.name.padEnd(28)} v${skill.version.padEnd(8)} SDK ${skill.superAds.padEnd(16)} ${tag}${s.agents.length ? pc.dim(`  [${s.agents.join(", ")}]`) : ""}`);
   }
 }
 var program = new Command();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hungvv/super-ads-skills",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Agent skills for the SuperAds SDK - one command installs them for Claude Code, Cursor, Codex and Antigravity.",
   "type": "module",
   "license": "UNLICENSED",

package/skills/README.md

@@ -6,6 +6,8 @@ Bộ skill giúp agent gắn, dùng, debug và kiểm SuperAds trong **mọi app
 
 | Skill | Dùng khi |
 |---|---|
+| [super-ads-guide](super-ads-guide/SKILL.md) | **Điểm vào**: mọi việc liên quan SuperAds. Chọn skill chủ, kiểm version SDK của app |
+| [super-ads-upgrade](super-ads-upgrade/SKILL.md) | App dùng SuperAds thấp hơn range của skill, hoặc cần nâng SDK (import, logic, key config, changelog) |
 | [super-ads-integrate](super-ads-integrate/SKILL.md) | App chưa có SDK quảng cáo, cần gắn SuperAds từ đầu |
 | [adspro-to-superads](adspro-to-superads/SKILL.md) | App đang dùng AdsPro, cần chuyển sang SuperAds |
 | [super-ads-add-placement](super-ads-add-placement/SKILL.md) | App đã có SuperAds, thêm hoặc đổi vị trí ad |
@@ -20,6 +22,8 @@ Bộ skill giúp agent gắn, dùng, debug và kiểm SuperAds trong **mọi app
 ## Chọn skill
 
 ```
+Không chắc bắt đầu từ đâu? ────► super-ads-guide (bảng định tuyến + kiểm version SDK)
+SDK của app thấp hơn skill? ───► super-ads-upgrade
 App chưa có ads? ──────────────► super-ads-integrate ──► super-ads-add-placement
 App còn AdsPro? ───────────────► adspro-to-superads
 Thêm/đổi vị trí ad? ───────────► super-ads-add-placement ──► super-ads-adb-test