@anionzo/skill 1.1.0

package/i18n/CONTRIBUTING.vi.md

@@ -0,0 +1,302 @@
+<div align="center">
+
+# 🤝 Hướng Dẫn Đóng Góp
+
+**Cách đóng góp skill, knowledge, và cải tiến cho thư viện này**
+
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square&logo=github)](https://github.com/anionzo/skill/pulls)
+[![Skill Spec](https://img.shields.io/badge/read-skill_spec-blue?style=flat-square&logo=bookstack)](../docs/skill-spec.md)
+[![Authoring Guide](https://img.shields.io/badge/read-authoring_guide-purple?style=flat-square&logo=pencil)](../docs/authoring-guide.md)
+
+---
+
+🌐 **[English](../CONTRIBUTING.md)**
+
+</div>
+
+---
+
+> 🎯 Cảm ơn bạn đã quan tâm đóng góp! Hướng dẫn này cover mọi thứ bạn cần để thêm hoặc cải thiện skill, knowledge, và tooling trong repo này.
+
+### 📋 Mục Lục
+
+| | Phần |
+|---|---|
+| 🏁 | [Bắt Đầu Nhanh](#-bắt-đầu-nhanh) |
+| ➕ | [Thêm Skill Mới](#-thêm-skill-mới) |
+| ✏️ | [Sửa Skill Có Sẵn](#️-sửa-skill-có-sẵn) |
+| 📚 | [Đóng Góp Knowledge](#-đóng-góp-knowledge) |
+| 🔌 | [Cập Nhật Adapter](#-cập-nhật-adapter) |
+| ✅ | [Validation & Chất Lượng](#-validation--chất-lượng) |
+| 📐 | [Style & Quy Ước](#-style--quy-ước) |
+| 🔄 | [Quy Trình Pull Request](#-quy-trình-pull-request) |
+| 🚫 | [Những Điều Không Nên Làm](#-những-điều-không-nên-làm) |
+
+---
+
+### 🏁 Bắt Đầu Nhanh
+
+```bash
+# 1. Fork và clone repo
+git clone https://github.com/<your-username>/skill.git
+cd skill
+
+# 2. Tạo branch mới
+git branch feat/skill-moi
+git checkout feat/skill-moi
+
+# 3. Thực hiện thay đổi (xem các phần bên dưới)
+
+# 4. Validate
+bash scripts/validate-skills
+
+# 5. Sinh platform file
+bash scripts/sync-platform-files
+
+# 6. Commit và push
+git add .
+git commit -m "add skill: <ten-skill>"
+git push origin feat/skill-moi
+
+# 7. Mở Pull Request trên GitHub
+```
+
+---
+
+### ➕ Thêm Skill Mới
+
+Mỗi skill nằm trong thư mục riêng dưới `skills/`. Làm theo các bước sau:
+
+#### Bước 1 — Scaffold từ template
+
+```bash
+cp -r templates/ skills/<ten-skill>/
+```
+
+#### Bước 2 — Điền `meta.yaml`
+
+| Key | Bắt buộc | Mô tả |
+|---|---|---|
+| `name` | ✅ | Định danh skill (kebab-case) |
+| `version` | ✅ | Phiên bản semantic (`1.0.0`) |
+| `category` | ✅ | Một trong: `routing`, `discovery`, `planning`, `implementation`, `debugging`, `review`, `documentation`, `verification` |
+| `summary` | ✅ | Mô tả một dòng bằng tiếng Anh |
+| `summary_vi` | 🟡 | Mô tả một dòng bằng tiếng Việt |
+| `triggers` | 🟡 | Khi nào kích hoạt skill |
+| `inputs` | 🟡 | Skill cần gì |
+| `outputs` | 🟡 | Skill tạo ra gì |
+| `constraints` | 🟡 | Rào cản và giới hạn |
+| `related_skills` | 🟡 | Skill liên quan trong graph |
+
+> ✅ = bắt buộc &nbsp; 🟡 = khuyến nghị
+
+#### Bước 3 — Viết `SKILL.md`
+
+Theo cấu trúc từ [Skill Spec](../docs/skill-spec.md):
+
+```markdown
+# <Tên Skill>
+
+## 🎯 Mục Đích
+## ⏰ Khi Nào Dùng
+## 🔄 Workflow
+## 📋 Output Format
+## 🚩 Red Flag
+## ✅ Done Criteria
+## ➡️ Handoff
+```
+
+> 💡 Giữ tính **vận hành** — bước cụ thể, không phải lý thuyết trừu tượng. Xem [Authoring Guide](../docs/authoring-guide.md) để biết quy tắc viết chi tiết.
+
+#### Bước 4 — Thêm `examples.md`
+
+Bao gồm ít nhất một ví dụ thực tế với:
+
+- 🗣️ Một user request đại diện
+- 📋 Hình dạng response hoặc workflow dự kiến
+- ✅ Một ví dụ output đã hoàn thành
+
+#### Bước 5 — Thêm references (tùy chọn)
+
+Đặt file hỗ trợ trong `references/`:
+
+- 📋 Output template
+- ☑️ Checklist
+- 📊 Rubric
+- 🌳 Cây quyết định
+
+#### Bước 6 — Kết nối vào skill graph
+
+Cập nhật trường `related_skills` trong `meta.yaml` của các skill liên quan để router (`using-skills`) có thể tìm thấy skill mới của bạn.
+
+#### Bước 7 — Validate
+
+```bash
+bash scripts/validate-skills
+```
+
+Tất cả skill phải pass với **0 FAIL** và **0 WARN**.
+
+---
+
+### ✏️ Sửa Skill Có Sẵn
+
+| | Hướng dẫn |
+|---|---|
+| 🔹 | Ưu tiên **thu hẹp phạm vi** hơn là thêm nhánh |
+| 🔹 | Nếu skill xử lý quá nhiều trường hợp, **tách nó** thành hai |
+| 🔹 | Giữ output format ổn định — các skill downstream phụ thuộc vào nó |
+| 🔹 | Cập nhật `examples.md` nếu workflow thay đổi |
+| 🔹 | Tăng `version` trong `meta.yaml` |
+
+---
+
+### 📚 Đóng Góp Knowledge
+
+File knowledge nằm trong `knowledge/global/`. Chúng chứa nguyên tắc, heuristic, và pattern — **không phải** workflow từng bước (đó thuộc về skill).
+
+| File | Mục đích |
+|---|---|
+| 📐 `engineering-principles.md` | Giá trị coding cốt lõi |
+| 🔍 `review-heuristics.md` | Quy tắc code review |
+| 🐛 `debugging-patterns.md` | Phương pháp debug có hệ thống |
+| 🧠 `skill-triggering-rules.md` | Khi nào load skill nào |
+
+Khi thêm hoặc sửa knowledge:
+
+- 🔹 Giữ mục ngắn gọn và hành động được
+- 🔹 Tránh chi tiết dự án cụ thể — knowledge phải portable
+- 🔹 Mỗi mục phải giúp AI agent đưa ra quyết định tốt hơn
+
+---
+
+### 🔌 Cập Nhật Adapter
+
+Skeleton adapter trong `adapters/` định nghĩa cách sinh platform file. Nếu bạn thay đổi catalog skill hoặc cấu trúc knowledge:
+
+```bash
+# Sinh lại tất cả platform file
+bash scripts/sync-platform-files
+```
+
+> ⚠️ Không bao giờ sửa trực tiếp file trong `generated/` — chúng bị ghi đè mỗi lần sync.
+
+---
+
+### ✅ Validation & Chất Lượng
+
+Trước khi submit bất kỳ thay đổi nào, chạy:
+
+```bash
+# 1. Validate tất cả skill
+bash scripts/validate-skills
+
+# 2. Sinh lại platform file
+bash scripts/sync-platform-files
+```
+
+#### Checklist Chất Lượng
+
+| | Kiểm tra |
+|---|---|
+| 🏷️ | Tên skill cụ thể và mô tả được |
+| 📝 | Summary một câu và vẫn hữu ích |
+| 🔄 | Workflow thực hiện được mà không cần context riêng tư |
+| 📋 | Output format nhất quán |
+| 💡 | Ví dụ thực tế và có completed output |
+| ✅ | Done criteria yêu cầu bằng chứng, không phải ngôn ngữ mong muốn |
+| 🔗 | Graph `related_skills` nhất quán (link hai chiều) |
+| ⚙️ | `validate-skills` pass với 0 FAIL, 0 WARN |
+| 📦 | `sync-platform-files` chạy không lỗi |
+
+---
+
+### 📐 Style & Quy Ước
+
+| | Quy ước |
+|---|---|
+| 📁 | Thư mục skill dùng **kebab-case** (`feature-delivery`, không phải `FeatureDelivery`) |
+| 📄 | File skill: `meta.yaml`, `SKILL.md`, `examples.md`, `references/` |
+| 🌐 | Tài liệu phải **song ngữ** — tiếng Anh ở file chính, tiếng Việt ở `i18n/` |
+| 📂 | Bản dịch tiếng Việt đặt trong `i18n/<tên-file>.vi.md` |
+| 🔗 | File chính link đến bản dịch `i18n/`; bản dịch link ngược về file chính |
+| 🎨 | Dùng emoji icon, bảng, và badge — không viết text trơn |
+| 🔗 | Tất cả repo nguồn phải là **link clickable** đến GitHub |
+| 💬 | Commit message bằng **tiếng Anh**, rõ ràng và mô tả |
+| 📏 | Giữ `SKILL.md` dưới ~200 dòng — tách nếu dài hơn |
+
+---
+
+### 🔄 Quy Trình Pull Request
+
+```
+┌──────────────┐     ┌─────────────┐     ┌──────────────┐
+│  Fork & Code │────▶│  Validate   │────▶│  Mở PR       │
+│              │     │  & Sync     │     │              │
+└──────────────┘     └─────────────┘     └──────┬───────┘
+                                                │
+                                         ┌──────▼───────┐
+                                         │   Review     │
+                                         │   & Merge    │
+                                         └──────────────┘
+```
+
+#### Yêu Cầu PR
+
+| | Yêu cầu |
+|---|---|
+| 1️⃣ | Branch từ `main`, target `main` |
+| 2️⃣ | `bash scripts/validate-skills` pass với 0 lỗi |
+| 3️⃣ | `bash scripts/sync-platform-files` chạy sạch |
+| 4️⃣ | Tiêu đề PR theo format: `add skill: <tên>`, `fix: <mô tả>`, hoặc `update: <mô tả>` |
+| 5️⃣ | Mô tả PR giải thích **gì** thay đổi và **tại sao** |
+| 6️⃣ | Không có secret, token, hay đường dẫn máy cụ thể |
+| 7️⃣ | Không thay đổi `generated/` (đã gitignore) |
+
+---
+
+### 📦 Phát Hành Phiên Bản Mới
+
+Package được publish lên [npm](https://www.npmjs.com/package/@anionzo/skill) qua GitHub Actions workflow.
+
+#### Cách publish phiên bản mới:
+
+```bash
+# 1. Tăng version trong package.json
+npm version patch   # 1.0.0 → 1.0.1
+# hoặc
+npm version minor   # 1.0.0 → 1.1.0
+# hoặc
+npm version major   # 1.0.0 → 2.0.0
+
+# 2. Push version tag
+git push origin main --tags
+
+# 3. Tạo GitHub Release (kích hoạt workflow publish)
+gh release create v1.0.1 --generate-notes
+```
+
+> 💡 Workflow (`.github/workflows/publish.yml`) chạy validation, sinh platform file, và publish lên npm tự động.
+
+---
+
+### 🚫 Những Điều Không Nên Làm
+
+| | Anti-Pattern |
+|---|---|
+| ❌ | Commit file trong `generated/` — chúng được tự sinh |
+| ❌ | Tạo skill cố xử lý mọi trường hợp |
+| ❌ | Viết prompt mơ hồ kiểu "hãy là kỹ sư giỏi" |
+| ❌ | Nhúng secret, token, hay đường dẫn file local |
+| ❌ | Giả định cứng về một AI agent cụ thể |
+| ❌ | Sửa platform file trực tiếp thay vì sửa adapter |
+| ❌ | Bỏ qua validation trước khi mở PR |
+| ❌ | Viết docs chỉ tiếng Anh (bắt buộc song ngữ) |
+
+---
+
+<div align="center">
+
+**Xây dựng với 🤝 cho phát triển skill AI cộng tác**
+
+</div>

package/i18n/README.vi.md

@@ -0,0 +1,209 @@
+<div align="center">
+
+# 🧠 Thư Viện Skill AI Cá Nhân
+
+**Thư viện skill đa agent, vendor-neutral cho kỹ thuật phần mềm hỗ trợ AI**
+
+[![Skills](https://img.shields.io/badge/skills-10-blue?style=flat-square&logo=bookstack)](../skills/)
+[![Knowledge](https://img.shields.io/badge/knowledge-5_files-green?style=flat-square&logo=readme)](../knowledge/)
+[![Platforms](https://img.shields.io/badge/platforms-5_agents-purple?style=flat-square&logo=robot-framework)](../adapters/)
+[![License](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](../LICENSE)
+[![Contributing](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square&logo=github)](../CONTRIBUTING.md)
+[![npm](https://img.shields.io/npm/v/@anionzo/skill?style=flat-square&logo=npm&color=crimson)](https://www.npmjs.com/package/@anionzo/skill)
+
+---
+
+🌐 **[English](../README.md)**
+
+</div>
+
+---
+
+> 🎯 Giữ các workflow AI lặp lại ở một nơi. Tách skill khỏi kiến thức. Dùng được với mọi agent.
+
+Repo này nhẹ hơn một sản phẩm workflow đầy đủ. Nó lấy tư duy **workflow-first** từ `hoangnb24/skills`, hành vi **plan-first** từ các coding agent hiện đại như OpenCode, và tư duy **multi-platform** từ `knowns-dev/knowns` — rồi biến chúng thành thư viện cá nhân thực dụng.
+
+### 🏗️ Mục Tiêu Thiết Kế
+
+| | Mục tiêu |
+|---|---|
+| 🔹 | Skill nhỏ, cụ thể, tái sử dụng |
+| 🔹 | Kiến thức lưu tách biệt khỏi skill |
+| 🔹 | Adapter sinh tự động từ một nguồn — không viết tay |
+| 🔹 | Hoạt động mà không cần plugin runtime |
+
+### 📁 Cấu Trúc Repo
+
+```
+.
+├─ 📄 docs/                 → Spec, quy tắc viết, quyết định thiết kế
+├─ 🎯 skills/               → Định nghĩa skill tái sử dụng
+├─ 📚 knowledge/            → Kiến thức global, project, working
+├─ 📋 templates/            → Mẫu khởi tạo skill mới
+├─ 🔌 adapters/             → Hướng dẫn cho từng nền tảng
+├─ ⚙️ scripts/              → Script validate và sync
+├─ 🌐 i18n/                 → Bản dịch tiếng Việt
+└─ 📦 generated/            → Output tự sinh (đã gitignore)
+```
+
+### 🎯 Danh Mục Skill
+
+| | Skill | Mục đích |
+|---|---|---|
+| 🧭 | `using-skills` | Phân loại request và chọn đúng skill |
+| 💡 | `brainstorming` | Làm rõ ý tưởng mơ hồ trước khi lập plan |
+| 🗺️ | `repo-onboarding` | Hiểu codebase lạ trước khi hành động |
+| 📐 | `planning` | Biến request thành plan thực thi trước khi code |
+| 🚀 | `feature-delivery` | Triển khai feature với thay đổi tối thiểu, phù hợp repo |
+| 🐛 | `bug-triage` | Điều tra lỗi, regression, failure chưa rõ nguyên nhân |
+| ♻️ | `refactor-safe` | Tái cấu trúc code mà không thay đổi hành vi |
+| ✅ | `verification-before-completion` | Yêu cầu bằng chứng trước khi tuyên bố xong |
+| 🔍 | `code-review` | Review diff ưu tiên bug, regression, test gap |
+| 📝 | `docs-writer` | Cập nhật docs từ hành vi thực tế đã xác minh |
+
+### 🔄 Workflow Mặc Định
+
+```
+┌─────────────┐     ┌───────────────┐     ┌─────────────────┐
+│ using-skills │────▶│ brainstorming │────▶│ repo-onboarding │
+│  (router)    │     │ (nếu mơ hồ)  │     │ (nếu repo lạ)   │
+└──────┬───────┘     └───────┬───────┘     └────────┬────────┘
+       │                     │                      │
+       │                     ▼                      │
+       │              ┌──────────┐                  │
+       └─────────────▶│ planning │◀─────────────────┘
+                      └────┬─────┘
+                           │
+              ┌────────────┼────────────┐
+              ▼            ▼            ▼
+     ┌────────────┐ ┌───────────┐ ┌──────────────┐
+     │  feature-  │ │ bug-triage│ │ refactor-safe│
+     │  delivery  │ │           │ │              │
+     └─────┬──────┘ └─────┬─────┘ └──────┬───────┘
+           │              │              │
+           ▼              ▼              ▼
+     ┌─────────────────────────────────────────┐
+     │      verification-before-completion     │
+     └────────────────────┬────────────────────┘
+                          ▼
+                   ┌─────────────┐
+                   │ code-review │
+                   └─────────────┘
+```
+
+### 📖 Nghiên Cứu Tham Khảo
+
+| Nguồn | Pattern chính |
+|---|---|
+| 🏛️ [`anthropics/skills`](https://github.com/anthropics/skills) | Đóng gói skill tối giản, portable |
+| ⚡ [`obra/superpowers`](https://github.com/obra/superpowers) | Luồng brainstorm → plan → execute → verify |
+| 🧩 [`affaan-m/everything-claude-code`](https://github.com/affaan-m/everything-claude-code) | Mô hình phân lớp: skills, rules, memory, adapter |
+| 🗃️ [`knowns-dev/knowns`](https://github.com/knowns-dev/knowns) | Tách skill khỏi knowledge; sinh platform file tự động |
+| 📦 [`hoangnb24/skills`](https://github.com/hoangnb24/skills) | Thiết kế skill workflow-first với router và output contract |
+
+### 🚀 Bắt Đầu Nhanh
+
+```bash
+# 1. Hiểu hình dạng repo
+cat docs/design-brief.md
+
+# 2. Tùy chỉnh knowledge theo phong cách của bạn
+vim knowledge/global/engineering-principles.md
+
+# 3. Bắt đầu — router sẽ chọn đúng skill
+cat skills/using-skills/SKILL.md
+
+# 4. Validate các skill
+bash scripts/validate-skills
+
+# 5. Sinh platform file
+bash scripts/sync-platform-files
+```
+
+### 📦 Cài Đặt Qua npm
+
+> Có sẵn trên [npm](https://www.npmjs.com/package/@anionzo/skill) — không cần xác thực
+
+```bash
+# 1. Cài đặt package
+npm install @anionzo/skill
+
+# 2. Copy skills/knowledge vào project
+cp -r node_modules/@anionzo/skill/skills/ ./
+cp -r node_modules/@anionzo/skill/knowledge/ ./
+
+# 3. Sinh platform file
+bash node_modules/@anionzo/skill/scripts/sync-platform-files
+
+# 4. Copy output sang agent
+cp generated/CLAUDE.md ./   # hoặc OPENCODE.md, GEMINI.md, v.v.
+```
+
+> 💡 Hoặc clone repo trực tiếp nếu muốn chỉnh sửa skill tại chỗ.
+
+### 🔌 Tích Hợp Agent
+
+> Repo này là **nguồn sự thật duy nhất**. Các file sinh ra chỉ là artifact phân phối.
+
+| Agent | Copy từ | Copy tới |
+|---|---|---|
+| 🤖 Claude Code | `generated/CLAUDE.md` | `CLAUDE.md` |
+| ⚡ OpenCode | `generated/OPENCODE.md` | `OPENCODE.md` |
+| 💎 Gemini CLI | `generated/GEMINI.md` | `GEMINI.md` |
+| 🔧 Agent chung | `generated/AGENTS.md` | `AGENTS.md` |
+| 🐙 GitHub Copilot | `generated/copilot-instructions.md` | `.github/copilot-instructions.md` |
+
+### ➕ Tạo Skill Mới
+
+```bash
+# 1. Scaffold từ template
+cp -r templates/ skills/<ten-skill>/
+
+# 2. Sửa các file
+vim skills/<ten-skill>/meta.yaml
+vim skills/<ten-skill>/SKILL.md
+vim skills/<ten-skill>/examples.md
+
+# 3. Validate
+bash scripts/validate-skills
+```
+
+### ⚙️ Lệnh
+
+| Lệnh | Mục đích |
+|---|---|
+| `bash scripts/validate-skills` | Kiểm tra mọi skill có đủ file và key bắt buộc |
+| `bash scripts/sync-platform-files` | Sinh file hướng dẫn cho từng nền tảng |
+
+### 📋 Thứ Tự Tùy Chỉnh Khuyến Nghị
+
+1. 🥇 `knowledge/global/engineering-principles.md`
+2. 🥈 `knowledge/global/review-heuristics.md`
+3. 🥉 `knowledge/global/debugging-patterns.md`
+4. 🎯 Các skill bạn dùng hàng tuần
+5. 🔌 Adapter output cho hai agent bạn dùng nhiều nhất
+
+### 🤝 Đóng Góp
+
+Chào mừng đóng góp! Xem **[CONTRIBUTING.md](../CONTRIBUTING.md)** để biết:
+
+🇻🇳 [Hướng dẫn đóng góp tiếng Việt](../i18n/CONTRIBUTING.vi.md)
+
+- ➕ Cách thêm skill mới
+- ✏️ Cách sửa skill có sẵn
+- 📚 Cách đóng góp knowledge
+- 🔄 Quy trình pull request và quy ước
+
+### 📌 Ghi Chú
+
+- `generated/` bị gitignore — tái sinh bất kỳ lúc nào
+- Chưa ship plugin runtime hay MCP server
+- Bước tiếp theo: manifest machine-readable hoặc MCP bridge
+
+---
+
+<div align="center">
+
+**Xây dựng với ❤️ cho kỹ thuật phần mềm hỗ trợ AI**
+
+</div>

package/i18n/adapter-guide.vi.md

@@ -0,0 +1,62 @@
+# 🔌 Hướng Dẫn Adapter
+
+> 🌐 **[English](../docs/adapter-guide.md)**
+
+---
+
+### 🎯 Mục Tiêu
+
+Adapter giúp cùng một thư viện skill dùng được trên nhiều nền tảng agent mà không cần viết lại nội dung core.
+
+> 📁 File core ở trong `skills/` và `knowledge/`.
+> 📦 File platform-specific được sinh vào `generated/`.
+
+### 🤖 Các Nền Tảng Hiện Tại
+
+| | Agent | File output |
+|---|---|---|
+| 🤖 | Claude Code | `CLAUDE.md` |
+| ⚡ | OpenCode | `OPENCODE.md` |
+| 💎 | Gemini CLI | `GEMINI.md` |
+| 🔧 | Agent chung | `AGENTS.md` |
+| 🐙 | GitHub Copilot | `.github/copilot-instructions.md` |
+
+### 📋 Chiến Lược Hiện Tại
+
+Phiên bản đầu không cố dịch toàn bộ mỗi skill sang cú pháp platform-specific.
+
+Thay vào đó, nó sinh file platform ngắn gọn:
+
+- 🧭 Trỏ đến skill router core
+- 📚 Trỏ đến các file knowledge quan trọng nhất
+- 📋 Bao gồm danh mục skill nhỏ
+- 📏 Nêu quy tắc làm việc ổn định xuyên nền tảng
+
+> 💡 Điều này giữ artifact phân phối ngắn và giảm drift.
+
+### 🔄 Luồng Sync
+
+```bash
+bash scripts/sync-platform-files
+```
+
+Lệnh này ghi file mới vào `generated/`.
+
+### 📋 Luồng Copy
+
+Sau khi sync, copy file output sang repo đích:
+
+| Nguồn | Đích |
+|---|---|
+| `generated/CLAUDE.md` | `CLAUDE.md` |
+| `generated/OPENCODE.md` | `OPENCODE.md` |
+| `generated/GEMINI.md` | `GEMINI.md` |
+| `generated/AGENTS.md` | `AGENTS.md` |
+| `generated/copilot-instructions.md` | `.github/copilot-instructions.md` |
+
+### 🔮 Cải Tiến Tương Lai
+
+- 📋 Skill manifest machine-readable
+- 🏷️ Sync chọn lọc theo tag hoặc nền tảng
+- 📁 Project overlay tự động thêm `knowledge/project/`
+- 🔌 Phân phối qua MCP hoặc CLI cho skill discovery

package/i18n/authoring-guide.vi.md

@@ -0,0 +1,69 @@
+# ✍️ Hướng Dẫn Viết Skill
+
+> 🌐 **[English](../docs/authoring-guide.md)**
+
+---
+
+### ➕ Tạo Skill Mới
+
+```
+Bước 1  📁  Tạo skills/<ten>/
+Bước 2  📋  Copy các file từ templates/
+Bước 3  📄  Điền meta.yaml trước
+Bước 4  📖  Viết SKILL.md xoay quanh một công việc lặp lại
+Bước 5  💡  Thêm một ví dụ thực tế
+Bước 6  📂  Thêm file hỗ trợ trong references/ nếu cần
+Bước 7  ✅  Chạy bash scripts/validate-skills
+```
+
+### 📄 Viết `meta.yaml`
+
+Bắt đầu bằng cách trả lời bốn câu hỏi:
+
+| # | Câu hỏi |
+|---|---|
+| 1️⃣ | Skill tên gì? |
+| 2️⃣ | Thuộc category nào? |
+| 3️⃣ | Giải quyết vấn đề gì? |
+| 4️⃣ | Khi nào agent nên dùng nó? |
+
+> ⚠️ Nếu agent khó quyết định khi nào load skill, metadata vẫn còn quá mơ hồ.
+
+### 📖 Viết `SKILL.md`
+
+Skill file tốt mang tính **vận hành**:
+
+- ⏰ Mô tả khi nào skill nên được load
+- 🔢 Cho một số ít bước cụ thể
+- 📋 Định nghĩa cách báo cáo kết quả
+- 🚩 Chỉ ra các lỗi phổ biến mà skill nhằm ngăn chặn
+- ➡️ Định nghĩa skill có handoff sang skill khác hay kết thúc luồng
+
+### 💡 Ví Dụ
+
+Ví dụ nên giống **prompt hoặc task thực tế**, không phải mô tả trừu tượng.
+
+Bao gồm:
+
+- 🗣️ Một user request đại diện
+- 📋 Hình dạng response hoặc workflow dự kiến
+- 🔑 Giả định chính ảnh hưởng routing
+
+### ☑️ Checklist Review
+
+Trước khi giữ skill mới, kiểm tra:
+
+| | Kiểm tra |
+|---|---|
+| 🏷️ | Tên cụ thể |
+| 📝 | Summary một câu và vẫn hữu ích |
+| 🔄 | Workflow có thể thực hiện mà không cần context riêng tư |
+| 📋 | Output format nhất quán |
+| 💡 | Ví dụ thực tế |
+| ✅ | Done criteria yêu cầu bằng chứng, không phải ngôn ngữ mong muốn |
+
+### ✏️ Sửa Skill Có Sẵn
+
+Khi tinh chỉnh skill, ưu tiên **thu hẹp phạm vi** hơn là thêm nhánh.
+
+> 💡 Nếu skill bắt đầu xử lý quá nhiều trường hợp không liên quan, **tách nó** thành hai skill thay vì làm một file khó suy luận hơn.