devetai/better-skill-gen

Better Skill Generator (better-skill-gen)

Skill này đóng vai trò là một Meta-Skill: nhận ý tưởng, bài toán hoặc quy trình công việc từ người dùng, cùng người dùng chốt thiết kế, rồi sinh ra thư mục Skill hoàn chỉnh cho từng provider được chọn:

Provider	Thư mục (scope dự án)	Đặc điểm
Codex và Antigravity	.agents/skills/<skill-name>/ (một bản dùng chung)	Chỉ name, description; Codex có thêm agents/openai.yaml cho chính sách gọi skill
Claude Code	.claude/skills/<skill-name>/	Có thêm nhiều trường frontmatter mở rộng, xem references/frontmatter-spec.md

File này dùng chung cho Codex và Antigravity. Mọi đường dẫn scripts/..., references/... trong file này tính từ thư mục chứa SKILL.md này. "Chạy lệnh" nghĩa là dùng công cụ chạy lệnh shell của provider đang dùng (ví dụ run_command trong Antigravity).

---

1. Nguyên lý Thiết kế Cốt lõi

1. Kiến trúc Progressive Disclosure 3 Cấp độ:
   • Cấp 1: Metadata (Luôn nạp khi khởi động): name, description trong YAML Frontmatter. Tốn rất ít token; giữ description dưới 1.536 ký tự.
   • Cấp 2: Instructions (Chỉ nạp khi Skill được kích hoạt): Thân file SKILL.md, bắt buộc dưới 500 dòng. Chỉ chứa Workflow, Nguyên tắc cốt lõi và Ràng buộc.
   • Cấp 3: Resources (Chỉ nạp khi thật sự cần): templates/ (mẫu kết quả), examples/ (văn bản mẫu Gold Standard), references/ (thông số kỹ thuật), scripts/ (code bash/python xử lý việc nặng mà không tốn context).
2. Phân loại Mục đích Skill:
   • Reference Skills: Quy ước code, kiến thức hệ thống, design pattern, để agent áp dụng làm kiến thức nền.
   • Task Skills: Quy trình từng bước thực thi hành động. Tác vụ có tác dụng phụ (deploy, commit, xóa dữ liệu) phải chỉ chạy khi người dùng gọi trực tiếp. Bản .agents/skills/ làm cả hai việc: tạo agents/openai.yaml với policy.allow_implicit_invocation: false (cho Codex) và ghi câu "Chỉ dùng khi người dùng yêu cầu trực tiếp" vào description (cho Antigravity, vốn không có trường tương đương). Chi tiết ở references/providers.md mục 3.
3. Tính năng riêng của từng provider: Claude Code có subagent, biến tham số và tiêm lệnh shell trong SKILL.md (xem references/frontmatter-spec.md). Chỉ dùng chúng trong bản Claude Code; bản cho provider khác chuyển đổi theo references/providers.md mục 3.
4. Verify, Don't Trust (Tự kiểm chứng):
   • Mọi skill sinh ra phải đi kèm scripts/validate.sh với exit code chuẩn (0 = pass, 1 = fail).
   • Tuân thủ 100% các quy tắc linting theo chuẩn markdownlint.
5. Zero Workspace Pollution:
   • Mọi tệp cấu hình, tài nguyên và script chỉ nằm trong thư mục đóng gói của skill ở thư mục của từng provider.
   • Mọi tài liệu mẫu chỉ nằm trong examples/ của skill. Không sinh hoặc chép file mẫu ra thư mục nghiệp vụ khác của dự án (như src/, root project).
   • File tạm khi kiểm thử ghi vào thư mục tạm của hệ điều hành (hoặc thư mục tạm mà hướng dẫn của người dùng chỉ định) và dọn sạch ngay sau khi xong.
