Cách mình viết skill cho AI - một lần, dùng mãi

✍️ Hana · 🗓️ Tháng 5/2026 📚 Series: Làm Cùng với AI · BA Edition 🔢 Order: 9

Màn hình VS Code mở SKILL.md - prd-writing skill mình viết cho Claude Code tại VNG

---

Cái moment mình nhận ra mình đang lãng phí thời gian

Tháng 11 năm 2025, anh Vũ PO ping mình: "Em viết PRD cho multi-AZ control plane của VKS nhé, deadline thứ tư."

Mình mở Claude, bắt đầu gõ cái đoạn quen thuộc: "Tôi là BA tại VNG Cloud, team cần PRD theo 8 sections - Overview, User Stories theo Gherkin, FR phải measurable, NFR..." 15 dòng setup. Mình gõ từng chữ, lần này giống hệt lần trước.

Rồi mình dừng lại.

Đây là lần thứ mấy rồi? Tháng trước viết PRD cho tag management của VKS - 15 dòng setup. Trước đó nữa là PostgreSQL Cluster cho vDB - cũng 15 dòng đó. Mình đang dạy AI một thứ đã biết, cứ mỗi lần một tab mới là AI quên sạch từ đầu, mình lại gõ lại từ đầu.

Hôm đó mình không mở file PRD. Mình mở một file mới, đặt tên SKILL.md.

---

Mình từng tưởng system prompt là đủ

Trước đó mình cũng không phải không có "solution". Mình có một đoạn text dài paste vào đầu mỗi session - đại loại là "bạn là BA assistant, khi tôi nói viết PRD thì làm theo 8 sections này...". Đôi khi mình save thành snippet trong Raycast để paste nhanh.

Nhưng có ba vấn đề mình không giải quyết được.

Thứ nhất, snippet đó ai cũng gõ giống nhau được. Không có gì trong đó là của riêng workflow VNG - không có template thực tế, không có reference về cách team mình đặt tên section. AI đọc xong vẫn hỏi thêm mấy câu cơ bản.

Thứ hai, mỗi lần workflow thay đổi - team thêm section Risks, đổi sang format AC mới - mình phải đi tìm lại snippet, sửa, paste lại. Không có version control, không có nguồn sự thật duy nhất.

Thứ ba, không scale được. Anh Minh tuần sau cũng cần viết PRD - mình "dạy" anh ấy bằng cách gửi snippet qua Slack, anh ấy copy về dùng, rồi mỗi người sửa một kiểu. Không ai cập nhật khi có thay đổi.

Skill giải quyết ba cái đó cùng lúc.

---

Cấu trúc một SKILL.md từ đầu

Một Skill gồm một file bắt buộc và thư mục resources tùy chọn. Cấu trúc chuẩn trông như này:

skill-name/
+-- SKILL.md          <- bắt buộc
|   +-- YAML frontmatter (name + description)
|   +-- Markdown instructions
+-- references/       <- tùy chọn, load khi cần
|   +-- template.md
|   +-- checklist.md
+-- assets/           <- tùy chọn, dùng trong output
    +-- output-template.md

Có ba lớp tải - đây là phần mình thấy thiết kế nhất trong chuẩn skill của Anthropic:

Lớp 1 - Metadata (~100 từ, luôn trong context): Tên và description trong YAML frontmatter. AI đọc cái này để quyết định "skill này có liên quan không".

Lớp 2 - SKILL.md body (< 500 dòng, tải khi kích hoạt): Workflow, decision tree, rules. Phần mình viết nhiều nhất.

Lớp 3 - Resources (không giới hạn, tải đúng lúc cần): Template dài, checklist chi tiết, reference docs. Không cần nhét hết vào SKILL.md.

Ba lớp đó giải quyết bài toán context window - AI không cần tải 300 dòng template PRD mỗi lần ai hỏi một câu không liên quan.

Viết YAML frontmatter

---
name: prd-writing
description: >-
  Viết Product Requirements Document (PRD) chuẩn VNG Cloud cho feature.
  Dùng khi user nói "viết PRD", "soạn spec", "tạo tài liệu yêu cầu",
  "draft PRD", "cần PRD cho feature X".
  Tự động viết 8 sections theo chuẩn template nội bộ.
---

Description là thứ quan trọng nhất - nó là trigger list. AI đọc cái này để quyết định khi nào chạy skill. Mình viết đủ các cách người ta hay nói: "viết PRD", "soạn spec", "tài liệu yêu cầu" - không phải lúc nào cũng dùng đúng từ PRD.

Viết phần instructions

Phần thân Markdown là workflow thực tế. Cái mình thấy hay nhất khi ngồi viết prd-writing/SKILL.md là quá trình đó buộc mình nghĩ lại từ đầu. Trước đó mình viết PRD theo cảm tính - bắt đầu từ chỗ nào tùy hứng. Khi phải viết thành instruction, mình phải đặt câu hỏi: "bước nào là bước đầu tiên, luôn luôn?"

Câu trả lời là: validate input. Người ta nói "viết PRD cho export log" - thông tin đó đủ chưa? Nếu chưa thì hỏi gì? Nếu họ paste intake form đầy đủ vào thì làm gì khác? Viết SKILL.md tốt là viết được cái decision tree đó rõ ràng.

