devetai/better-plugin-gen

Better Plugin Generator (better-plugin-gen)

Skill này giúp người dùng tạo một plugin: một thư mục gói nhiều thành phần (component) như skill, agent, hook, MCP server để cài vào coding agent bằng một lệnh. Skill hỗ trợ ba host (công cụ agent nạp plugin): Claude Code, Codex, Antigravity. Mỗi host có manifest riêng; skill dùng chung thư mục skills/ và sinh manifest cho từng host được chọn.

Mọi đường dẫn template.md, references/, examples/, scripts/ dưới đây tính từ thư mục chứa file SKILL.md này.

---

1. Nguyên lý cốt lõi

1. Hỏi trước, sinh sau. Mọi lựa chọn hỏi người dùng bằng công cụ hỏi có cấu trúc nếu phiên có; nếu không, liệt kê lựa chọn đánh số, ghi rõ lựa chọn khuyến nghị và dừng chờ trả lời. Trước mỗi lần hỏi, viết ngắn: plugin định tạo làm gì, câu hỏi hỏi gì và vì sao phát sinh. Không tự điền điểm chưa rõ rồi sinh file.
2. Không đoán đặc tả host. Vị trí file, định dạng manifest và MCP theo references/hosts.md. Điểm ghi "chưa xác minh" phải báo người dùng.
3. Logic chính đặt trong skill. Skill là component duy nhất chạy trên cả ba host. Agent, command, hook, LSP chỉ thêm khi người dùng cần và host hỗ trợ.
4. Khung tối giản chạy được. Mỗi component sinh ra phải chạy được ngay nhưng ngắn. Nếu dự án có skill better-skill-gen hoặc better-agent-gen, đề nghị người dùng dùng chúng để viết kỹ skill hay agent sau khi plugin đã chạy.
5. Tự kiểm chứng. Plugin chỉ được bàn giao khi scripts/validate.sh trả exit code 0.
6. Không có tác dụng phụ ra ngoài. Skill chỉ ghi file trong thư mục plugin đích (và file marketplace ở gốc repo nếu người dùng chọn). Không chạy git commit, git push, không cài plugin, không sửa cấu hình host của người dùng; chỉ in lệnh để họ tự chạy.

---

2. Đầu vào

• Bắt buộc: plugin dùng để làm gì (một câu cũng được), hoặc đường dẫn plugin có sẵn khi muốn thêm component. Lấy từ yêu cầu của người dùng.
• Hỏi nếu chưa có: host đích, vị trí thư mục, danh sách component, có marketplace không, tên plugin, tác giả, giấy phép.
• Thiếu thông tin: hỏi theo mục 3 bước 2; không có câu trả lời thì dừng chờ.

---

3. Quy trình

Bước 1: Xác định chế độ và đọc hiện trạng

• Tạo mới: người dùng mô tả plugin, chưa có thư mục.
• Thêm component / thêm host: người dùng đưa đường dẫn có .claude-plugin/plugin.json, .codex-plugin/plugin.json hoặc plugin.json. Đọc mọi manifest, liệt kê component đang có, chạy lệnh shell bash scripts/validate.sh <dir> để biết lỗi sẵn có trước khi sửa.
• Tạo marketplace: người dùng đã có plugin, chỉ cần phát hành. Đọc plugin như trên rồi sang bước 6.
• Đọc references/hosts.md. Nếu Ngày xác minh cũ hơn 30 ngày, hoặc plugin cần tính năng chưa có trong file: tra nguồn ở mục 6 của file đó trên web, cập nhật file và ngày xác minh, rồi báo người dùng phần đã đổi.

Bước 2: Hỏi người dùng

Tóm tắt điều đã hiểu (plugin làm gì, ai dùng, chạy khi nào), rồi hỏi đợt 1, bỏ câu nào người dùng đã trả lời rõ:

Câu hỏi	Kiểu	Lựa chọn (khuyến nghị đứng đầu)
Plugin chạy trên host nào?	Chọn nhiều	Claude Code; Codex; Antigravity. Khuyến nghị cả ba nếu plugin chỉ gồm skill và MCP; chỉ Claude Code nếu cần hook, LSP hay userConfig
Đặt plugin ở đâu?	Chọn một	Repo riêng, plugin ở gốc (./<tên>/); trong repo marketplace (plugins/<tên>/); trong dự án hiện tại để thử
Plugin gồm những component nào?	Chọn nhiều	Skill; Agent; Hook; MCP server; Command; LSP; userConfig
Có tạo marketplace để phát hành không?	Chọn một	Có, cho các host đã chọn; Chưa, chỉ thử trên máy

Đợt 2 (nếu cần): tên plugin (đề xuất tên kebab-case suy từ mô tả), tác giả và chủ repo GitHub, giấy phép, chi tiết từng component (skill làm gì, agent được dùng công cụ nào, hook chạy ở sự kiện nào, MCP server nào và có cần token không).

Quy tắc khi hỏi:

• Người dùng chọn hook cùng host khác Claude Code: báo trước xung đột ở references/hosts.md mục 4, hỏi có giữ hook không.
• Plugin cần token hoặc mật khẩu: hỏi cách cấp (Claude Code: userConfig có sensitive: true; host khác: biến môi trường ghi trong README). Không bao giờ ghi giá trị bí mật vào file.
• Tên trùng tên bị cấm của Claude Code (references/hosts.md mục 2.1): đề xuất tên khác.
• Thư mục đích đã có file: liệt kê file sẽ bị ghi đè và hỏi trước khi ghi.

Bước 3: Chốt thiết kế

Viết bản tóm tắt trong chat: tên, host, vị trí, cây thư mục sẽ tạo (đánh dấu host của từng file), component nào chạy trên host nào, giá trị agent tự đặt, điểm chưa xác minh. Nếu câu trả lời làm phát sinh điểm chưa rõ mới thì hỏi tiếp, chưa sinh file.

Bước 4: Sinh file

1. Đọc template.md (khung từng file) và references/components.md (định dạng từng component). Đọc examples/sample.md để nắm mức chi tiết mong muốn.
2. Ghi manifest cho từng host đã chọn. name, version, description giống hệt nhau ở mọi manifest.
3. Ghi component ở gốc plugin, không đặt trong .claude-plugin/ hay .codex-plugin/:
   • Skill: skills/<tên>/SKILL.md, frontmatter chỉ name, description, để mọi host đọc được.
   • MCP: .mcp.json cho Claude Code, Codex; mcp_config.json cho Antigravity (server từ xa dùng serverUrl). Hai file cùng danh sách server.
   • Hook: hooks/hooks.json bọc trong khóa "hooks", luôn có matcher, gọi script bằng "${CLAUDE_PLUGIN_ROOT}" (biến của Claude Code). Script đặt ở scripts/, có shebang.
   • Agent, command, LSP, userConfig: theo references/components.md.
4. Ghi README.md từ khung File 8, tối thiểu 40 từ, có bảng component theo host và lệnh cài cho từng host (references/publishing.md mục 5).
5. Chế độ thêm component: chỉ thêm file mới và sửa đúng khóa cần sửa trong manifest; tăng version (bản vá) ở mọi manifest nếu plugin đã phát hành.

Bước 5: Tự kiểm chứng

1. Chạy lệnh shell HOSTS="<các host đã chọn>" bash scripts/validate.sh <thư-mục-plugin-hoặc-repo>. Ví dụ HOSTS="claude codex antigravity".
2. Script chạy check_plugin.py (manifest, tên, đường dẫn, MCP, hook, skill, agent, marketplace, placeholder, chuỗi giống bí mật), rồi claude plugin validate và agy plugin validate nếu máy có các lệnh đó.
3. Có [FAIL] hoặc CLI báo lỗi: sửa file, chạy lại cho tới khi exit code 0.
4. Đọc từng [WARN]: sửa nếu sửa được; nếu giữ (ví dụ cảnh báo hook đa host đã báo người dùng) thì ghi lý do vào báo cáo bàn giao.
5. Cần file tạm thì ghi vào thư mục tạm mà hướng dẫn của người dùng chỉ định, không có thì dùng thư mục tạm của hệ điều hành; xóa ngay sau khi kiểm xong.

Bước 6: Marketplace (nếu chọn)

• Claude Code: .claude-plugin/marketplace.json ở gốc repo (khung File 9).
• Codex: .agents/plugins/marketplace.json ở gốc repo (khung File 10).
• Antigravity: không cần file; README ghi lệnh agy plugin install kèm URL repo GitHub, ví dụ https://github.com/phucbui/pr-review-kit.
• Chạy lại bước 5 với thư mục gốc repo để kiểm cả marketplace.

Bước 7: Bàn giao

In báo cáo theo khung "Báo cáo bàn giao" cuối template.md: thư mục, host, kết quả kiểm tra, bảng file, điểm chưa xác minh, lệnh thử trên máy, lệnh phát hành cho người dùng tự chạy (references/publishing.md mục 3 đến 6). Nếu có better-skill-gen hay better-agent-gen trong dự án, gợi ý một dòng cách dùng chúng để viết kỹ component.

---

4. Ràng buộc

• Bắt buộc:
  • Hỏi host, vị trí, component, marketplace trước khi tạo file; không tự quyết điểm chưa rõ.
  • Chỉ ghi trong thư mục plugin đích và file marketplace ở gốc repo; không tạo file mẫu ở nơi khác. Ví dụ mẫu chỉ nằm trong examples/ của skill này.
  • Không chạy git commit, git push, claude plugin install, agy plugin install, codex plugin marketplace add; chỉ in lệnh.
  • Không ghi token, mật khẩu, khóa API vào bất kỳ file nào.
  • Bàn giao chỉ khi scripts/validate.sh exit 0.
• Nên:
  • Đặt tên plugin, skill, agent kebab-case; phiên bản đầu 0.1.0.
  • Giữ plugin tập trung vào một mục đích; tách plugin nếu người dùng gom việc không liên quan.
  • Ghi rõ trong README component nào chạy trên host nào.
• Không nên:
  • Không chép nguyên SKILL.md có trường riêng của Claude Code vào plugin dùng cho Codex hay Antigravity.
  • Không dùng đường dẫn tuyệt đối hay .. trong manifest, hook, MCP.
  • Không đặt CLAUDE.md ở gốc plugin; hướng dẫn cần nạp thì đưa vào skill.