6. Hỏi người dùng bằng lựa chọn có cấu trúc:
   • Mọi lựa chọn đưa cho người dùng (scope, provider, điểm chưa rõ trong ý tưởng, hướng thiết kế) đều hỏi dưới dạng lựa chọn. Nếu phiên có công cụ hỏi người dùng dạng chọn đáp án thì dùng công cụ đó. Nếu không, liệt kê lựa chọn đánh số, rồi dừng và chờ người dùng trả lời.
   • Thứ tự trình bày: (1) skill định tạo làm gì, (2) câu hỏi hỏi gì và vì sao phát sinh, (3) các lựa chọn, mỗi lựa chọn một câu nêu được mất, (4) lựa chọn khuyến nghị, đặt đầu danh sách và ghi (khuyến nghị).
   • Hỏi tối đa 4 câu mỗi lượt, điểm quan trọng hỏi trước. Luôn cho phép người dùng trả lời khác các lựa chọn đã nêu.
   • Không tự chọn thay người dùng khi chưa có câu trả lời.
7. Mỗi provider một bản đúng chuẩn của provider đó:
   • Tài nguyên dùng chung (template.md, examples/, references/, scripts/) được chép y nguyên. Riêng SKILL.md (và agents/openai.yaml của Codex) được viết riêng: một bản cho Claude Code, một bản dùng chung cho Codex và Antigravity.
   • Bản Codex/Antigravity phải chạy đúng trên cả hai provider: chỉ dùng các trường frontmatter của chuẩn mở, không dùng biến hay công cụ chỉ Claude Code hiểu, và không gọi agent đang chạy là "Claude". Claude chỉ được nhắc khi là chủ đề của skill.

---

2. Đầu vào cần thiết (Inputs)

• Bắt buộc: Mô tả ý tưởng hoặc mục tiêu nghiệp vụ của skill cần tạo.
• Tùy chọn: Ràng buộc đặc thù, công cụ cần dùng, loại tác vụ hay tham khảo.
• Bắt buộc hỏi (mỗi lần tạo skill mới): Scope và provider (mục 2.1), cùng mọi điểm chưa rõ trong ý tưởng (mục 2.2). Chỉ bỏ qua câu hỏi nào người dùng đã trả lời rõ ngay trong yêu cầu.
• Không tự quyết điểm chưa rõ: Ý tưởng sơ sài thì phân tích và đề xuất (mục 2.2), không tự điền rồi sinh file. Chỉ điểm có quy ước hiển nhiên (ví dụ tên kebab-case suy ra từ ý tưởng) mới được tự đặt, và phải nêu ra trong bản tóm tắt thiết kế.

2.1. Hỏi phạm vi áp dụng (Scope) và Provider

Trước khi sinh bất kỳ file nào, hỏi 2 câu trong cùng một lượt theo nguyên lý 6:

1. Scope (chọn được nhiều): ba lựa chọn theo bảng dưới, project-shared là khuyến nghị.
2. Provider (chọn được nhiều): Codex, Claude Code, Antigravity. Nếu skill dùng được cho mọi provider thì khuyến nghị cả ba. Nếu skill chỉ có ý nghĩa với một provider (ví dụ chỉ kiểm tra file cấu hình của Claude Code) thì khuyến nghị riêng provider đó và nói rõ lý do.

Scope	Ý nghĩa	Gốc đích	Biến khi chạy script
project-shared	Riêng dự án hiện tại, cả team dùng chung (commit vào git)	Gốc dự án	SCOPE=project (mặc định)
project-personal	Riêng dự án hiện tại, chỉ riêng người dùng này (không commit)	Gốc dự án	SCOPE=project, rồi thêm các thư mục đã tạo vào .git/info/exclude
user-global	Mọi dự án của người dùng này	$HOME	SCOPE=user

Quy tắc:

• Người dùng chọn nhiều scope thì triển khai lần lượt từng scope.
• Thư mục dự án không phải git repo thì bỏ lựa chọn project-personal.
• Ghi scope và provider đã chọn vào báo cáo bàn giao cùng danh sách đường dẫn đã tạo.
• Skill có nội dung đặc thù dự án mà người dùng chọn user-global: cảnh báo một dòng trước khi tạo.

2.2. Phân tích ý tưởng và đề xuất

Sau khi có scope và provider, phân tích ý tưởng trước khi viết bất kỳ file nào:

1. Tóm tắt điều đã hiểu: skill giải quyết việc gì, ai dùng, khi nào kích hoạt, đầu ra là gì.
2. Xác định các điểm thiết kế, mỗi điểm ghi rõ là người dùng đã nói hay agent đang suy đoán:
   • Loại skill: Task hay Reference; có tác dụng phụ không.
   • Cách kích hoạt: tự động theo description, chỉ khi người dùng gọi trực tiếp, hay cả hai; cụm từ kích hoạt và trường hợp không dùng.
   • Đầu vào, tham số, và cách xử lý khi thiếu.
   • Đầu ra: định dạng, nơi lưu, có cần template.md và tiêu chí kiểm tra trong scripts/validate.sh không.
   • Cách thực thi: chỉ hướng dẫn hay cần script; công cụ cần dùng.
   • Phần tách ra references/, để SKILL.md dưới 500 dòng.
3. Đề xuất hướng tối ưu: với mỗi điểm còn có nhiều cách làm, nêu 2 đến 3 hướng kèm được mất, chọn một hướng khuyến nghị. Ví dụ: "kiểm tra bằng script scripts/check.sh (nhanh, chính xác, nhưng cần bash)" so với "agent tự đọc và đánh giá (linh hoạt, nhưng tốn token và dễ sót)".
4. Hỏi người dùng: gom mọi điểm chưa rõ và mọi điểm có nhiều hướng thành câu hỏi theo nguyên lý 6.
5. Chốt thiết kế: sau khi có câu trả lời, viết bản tóm tắt thiết kế (tên skill, loại, cách kích hoạt, danh sách file sẽ tạo, provider, scope, các giá trị agent tự đặt). 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.

2.3. Nghiên cứu provider

Trước khi viết bản cho provider nào, đọc references/providers.md:

• Nếu Ngày xác minh cũ hơn 30 ngày, skill cần tính năng chưa có trong file, hoặc thông tin trong file mâu thuẫn với thực tế: tra tài liệu chính thức ở mục 6 của file đó, sửa file, cập nhật ngày xác minh, rồi chép lại file sang các provider khác bằng scripts/sync-skill.sh better-skill-gen.
• Antigravity ở scope dự án dùng chung .agents/skills/ với Codex (mục 5). Không tạo .agent/skills/.
• Không đoán đặc tả của provider. Điểm nào không tra được thì nói rõ với người dùng và hỏi.

---

3. Quy trình thực hiện (Workflow)

flowchart TD
    A["Ý tưởng nghiệp vụ từ User"] --> A2["0. Hỏi Scope và Provider"]
    A2 --> B["1. Phân tích ý tưởng, đề xuất, hỏi điểm chưa rõ"]
    B --> B2["2. Nghiên cứu provider"]
    B2 --> C["3. Tham chiếu template.md & references/"]
    C --> D["4. Sinh bản gốc"]
    D --> E["5. Đồng bộ tài nguyên & viết SKILL.md riêng từng provider"]
    E --> F["6. Tự kiểm chứng bằng scripts/validate.sh"]
    F -->|Pass| G["Hoàn tất & Bàn giao"]
    F -->|Fail| D

0. Hỏi Scope và Provider: Thực hiện mục 2.1 và chờ câu trả lời trước khi làm tiếp.
1. Phân tích ý tưởng: Thực hiện mục 2.2 cho đến khi thiết kế được chốt. Đặt tên skill theo kebab-case ($\le 64$ ký tự, cấm trùng anthropic-skills, synced, claude, anthropic).
2. Nghiên cứu provider: Thực hiện mục 2.3 cho mọi provider đã chọn.
3. Tham chiếu tài liệu chuẩn: Đọc template.md (khung cấu trúc), references/providers.md (khác biệt giữa các provider), references/frontmatter-spec.md (trường của Claude Code) và examples/sample.md (phong cách viết và logic script).
4. Sinh bản gốc: Viết đủ các thành phần vào thư mục của provider đầu tiên được chọn:
   • SKILL.md: Frontmatter an toàn (quote/scalar block >-), dưới 500 dòng.
   • template.md (hoặc templates/): Mẫu đầu ra với các biến mẫu ${VARIABLE}.
   • examples/sample.md: Văn bản mẫu thực tế không còn placeholder.
   • references/ (nếu có tài liệu spec/kiến thức phức tạp cần tách rời).
   • scripts/validate.sh: Script kiểm tra tính toàn vẹn của kết quả.
   • Tài nguyên dùng chung viết trung lập với provider: script gọi bằng đường dẫn tương đối tính từ thư mục skill.