---

Dùng AI để viết skill - không phải irony

Anthropic có một skill tên là skill-creator - dùng để viết Skill cho AI. Lần đầu mình đọc thấy buồn cười, nhưng nghĩ lại thì hoàn toàn hợp lý: bạn đang dạy AI cách nghĩ theo một domain cụ thể. AI giúp được phần structure, còn phần domain knowledge là của bạn.

Workflow mình hay dùng khi viết skill mới:

1. Brain-dump tự do: "Mình muốn skill này làm gì, trigger khi nào, output là gì, bước nào không được bỏ qua, edge case nào hay gặp..."
2. AI chuyển brain-dump thành YAML frontmatter + structured Markdown theo chuẩn
3. Mình đọc lại và điền những thứ AI không có context để biết

Bước 3 tốn thời gian hơn bước 1 và 2 cộng lại. AI sẽ viết skill trông rất đẹp, rất chuẩn cấu trúc - nhưng những chi tiết như "với VNG Cloud thì section Technical Notes phải mention quota limit của từng tier vì dev hay hỏi cái đó" thì chỉ mình mới có. Đó là phần không thể delegate.

prd-writing/SKILL.md hiện của mình là 328 dòng. Có workflow diagram text, decision tree, reference đến 5 file trong /references và /assets. Phần mình viết tay khoảng 60%, phần AI draft ban đầu khoảng 40%.

---

Viết xong không phải là xong - phần mình hay bỏ qua nhất

Lần đầu mình viết xong prd-writing/SKILL.md, mình chạy thử một case - PRD cho feature export log - output trông ổn, mình nghĩ xong. Deploy luôn.

Tuần sau anh Minh dùng skill đó cho một PRD khác - feature billing. Output section User Stories bị thiếu business rule về chu kỳ thanh toán, AI tự suy luận ra một con số không tồn tại trong hệ thống. Không phải AI bịa bậy - là skill của mình không có instruction đủ rõ cho trường hợp feature liên quan đến billing logic.

Cái sai là mình nghĩ "chạy một lần được là được". Không phải vậy.

Skill ổn định khi output đúng qua nhiều case khác nhau liên tiếp - không phải một case.

Sau lần đó mình có một checklist test trước khi coi skill là "production ready":

1. Test ít nhất 3-5 case khác nhau - không phải 3 case giống nhau. Case đơn giản, case phức tạp, case có thông tin thiếu, case có thông tin thừa. Nếu skill PRD, test với feature CRUD đơn giản, feature có nhiều integration, feature business-logic nặng.
2. So output với "mẫu vàng" - cái bạn tự làm tay tốt nhất - đặt hai bản cạnh nhau, đọc từng section. Chỗ nào AI viết khác với cách mình hay viết, đó là chỗ cần thêm instruction hoặc ví dụ vào SKILL.md.
3. Test edge case - thứ người dùng thật hay làm sai - input mơ hồ ("viết PRD cho tính năng mới"), input thiếu (scope không có), input tiếng Anh trong khi instruction tiếng Việt. Skill phải handle được những cái đó hoặc hỏi lại đúng chỗ.
4. Lặp lại cho đến khi output nhất quán - nếu cùng một input, chạy hai lần ra hai kết quả khác nhau đáng kể, là skill còn mơ hồ ở chỗ nào đó. Tìm chỗ đó và làm rõ hơn.

Với prd-writing, mình mất thêm hai tuần sau khi "xong" để test thêm 8 case nữa - multi-AZ control plane, PostgreSQL Cluster, Redis Cluster, PM Agent, Backup Cluster, Zoho CRM Agent, OpenClaw one-click deploy, và Tag for Nodegroup. Mỗi case phát hiện một chỗ instruction còn thiếu hoặc mơ hồ. Sau 8 case đó, output bắt đầu nhất quán. Mình mới coi là ổn.

Quy tắc đơn giản mình hay dùng: khi nào bạn chạy 3 case liên tiếp mà không cần sửa gì trong output, skill mới ổn định.

---

Một thứ mình không ngờ khi viết skill xong

Skill không thay thế được cái việc bạn phải biết mình muốn gì.

Mình thấy nhiều người nghĩ viết skill là gõ vài câu để AI "tự làm". Thực ra viết skill tốt đòi bạn phải hiểu workflow của mình rõ hơn cả khi làm tay - vì bây giờ phải viết nó ra. Cái lợi ích ẩn là skill buộc bạn document quy trình. Khi ai cần viết PRD hay Userguide, mình không cần "dạy miệng" nữa - share folder skills là xong.

Skill không giúp bạn biết phải làm gì. Skill giúp bạn không phải giải thích lại những gì mình đã biết phải làm.

Lần gần nhất bạn gõ cùng một đoạn hướng dẫn cho AI lần thứ ba trong tuần - đó là lúc bạn nên ngồi viết skill thay vì gõ lại lần thứ tư.

---

Bài này thuộc series "Làm Cùng với AI · BA Edition". Xem thêm: Cách mình viết PRD cùng với AI · Cách mình chạy workflow bằng skill cho AI