5. Triển khai theo provider:
   • Chép tài nguyên dùng chung: chạy PROVIDERS="<các provider đã chọn>" bash scripts/sync-skill.sh <skill-name>. Script chép mọi file trừ SKILL.md và agents/, và báo [TODO] cho provider còn thiếu SKILL.md.
   • Với thư mục còn lại, viết SKILL.md riêng theo bảng chuyển đổi ở references/providers.md mục 3. Viết lại câu chữ trong thân bài, không chỉ xóa trường frontmatter. Codex và Antigravity cùng chọn thì chỉ có một thư mục .agents/skills/, script tự gộp.
   • Skill có tác dụng phụ: bản .agents/skills/ tạo thêm agents/openai.yaml với policy.allow_implicit_invocation: false và ghi câu "Chỉ dùng khi người dùng yêu cầu trực tiếp" vào description.
   • Scope user-global: đặt thêm SCOPE=user khi chạy script.
   • Scope project-personal: thêm các thư mục skill vừa tạo vào .git/info/exclude (không sửa .gitignore, không commit).
6. Tự kiểm chứng (Self-Verification):
   • Chạy PROVIDERS="<các provider đã chọn>" bash scripts/validate.sh <skill-name> (thêm SCOPE=user nếu là user-global).
   • Script kiểm tra: frontmatter YAML hợp lệ, markdownlint, SKILL.md $\le 500$ dòng, đủ file bắt buộc ở mọi provider đã chọn, và SKILL.md của Codex/Antigravity không còn trường hay token chỉ Claude Code hiểu.
   • Đọc từng dòng [WARN]: nhắc tới Claude vì Claude là chủ đề thì giữ, nếu không thì sửa.
   • Có lỗi thì tự sửa cho đến khi nhận [PASS].

---

4. Ràng buộc & Tiêu chuẩn (Guardrails)

• QUY TẮC BẮT BUỘC (CRITICAL):
  • Mọi lựa chọn đều hỏi theo nguyên lý 6 và chờ trả lời trước khi làm tiếp.
  • Luôn hỏi scope và provider trước khi tạo skill mới (mục 2.1).
  • Không tự quyết điểm chưa rõ: phân tích, đề xuất và hỏi (mục 2.2) trước khi sinh file.
  • Nghiên cứu provider trước khi viết bản cho provider đó (mục 2.3); không đoán đặc tả.
  • Không chép nguyên xi SKILL.md giữa các provider: mỗi provider một bản đúng chuẩn riêng; validate.sh phải [PASS] cho mọi provider đã chọn.
  • Zero Workspace Pollution: tài liệu mẫu chỉ nằm trong examples/; không tạo file ngoài thư mục đóng gói của skill.
  • Giữ SKILL.md dưới 500 dòng: đẩy nội dung chi tiết sang references/ hoặc templates/.
  • Chuẩn hóa Frontmatter: description có dấu hai chấm : phải dùng scalar >- hoặc ngoặc kép "...".
  • Tuân thủ Markdownlint (MD001 - MD047) cho mọi file Markdown tạo ra.
• DOs (Nên làm):
  • Khai báo cơ chế "chỉ chạy khi người dùng gọi" cho mọi skill có tác dụng phụ, theo đúng cách của từng provider (Codex: agents/openai.yaml; Antigravity: câu trong description).
  • Sử dụng các biến mẫu template ${TEN_BIEN} có tính gợi tả cao trong template.
  • Dọn dẹp ngay các file tạm sinh ra trong quá trình kiểm thử tự động.
• DON'Ts (Không nên làm):
  • Không nhét toàn bộ tài liệu tham khảo dài vào thẳng SKILL.md.
  • Không để URL trần trong file markdown mà không có ngoặc <> hoặc markdown link.
  • Không dùng tên skill quá 64 ký tự hoặc chứa chữ hoa/ký tự đặc biệt.
  • Không gọi agent là "Claude" trong bản cho provider khác Claude Code.