ayrisdev/app-store-optimization
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: restructure translation formatting - moving all localized content to docs/vietnamese

Browse Source
This commit is contained in:
sck_0
2026-01-28 18:01:08 +01:00
committed by Đỗ Khắc Gia Khoa
parent 76e0dffad7
commit a16b57e581
31 changed files with 3024 additions and 1423 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
docs/vietnamese/BUNDLES.md Normal file
View File

@@ -0,0 +1,124 @@
# 📦 Gói Kỹ năng Antigravity (Skill Bundles)
Bạn không biết bắt đầu từ đâu? Hãy chọn một gói dưới đây để sỡ hữu bộ kỹ năng được tuyển chọn phù hợp cho vai trò của bạn.
## 🚀 Gói Khởi đầu "Thiết yếu" (Essentials)
_Dành cho tất cả mọi người. Hãy cài đặt những kỹ năng này đầu tiên._
- `concise-planning`: Luôn bắt đầu bằng một kế hoạch.
- `lint-and-validate`: Giữ code sạch sẽ một cách tự động.
- `git-pushing`: Lưu công việc của bạn một cách an toàn.
- `kaizen`: Tư duy cải tiến liên tục.
## 🛡️ Gói "Kỹ sư Bảo mật" (Security Engineer)
_Dành cho pentesting, kiểm tra (auditing) và tăng cường bảo mật (hardening)._
- `ethical-hacking-methodology`: "Kinh thánh" về hacking đạo đức.
- `burp-suite-testing`: Quét lỗ hổng web.
- `owasp-top-10`: Kiểm tra các lỗi phổ biến nhất.
- `linux-privilege-escalation`: Đánh giá bảo mật Linux nâng cao.
- `cloud-penetration-testing`: Bảo mật AWS/Azure/GCP.
## 🌐 Gói "Phù thủy Web" (Web Wizard)
_Để xây dựng các ứng dụng web hiện đại, hiệu suất cao._
- `frontend-design`: Hướng dẫn về UI và thẩm mỹ.
- `react-patterns`: Các thực hành tốt nhất cho React (nếu có sẵn).
- `tailwind-patterns`: Siêu năng lực tạo kiểu (styling).
- `form-cro`: Tối ưu hóa các biểu mẫu để tăng tỷ lệ chuyển đổi.
- `seo-audit`: Giúp trang web của bạn xuất hiện trên Google.
## 🤖 Gói "Kiến trúc sư Agent" (Agent Architect)
_Để xây dựng các hệ thống AI._
- `agent-evaluation`: Kiểm tra các trợ lý AI (agents) của bạn.
- `langgraph`: Xây dựng quy trình làm việc agent có trạng thái (stateful).
- `mcp-builder`: Tự tạo các công cụ của riêng bạn.
- `prompt-engineering`: Làm chủ nghệ thuật giao tiếp với LLM.
## 🎮 Gói "Lập trình viên Game Độc lập" (Indie Game Dev)
_Đế xây dựng trò chơi với sự trợ giúp của AI._
- `game-development/game-design`: Cơ chế và vòng lặp trò chơi.
- `game-development/2d-games`: Sprite và vật lý 2D.
- `game-development/3d-games`: Mô hình 3D và shader.
- `game-development/unity-csharp`: Làm chủ lập trình C#.
- `algorithmic-art`: Tạo tài nguyên game (assets) bằng code.
## 🐍 Gói "Chuyên gia Python" (Python Pro)
_Dành cho những người làm backend và các nhà khoa học dữ liệu._
- `python-patterns`: Viết code Python chuẩn mực (idiomatic).
- `poetry-manager`: Quản lý phụ thuộc (dependencies) hiệu quả.
- `pytest-mastery`: Các framework kiểm thử.
- `fastapi-expert`: Xây dựng API hiệu suất cao.
- `django-guide`: Framework đầy đủ tính năng "battery-included".
## 🦄 Gói "Người sáng lập Startup" (Startup Founder)
_Để xây dựng sản phẩm, không chỉ là viết code._
- `product-requirements-doc`: Định nghĩa những gì cần xây dựng.
- `competitor-analysis`: Biết rõ đối thủ của bạn là ai.
- `pitch-deck-creator`: Gọi vốn (hoặc chỉ để giải thích ý tưởng của bạn).
- `landing-page-copy`: Viết nội dung bán hàng hiệu quả.
- `stripe-integration`: Phương thức thanh toán.
## 🌧️ Gói "DevOps & Cloud"
_Dành cho hạ tầng và mở rộng hệ thống._
- `docker-expert`: Làm chủ container và build đa giai đoạn.
- `aws-serverless`: Sử dụng serverless trên AWS (Lambda, DynamoDB).
- `environment-setup-guide`: Chuẩn hóa cho các đội ngũ.
- `deployment-procedures`: Chiến lược triển khai an toàn.
- `bash-linux`: Làm chủ dòng lệnh Terminal.
## 📊 Gói "Dữ liệu & Phân tích" (Data & Analytics)
_Để hiểu rõ các con số._
- `analytics-tracking`: Thiết lập GA4/PostHog chính xác.
- `d3-viz`: Các hình ảnh hóa dữ liệu tùy chỉnh đẹp mắt.
- `sql-mastery`: Viết truy vấn tốt hơn (Skill cộng đồng).
- `ab-test-setup`: Học hỏi từ thực nghiệm đã xác thực.
## 🎨 Gói "Giám đốc Sáng tạo" (Creative Director)
_Dành cho hình ảnh, nội dung và thương hiệu._
- `canvas-design`: Tạo poster và sơ đồ.
- `frontend-design`: Thẩm mỹ UI.
- `content-creator`: Các bài blog tối ưu hóa SEO.
- `copy-editing`: Trau chuốt nội dung văn bản.
- `algorithmic-art`: Các tác phẩm nghệ thuật tạo bằng code.
## 🐞 Gói "QA & Kiểm thử" (QA & Testing)
_Để phát hiện lỗi trước khi người dùng thấy._
- `test-driven-development`: Red, Green, Refactor.
- `systematic-debugging`: "Sherlock Holmes" trong thế giới code.
- `browser-automation`: Kiểm thử đầu cuối (E2E) với Playwright.
- `ab-test-setup`: Các thử nghiệm đã được xác thực.
- `code-review-checklist`: Phát hiện lỗi trong các Pull Request.
## 🖌️ Gói "Thiết kế Web" (Web Designer)
_Để tạo ra những trải nghiệm hoàn hảo đến từng pixel._
- `ui-ux-pro-max`: Hệ thống thiết kế/tokens cao cấp.
- `frontend-design`: Nền tảng của thẩm mỹ.
- `3d-web-experience`: Ma thuật của Three.js & R3F.
- `canvas-design`: Hình ảnh tĩnh/poster.
- `responsive-layout`: Các nguyên tắc ưu tiên di động (Mobile-first).
---
_Để sử dụng một gói kỹ năng, chỉ cần copy tên các skill vào thư mục `.agent/skills` của bạn hoặc yêu cầu trợ lý AI sử dụng chúng._

236
docs/vietnamese/CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,236 @@
# 🤝 Hướng dẫn Đóng góp - Phiên bản V3 Enterprise
**Cảm ơn bạn đã muốn làm cho repository này trở nên tốt hơn!** Hướng dẫn này sẽ chỉ cho bạn chính xác cách thức đóng góp, ngay cả khi bạn là người mới đối với mã nguồn mở.
Với phiên bản V3, chúng tôi đã nâng cao các tiêu chuẩn về chất lượng. Vui lòng đọc kỹ **Tiêu chuẩn Chất lượng mới** bên dưới.
---
## 🧐 "Quy chuẩn Chất lượng" (Quality Bar - Tiêu chuẩn V3)
**Quan trọng đối với các skill mới:** Mỗi skill được gửi đi phải vượt qua **5 bước Kiểm tra Chất lượng** (xem `docs/vietnamese/QUALITY_BAR.md` để biết chi tiết):
1. **Siêu dữ liệu (Metadata)**: Phần Frontmatter chính xác (`name`, `description`).
2. **An toàn (Safety)**: Không chứa các lệnh gây hại mà không có nhãn rủi ro ("Risk").
3. **Rõ ràng (Clarity)**: Có phần "Khi nào nên dùng" (When to use) rõ ràng.
4. **Ví dụ (Examples)**: Ít nhất một ví dụ sử dụng có thể sao chép và dùng được ngay.
5. **Hành động (Actions)**: Phải định nghĩa các bước hành động cụ thể cho AI, không chỉ là các "ý nghĩ".
---
## Các Cách để Đóng góp
Bạn không cần phải là một chuyên gia! Dưới đây là những cách mà bất kỳ ai cũng có thể giúp đỡ:
### 1. Cải thiện Tài liệu (Dễ nhất!)
- Sửa lỗi chính tả hoặc ngữ pháp.
- Làm cho các giải thích trở nên rõ ràng hơn.
- Thêm ví dụ vào các kỹ năng hiện có.
- Dịch tài liệu sang các ngôn ngữ khác.
### 2. Báo cáo Vấn đề (Issues)
- Thấy điều gì đó khó hiểu? Hãy cho chúng tôi biết!
- Kỹ năng không hoạt động? Hãy báo cho chúng tôi!
- Bạn có đề xuất? Chúng tôi luôn sẵn sàng lắng nghe!
### 3. Tạo Kỹ năng (Skill) mới
- Chia sẻ chuyên môn của bạn dưới dạng một kỹ năng.
- Lấp đầy các khoảng trống trong bộ sưu tập hiện tại.
- Cải thiện các kỹ năng sẵn có.
### 4. Kiểm thử và Xác thực
- Thử nghiệm các kỹ năng và báo cáo những gì hoạt động hoặc không hoạt động.
- Kiểm tra trên các công cụ AI khác nhau.
- Đề xuất các cải tiến.
---
## Cách Tạo một Kỹ năng mới
### Hướng dẫn Từng bước
#### Bước 1: Chọn Chủ đề cho Kỹ năng của bạn
Hãy tự hỏi: "Tôi ước trợ lý AI của mình hiểu rõ hơn về điều gì?".
Ví dụ: "Tôi giỏi về Docker, tôi sẽ tạo một kỹ năng về Docker".
#### Bước 2: Tạo Cấu trúc Thư mục
Các kỹ năng nằm trong thư mục `skills/`. Sử dụng định dạng `kebab-case` cho tên thư mục.
```bash
# Di chuyển đến thư mục skills
cd skills/
# Tạo thư mục cho skill của bạn
mkdir my-awesome-skill
cd my-awesome-skill
# Tạo file SKILL.md
touch SKILL.md
```
#### Bước 3: Viết Nội dung cho SKILL.md
Mỗi kỹ năng đều cần cấu trúc cơ bản này. **Hãy sao chép mẫu dưới đây:**
```markdown
---
name: my-awesome-skill
description: "Mô tả ngắn gọn về chức năng của skill này"
---
# Tiêu đề Skill
## Tổng quan
Giải thích skill này làm gì và khi nào nên sử dụng nó.
## Khi nào nên sử dụng Skill này
- Sử dụng khi [tình huống 1]
- Sử dụng khi [tình huống 2]
## Cách hoạt động
Hướng dẫn chi tiết từng bước cho AI...
## Ví dụ
### Ví dụ 1
\`\`\`
code ví dụ ở đây
\`\`\`
## Thực hành tốt nhất
- ✅ Nên làm điều này
- ❌ Không nên làm điều này
```
#### Bước 4: Xác thực (BƯỚC V3 QUAN TRỌNG)
Chạy script xác thực (validation) tại máy của bạn. **Chúng tôi sẽ không chấp nhận các Pull Request (PR) thất bại ở bước kiểm tra này.**
```bash
# Chế độ nhẹ (chỉ cảnh báo)
python3 scripts/validate_skills.py
# Chế độ nghiêm ngặt (chế độ mà hệ thống CI sẽ chạy)
python3 scripts/validate_skills.py --strict
```
Bước này sẽ kiểm tra:
- ✅ File `SKILL.md` có tồn tại hay không.
- ✅ Phần Frontmatter có chính xác không.
- ✅ Tên (Name) có khớp với tên thư mục không.
- ✅ Có vượt qua các kiểm tra của Quality Bar không.
#### Bước 5: Gửi Kỹ năng của bạn
```bash
git add skills/my-awesome-skill/
git commit -m "feat: add my-awesome-skill"
git push origin my-branch
```
---
## Bản mẫu (Template) Kỹ năng (Copy & Paste)
Tiết kiệm thời gian! Hãy sao chép bản mẫu này:
```markdown
---
name: your-skill-name
description: "Mô tả trong một câu về chức năng của skill và khi nào cần dùng"
---
# Tên Kỹ năng của bạn
## Tổng quan
[2-3 câu giải thích skill này làm gì]
## Khi nào nên sử dụng Skill này
- Sử dụng khi bạn cần [tình huống 1]
- Sử dụng khi bạn muốn [tình huống 2]
## Hướng dẫn Từng bước
### 1. [Tên Bước đầu tiên]
[Hướng dẫn chi tiết]
## Ví dụ
### Ví dụ 1: [Tên Trường hợp sử dụng]
\`\`\`language
// Code ví dụ ở đây
\`\`\`
## Thực hành tốt nhất
- ✅ **Nên:** [Thực hành tốt]
- ❌ **Không nên:** [Điều cần tránh]
## Xử lý Sự cố
**Vấn đề:** [Lỗi thường gặp]
**Giải pháp:** [Cách khắc phục]
```
---
## Hướng dẫn về Thông điệp Commit (Commit Message)
Sử dụng các tiền tố sau:
- `feat:` - Kỹ năng mới hoặc tính năng lớn.
- `docs:` - Cải thiện tài liệu hướng dẫn.
- `fix:` - Sửa lỗi.
- `refactor:` - Cải thiện code mà không thay đổi chức năng.
- `test:` - Thêm hoặc cập nhật các bài kiểm tra.
- `chore:` - Các tác vụ bảo trì.
**Ví dụ:**
```
feat: add kubernetes-deployment skill
docs: improve getting started guide
fix: correct typo in stripe-integration skill
```
---
## Tài liệu Học tập
### Bạn mới sử dụng Git/GitHub?
- [Hướng dẫn Hello World của GitHub](https://guides.github.com/activities/hello-world/)
- [Cơ bản về Git](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics)
### Bạn mới sử dụng Markdown?
- [Hướng dẫn Markdown](https://www.markdownguide.org/basic-syntax/)
---
## Quy tắc Ứng xử (Code of Conduct)
- Luôn tôn trọng và hòa nhập.
- Chào đón những người mới.
- Tập trung vào các phản hồi mang tính xây dựng.
- **Không chứa nội dung gây hại**: Xem `docs/vietnamese/SECURITY_GUARDRAILS.md`.
---
**Cảm ơn bạn đã làm cho dự án này trở nên tốt đẹp hơn cho mọi người!**
Mọi sự đóng góp, dù nhỏ đến đâu, đều tạo nên sự khác biệt. Dù bạn sửa một lỗi chính tả, cải thiện một câu văn, hay tạo ra một kỹ năng hoàn toàn mới - bạn đang giúp đỡ hàng ngàn lập trình viên khác!

56
docs/vietnamese/EXAMPLES.md Normal file
View File

@@ -0,0 +1,56 @@
# 🧪 Ví dụ Thực tế ("Sổ tay Nấu ăn Antigravity")
Các kỹ năng (skills) vốn dĩ đã mạnh mẽ khi đứng riêng lẻ, nhưng chúng sẽ trở nên không thể ngăn cản khi được kết hợp lại với nhau.
Dưới đây là ba tình huống phổ biến và cách giải quyết chúng bằng cách sử dụng repository này.
## 🥘 Công thức 1: "Kiểm tra Code cũ (Legacy Code Audit)"
_Tình huống: Bạn vừa tiếp nhận một repository Node.js 5 năm tuổi đang rất hỗn loạn. Bạn cần sửa nó một cách an toàn._
**Các Skill sử dụng:**
1. `concise-planning` (Để lập bản đồ cho sự hỗn loạn)
2. `lint-and-validate` (Để tìm ra lỗi)
3. `security-audit` (Để tìm ra lỗ hổng bảo mật)
**Quy trình làm việc (Workflow):**
1. **Lập kế hoạch**: "Agent, hãy dùng `concise-planning` để tạo một danh sách kiểm tra (checklist) cho việc tái cấu trúc (refactoring) file `src/legacy-api.js`."
2. **Kiểm tra**: "Chạy `security-audit` trên file `package.json` để tìm các thư viện phụ thuộc có lỗ hổng bảo mật."
3. **Sửa lỗi**: "Sử dụng các quy tắc của `lint-and-validate` để tự động sửa các lỗi định dạng trong thư mục `src/`."
---
## 🥘 Công thức 2: "Ứng dụng Web hiện đại"
_Tình huống: Bạn cần xây dựng một trang Landing Page hiệu suất cao trong vòng 2 giờ._
**Các Skill sử dụng:**
1. `frontend-design` (Để đảm bảo tính thẩm mỹ)
2. `react-patterns` (Để xây dựng cấu trúc)
3. `tailwind-mastery` (Để tăng tốc độ triển khai)
**Quy trình làm việc (Workflow):**
1. **Thiết kế**: "Hãy sử dụng `frontend-design` để tạo bảng màu và kiểu chữ cho một 'Quán cà phê phong cách Cyberpunk'."
2. **Khởi tạo**: "Khởi tạo một dự án Vite. Sau đó áp dụng `react-patterns` để tạo component 'Hero'."
3. **Định dạng kiểu dáng**: "Sử dụng `tailwind-mastery` để làm cho các nút bấm có hiệu ứng glassmorphic (hiệu ứng kính mờ) và phản hồi tốt trên nhiều thiết bị (responsive)."
---
## 🥘 Công thức 3: "Kiến trúc sư Agent"
_Tình huống: Bạn muốn xây dựng một trợ lý AI (agent) tùy chỉnh có khả năng tự xác minh mã code của chính nó._
**Các Skill sử dụng:**
1. `mcp-builder` (Để xây dựng công cụ)
2. `agent-evaluation` (Để kiểm tra độ tin cậy)
3. `prompt-engineering` (Để trau chuốt các hướng dẫn)
**Quy trình làm việc (Workflow):**
1. **Xây dựng**: "Sử dụng `mcp-builder` để tạo một công cụ `verify-file`."
2. **Hướng dẫn**: "Áp dụng các mẫu `prompt-engineering` vào System Prompt để agent luôn kiểm tra lại đường dẫn file."
3. **Kiểm tra**: "Chạy `agent-evaluation` để đo lường tần suất agent thất bại trong việc tìm file."

178
docs/vietnamese/FAQ.md Normal file
View File

@@ -0,0 +1,178 @@
# ❓ Câu hỏi thường gặp (FAQ)
**Bạn có thắc mắc?** Bạn không hề cô đơn! Dưới đây là câu trả lời cho những câu hỏi thường gặp nhất về Antigravity Awesome Skills.
---
## 🎯 Câu hỏi Chung
### "Skills" (kỹ năng) chính xác là gì?
Skills là các tệp hướng dẫn chuyên biệt dạy cho các trợ lý AI cách xử lý những tác vụ cụ thể. Hãy coi chúng như những mô-đun kiến thức chuyên gia mà AI của bạn có thể tải khi cần.
**Một so sánh đơn giản:** Giống như việc bạn tham khảo ý kiến của các chuyên gia khác nhau (luật sư, bác sĩ, thợ máy), những kỹ năng này giúp AI của bạn trở thành chuyên gia trong các lĩnh vực khác nhau khi bạn cần.
### Tôi có cần phải cài đặt tất cả hơn 552 skills không?
**Không!** Khi bạn clone (tải bản sao) repository này, tất cả các kỹ năng đều có sẵn, nhưng AI của bạn chỉ tải chúng khi bạn yêu cầu rõ ràng bằng lệnh `@ten-skill`.
Nó giống như việc sở hữu một thư viện - tất cả sách đều ở đó, nhưng bạn chỉ đọc những cuốn bạn cần thôi.
**Mẹo:** Sử dụng [Bản mẫu Khởi đầu (Starter Packs)](BUNDLES.md) để chỉ cài đặt những gì phù hợp với vai trò của bạn.
### Những công cụ AI nào hoạt động với các kỹ năng này?
- ✅ **Claude Code** (Dòng lệnh CLI của Anthropic)
- ✅ **Gemini CLI** (Google)
- ✅ **Codex CLI** (OpenAI)
- ✅ **Cursor** (IDE tích hợp AI)
- ✅ **Antigravity IDE**
- ✅ **OpenCode**
- ⚠️ **GitHub Copilot** (Hỗ trợ một phần qua việc copy-paste)
### Những kỹ năng này có được sử dụng miễn phí không?
**Có!** Repository này được cấp phép theo giấy phép MIT License.
- ✅ Miễn phí cho sử dụng cá nhân.
- ✅ Miễn phí cho sử dụng thương mại.
- ✅ Bạn có thể sửa đổi chúng.
### Các kỹ năng có hoạt động ngoại tuyến (offline) không?
Bản thân các file skill được lưu trữ cục bộ trên máy tính của bạn, nhưng trợ lý AI của bạn vẫn cần kết nối internet để hoạt động.
---
## 🔒 Bảo mật & Tin cậy (Cập nhật V3)
### Các Nhãn rủi ro (Risk Labels) có ý nghĩa gì?
Chúng tôi phân loại các kỹ năng để bạn biết mình đang chạy cái gì:
- ⚪ **Safe (Trắng/Xanh)**: Các kỹ năng chỉ đọc, lập kế hoạch hoặc vô hại.
- 🔴 **Risk (Đỏ)**: Các kỹ năng sửa đổi file (xóa), sử dụng công cụ quét mạng, hoặc thực hiện các hành động có tính phá hủy. **Hãy sử dụng thận trọng.**
- 🟣 **Official (Tím)**: Được duy trì bởi các nhà cung cấp tin cậy (Anthropic, DeepMind, v.v.).
### Những kỹ năng này có thể hack máy tính của tôi không?
**Không.** Kỹ năng là các file văn bản. Tuy nhiên, chúng *hướng dẫn* AI chạy các dòng lệnh. Nếu một skill nói "xóa toàn bộ file", một AI tuân thủ có thể sẽ thử làm việc đó.
_Luôn kiểm tra nhãn rủi ro và xem xét mã nguồn trước khi dùng._
---
## 📦 Cài đặt & Thiết lập
### Tôi nên cài đặt các kỹ năng này ở đâu?
Đường dẫn phổ biến nhất hoạt động với mạng lưới các công cụ AI là `.agent/skills/`:
```bash
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
```
**Các đường dẫn cụ thể cho từng công cụ:**
- Claude Code: `.claude/skills/`
- Gemini CLI: `.gemini/skills/`
- Cursor: `.cursor/skills/` hoặc gốc của dự án.
### Repo này có hoạt động trên Windows không?
**Có**, nhưng một số kỹ năng "Official" (chính thức) sử dụng **symlinks** (liên kết tượng trưng) mà Windows xử lý không tốt theo mặc định.
Hãy chạy git clone với lệnh sau:
```bash
git clone -c core.symlinks=true https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
```
Hoặc bật "Chế độ Nhà phát triển" (Developer Mode) trong phần Cài đặt của Windows.
### Làm thế nào để cập nhật các kỹ năng?
Chuyển hướng đến thư mục chứa kỹ năng của bạn và kéo (pull) những thay đổi mới nhất:
```bash
cd .agent/skills
git pull origin main
```
---
## 🛠️ Cách sử dụng Skills
### Làm thế nào để gọi một kỹ năng?
Sử dụng biểu tượng `@` theo sau là tên skill:
```bash
@brainstorming giúp tôi thiết kế một ứng dụng todo
```
### Tôi có thể dùng nhiều kỹ năng cùng một lúc không?
**Có!** Bạn có thể gọi nhiều kỹ năng:
```bash
@brainstorming giúp tôi thiết kế phần này, sau đó dùng @writing-plans để tạo danh sách nhiệm vụ.
```
### Làm thế nào để tôi biết nên dùng kỹ năng nào?
1. **Duyệt qua danh mục**: Xem [Danh mục Skill (Skill Catalog)](../CATALOG.md).
2. **Tìm kiếm**: `ls skills/ | grep "từ-khóa"`
3. **Hỏi AI của bạn**: "Bạn có kỹ năng nào để kiểm thử (testing) không?"
---
## 🏗️ Xử lý sự cố
### Trợ lý AI của tôi không nhận diện được kỹ năng
**Các nguyên nhân có thể xảy ra:**
1. **Sai đường dẫn cài đặt**: Kiểm tra tài liệu hướng dẫn của công cụ bạn dùng. Hãy thử `.agent/skills/`.
2. **Cần khởi động lại**: Khởi động lại AI/IDE sau khi cài đặt.
3. **Lỗi đánh máy**: Bạn có gõ lầm `@brain-storming` thay vì `@brainstorming` không?
### Một kỹ năng đưa ra lời khuyên sai hoặc lỗi thời
Hãy [Mở một issue](https://github.com/sickn33/antigravity-awesome-skills/issues)!
Vui lòng gửi kèm:
- Skill nào?
- Điều gì đã xảy ra?
- Đáng lẽ điều gì nên xảy ra?
---
## 🤝 Đóng góp
### Tôi là người mới đối với mã nguồn mở. Tôi có thể đóng góp không?
**Chắc chắn là có!** Chúng tôi chào đón những người mới bắt đầu.
- Sửa lỗi đánh máy.
- Thêm ví dụ.
- Cải thiện tài liệu hướng dẫn.
Hãy xem [CONTRIBUTING.md](../CONTRIBUTING.md) để biết hướng dẫn chi tiết.
### Pull Request (PR) của tôi thất bại khi kiểm tra "Quality Bar". Tại sao?
Phiên bản V3 áp dụng kiểm soát chất lượng tự động. Skill của bạn có thể đang thiếu:
1. Một `description` (mô tả) hợp lệ.
2. Các ví dụ sử dụng.
Hãy chạy `python3 scripts/validate_skills.py` cục bộ để kiểm tra trước khi đẩy code lên.
### Tôi có thể cập nhật các kỹ năng "Official" không?
**Không.** Các kỹ năng chính thức (trong thư mục `skills/official/`) được đồng bộ từ các nhà cung cấp. Thay vào đó, hãy mở một issue để báo lỗi.
---
## 💡 Mẹo Chuyên nghiệp
- Bắt đầu với `@brainstorming` trước khi xây dựng bất kỳ thứ gì mới.
- Sử dụng `@systematic-debugging` khi gặp lỗi khó nhằn.
- Thử `@test-driven-development` để code có chất lượng tốt hơn.
- Khám phá `@skill-creator` để tự tạo kỹ năng của riêng bạn.
**Vẫn còn thắc mắc?** [Mở một cuộc thảo luận (Discussion)](https://github.com/sickn33/antigravity-awesome-skills/discussions) và chúng tôi sẽ giúp bạn! 🙌

108
docs/vietnamese/GETTING_STARTED.md Normal file
View File

@@ -0,0 +1,108 @@
# Hướng dẫn Bắt đầu với Antigravity Awesome Skills (V3)
**Bạn mới đến đây? Hướng dẫn này sẽ giúp bạn tăng cường sức mạnh cho trợ lý trợ lý AI của mình chỉ trong 5 phút.**
---
## 🤔 "Skills" (Kỹ năng) là gì?
Các trợ lý AI (như **Claude Code**, **Gemini**, **Cursor**) rất thông minh, nhưng chúng thiếu kiến thức cụ thể về các công cụ và quy trình làm việc của bạn.
**Skills** là các hướng dẫn sử dụng chuyên biệt (dưới dạng file markdown) dạy cho AI của bạn cách thực hiện các tác vụ cụ thể một cách hoàn hảo trong mọi lần thực hiện.
**Một phép so sánh:** AI của bạn là một thực tập sinh xuất sắc. **Skills** là các SOP (Quy trình vận hành tiêu chuẩn) biến họ thành một Kỹ sư cao cấp.
---
## ⚡️ Khởi động nhanh: Các "Gói khởi đầu" (Starter Packs)
Đừng lo lắng về con số hơn 552 kỹ năng. Bạn không cần dùng tất cả chúng cùng một lúc.
Chúng tôi đã tuyển chọn các **Gói khởi đầu** để bạn có thể bắt đầu sử dụng ngay lập tức.
### 1. Cài đặt Repository
Sao chép các kỹ năng vào thư mục agent của bạn:
```bash
# Cài đặt phổ thông (hoạt động với hầu hết các agent)
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
```
### 2. Chọn vai trò của bạn
Tìm gói kỹ năng phù hợp với vị trí của bạn (xem [BUNDLES.md](BUNDLES.md)):
| Vai trò | Tên Gói kỹ năng | Bên trong có những gì? |
| :-------------------- | :-------------- | :------------------------------------------------ |
| **Web Developer** | `Web Wizard` | React Patterns, Tailwind mastery, Frontend Design |
| **Security Engineer** | `Hacker Pack` | OWASP, Metasploit, Pentest Methodology |
| **Manager / PM** | `Product Pack` | Brainstorming, Planning, SEO, Strategy |
| **Cơ bản cho tất cả** | `Essentials` | Clean Code, Planning, Validation (Những thứ cơ bản nhất) |
---
## 🚀 Cách sử dụng một Skill
Sau khi cài đặt, bạn chỉ cần trò chuyện với AI một cách tự nhiên.
### Ví dụ 1: Lập kế hoạch cho một Tính năng (**Essentials**)
> "Sử dụng **@brainstorming** để giúp tôi thiết kế một luồng đăng nhập mới."
**Điều gì sẽ xảy ra:** AI sẽ tải kỹ năng brainstorming, đặt cho bạn các câu hỏi có cấu trúc và tạo ra một bản đặc tả chuyên nghiệp.
### Ví dụ 2: Kiểm tra Code của bạn (**Web Wizard**)
> "Chạy **@lint-and-validate** trên file này và sửa các lỗi."
**Điều gì sẽ xảy ra:** AI sẽ tuân theo các quy tắc linting nghiêm ngặt được định nghĩa trong skill để làm sạch code của bạn.
### Ví dụ 3: Kiểm tra Bảo mật (**Hacker Pack**)
> "Sử dụng **@api-security-best-practices** để xem xét các endpoint API của tôi."
**Điều gì sẽ xảy ra:** AI sẽ kiểm tra code của bạn dựa trên các tiêu chuẩn OWASP.
---
## 🔌 Các công cụ được hỗ trợ
| Công cụ | Trạng thái | Đường dẫn |
| :--------------- | :-------------- | :---------------- |
| **Claude Code** | ✅ Hỗ trợ đầy đủ | `.claude/skills/` |
| **Gemini CLI** | ✅ Hỗ trợ đầy đủ | `.gemini/skills/` |
| **Antigravity** | ✅ Hỗ trợ gốc | `.agent/skills/` |
| **Cursor** | ✅ Hỗ trợ gốc | `.cursor/skills/` |
| **Copilot** | ⚠️ Chỉ văn bản | Copy-paste thủ công |
---
## 🛡️ Sự tin cậy & An toàn (Mới trong bản V3)
Chúng tôi phân loại các kỹ năng để bạn biết mình đang chạy những gì:
- 🟣 **Official (Chính thức)**: Được duy trì bởi Anthropic/Google/Nhà cung cấp (Độ tin cậy cao).
- 🔵 **Safe (An toàn)**: Các kỹ năng cộng đồng không gây hại (Chỉ đọc/Lập kế hoạch).
- 🔴 **Risk (Rủi ro)**: Các kỹ năng sửa đổi hệ thống hoặc thực hiện kiểm thử bảo mật (Sử dụng khi được cấp phép).
_Kiểm tra [Danh mục Skill (Skill Catalog)](../CATALOG.md) để xem danh sách đầy đủ._
---
## ❓ FAQ
**H: Tôi có cần cài đặt tất cả 552 kỹ năng không?**
Đ: Bạn tải toàn bộ repo về, nhưng AI của bạn chỉ _đọc_ những kỹ năng bạn yêu cầu (hoặc những kỹ năng có liên quan). Nó rất nhẹ!
**H: Tôi có thể tự tạo kỹ năng cho riêng mình không?**
Đ: Có! Sử dụng kỹ năng **@skill-creator** để tự xây dựng.
**H: Nó có miễn phí không?**
Đ: Có, Giấy phép MIT. Mã nguồn mở mãi mãi.
---
## ⏭️ Các bước tiếp theo
1. [Duyệt qua các Gói kỹ năng (Bundles)](BUNDLES.md)
2. [Xem các Ví dụ thực tế (Examples)](EXAMPLES.md)
3. [Đóng góp một Skill mới](../CONTRIBUTING.md)

64
docs/vietnamese/QUALITY_BAR.md Normal file
View File

@@ -0,0 +1,64 @@
# 🏆 Tiêu chuẩn Chất lượng & Xác thực
Để biến **Antigravity Awesome Skills** từ một tập hợp các script thành một nền tảng đáng tin cậy, mỗi skill (kỹ năng) phải đáp ứng một tiêu chuẩn cụ thể về chất lượng và an toàn.
## Huy hiệu "Đã xác thực" (Validated) ✅
Một skill chỉ nhận được huy hiệu "Đã xác thực" nếu nó vượt qua **5 bước kiểm tra tự động** sau:
### 1. Tính toàn vẹn của siêu dữ liệu (Metadata Integrity)
Phần frontmatter trong `SKILL.md` phải là mã YAML hợp lệ và chứa:
- `name`: Định dạng Kebab-case, khớp với tên thư mục.
- `description`: Dưới 200 ký tự, nêu rõ giá trị mang lại.
- `risk`: Thuộc một trong các loại `[none, safe, critical, offensive]`.
- `source`: URL dẫn đến nguồn gốc (hoặc "self" nếu là nội dung gốc).
### 2. Điều kiện kích hoạt rõ ràng ("Khi nào nên dùng")
Skill BẮT BUỘC phải có một phần nêu rõ thời điểm nên kích hoạt nó.
- **Tốt**: "Sử dụng khi người dùng yêu cầu debug (gỡ lỗi) một component React."
- **Tệ**: "Skill này giúp bạn xử lý code."
### 3. Phân loại An toàn & Rủi ro
Mỗi skill phải khai báo mức độ rủi ro của nó:
- 🟢 **none**: Chỉ là văn bản/tư duy thuần túy (ví dụ: Brainstorming).
- 🔵 **safe**: Đọc file, chạy các lệnh an toàn (ví dụ: Linter).
- 🟠 **critical**: Sửa đổi trạng thái, xóa file, push lên môi trường production (ví dụ: Git Push).
- 🔴 **offensive**: Các công cụ Pentesting/Red Team. **BẮT BUỘC** phải có cảnh báo "Chỉ dành cho mục đích sử dụng đã được cấp phép".
### 4. Ví dụ thực tế (Copy-Pasteable)
Ít nhất một khối code hoặc ví dụ tương tác mà người dùng (hoặc agent) có thể sử dụng ngay lập tức.
### 5. Giới hạn rõ ràng (Explicit Limitations)
Danh sách các trường hợp biên hoặc những việc mà skill _không thể_ thực hiện.
- _Ví dụ_: "Không hoạt động trên Windows nếu không có WSL."
---
## Các cấp độ Hỗ trợ
Chúng tôi cũng phân loại skill dựa trên người duy trì chúng:
| Cấp độ | Huy hiệu | Ý nghĩa |
| :------------ | :------- | :--------------------------------------------------- |
| **Official** | 🟣 | Do đội ngũ cốt lõi duy trì. Độ tin cậy cao. |
| **Community** | ⚪ | Do cộng đồng đóng góp. Hỗ trợ theo khả năng tốt nhất. |
| **Verified** | ✨ | Skill cộng đồng đã vượt qua vòng kiểm duyệt thủ công chuyên sâu. |
---
## Cách Xác thực Skill của bạn
Chạy script xác thực trước khi gửi Pull Request (PR):
```bash
python3 scripts/validate_skills.py --strict
```

254
docs/vietnamese/README.md Normal file
View File

@@ -0,0 +1,254 @@
# 🌌 Antigravity Awesome Skills: 552+ Kỹ năng (Skills) cho Claude Code, Gemini CLI, Cursor, Copilot và nhiều hơn nữa
> **Bộ sưu tập tối ưu gồm hơn 552 Kỹ năng Phổ quát cho các Trợ lý Lập trình AI — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode**
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-Anthropic-purple)](https://claude.ai)
[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Google-blue)](https://github.com/google-gemini/gemini-cli)
[![Codex CLI](https://img.shields.io/badge/Codex%20CLI-OpenAI-green)](https://github.com/openai/codex)
[![Cursor](https://img.shields.io/badge/Cursor-AI%20IDE-orange)](https://cursor.sh)
[![Copilot](https://img.shields.io/badge/GitHub%20Copilot-VSCode-lightblue)](https://github.com/features/copilot)
[![OpenCode](https://img.shields.io/badge/OpenCode-CLI-gray)](https://github.com/opencode-ai/opencode)
[![Antigravity](https://img.shields.io/badge/Antigravity-DeepMind-red)](https://github.com/sickn33/antigravity-awesome-skills)
**Antigravity Awesome Skills** là một thư viện được tuyển chọn và kiểm chứng kỹ lưỡng với **552 kỹ năng hiệu suất cao** được thiết kế để hoạt động mượt mà trên tất cả các trợ lý lập trình AI lớn:
- 🟣 **Claude Code** (Anthropic CLI)
- 🔵 **Gemini CLI** (Google DeepMind)
- 🟢 **Codex CLI** (OpenAI)
- 🔴 **Antigravity IDE** (Google DeepMind)
- 🩵 **GitHub Copilot** (VSCode Extension)
- 🟠 **Cursor** (AI-native IDE)
- ⚪ **OpenCode** (Mã nguồn mở CLI)
Repository này cung cấp các kỹ năng thiết yếu để biến trợ lý AI của bạn thành một **digital agency toàn diện**, bao gồm các khả năng chính thức từ **Anthropic**, **OpenAI**, **Google**, **Supabase**, và **Vercel Labs**.
## Mục lục
- [🚀 Bạn mới đến đây? Hãy bắt đầu tại đây!](#bạn-mới-đến-đây-hãy-bắt đầu-tại-đây)
- [🔌 Khả năng tương thích & Cách gọi lệnh](#khả-năng-tương-thích--cách-gọi-lệnh)
- [📦 Tính năng & Danh mục](#tính-năng--danh-mục)
- [🎁 Bộ sưu tập được tuyển chọn (Bundles)](#bộ-sưu-tập-được-tuyển-chọn)
- [📚 Duyệt hơn 552 Kỹ năng](#duyệt-hơn-552-kỹ-năng)
- [🛠️ Cài đặt](#cài-đặt)
- [🤝 Cách thức Đóng góp](#cách-thức-đóng-góp)
- [👥 Người đóng góp & Ghi công](#người-đóng-góp--ghi-công)
- [⚖️ Giấy phép](#giấy-phép)
- [👥 Những người đóng góp cho Repo](#những-người-đóng-góp-cho-repo)
- [🌟 Lịch sử Star](#lịch-sử-star)
---
## Bạn mới đến đây? Hãy bắt đầu tại đây!
**Chào mừng bạn đến với Phiên bản V4.0.0 Enterprise.** Đây không chỉ là một danh sách các kịch bản; nó là một hệ điều hành hoàn chỉnh cho Trợ lý AI của bạn.
### 1. 🐣 Bối cảnh: Đây là cái gì?
**Antigravity Awesome Skills** (Phiên bản 4.0.0) là một bản nâng cấp khổng lồ cho khả năng của AI của bạn.
Các trợ lý AI (như Claude Code, Cursor, hoặc Gemini) rất thông minh, nhưng chúng thiếu các **công cụ cụ thể**. Chúng không biết "Giao thức Triển khai" của công ty bạn hoặc cú pháp cụ thể cho "AWS CloudFormation".
**Skills** là các tệp markdown nhỏ dạy cho chúng cách thực hiện những tác vụ cụ thể này một cách hoàn hảo trong mọi lần thực hiện.
### 2. ⚡️ Khởi động nhanh (Theo cách dùng "Gói kỹ năng")
Đừng cài đặt 552+ kỹ năng một cách thủ công. Hãy sử dụng các **Gói khởi đầu (Starter Packs)** của chúng tôi:
1. **Sao chép repo**:
```bash
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
```
2. **Chọn vai trò của bạn** (Xem [docs/vietnamese/BUNDLES.md](docs/vietnamese/BUNDLES.md)):
- **Lập trình Web?** sử dụng gói `Web Wizard`.
- **Hacker?** sử dụng gói `Security Engineer`.
- **Chỉ tò mò thôi?** bắt đầu với gói `Essentials`.
### 3. 🧠 Cách sử dụng
Sau khi cài đặt, chỉ cần hỏi trợ lý của bạn một cách tự nhiên:
> "Sử dụng kỹ năng **@brainstorming** để giúp tôi lập kế hoạch cho một dự án SaaS."
> "Chạy **@lint-and-validate** trên file này."
👉 **[Đọc Hướng dẫn bắt đầu đầy đủ](docs/vietnamese/GETTING_STARTED.md)**
---
## Khả năng tương thích & Cách gọi lệnh
Các kỹ năng này tuân theo định dạng chuẩn **SKILL.md** phổ quát và hoạt động với bất kỳ trợ lý lập trình AI nào hỗ trợ các kỹ năng agentic.
| Công cụ | Loại | Ví dụ gọi lệnh | Đường dẫn |
| :-------------- | :--- | :-------------------------------- | :---------------- |
| **Claude Code** | CLI | `>> /skill-name giúp tôi...` | `.claude/skills/` |
| **Gemini CLI** | CLI | `(User Prompt) Dùng skill-name...`| `.gemini/skills/` |
| **Antigravity** | IDE | `(Agent Mode) Dùng skill...` | `.agent/skills/` |
| **Cursor** | IDE | `@skill-name (trong Chat)` | `.cursor/skills/` |
| **Copilot** | Ext | `(Dán nội dung thủ công)` | (N/A) |
> [!TIP]
> **Đường dẫn Phổ quát**: Chúng tôi khuyên bạn nên clone về thư mục `.agent/skills/`. Hầu hết các công cụ hiện đại (Antigravity, các CLI gần đây) đều tìm kiếm ở đây theo mặc định.
> [!WARNING]
> **Người dùng Windows**: Repository này sử dụng **symlinks** cho các kỹ năng chính thức.
> Bạn phải bật Chế độ nhà phát triển (Developer Mode) hoặc chạy Git với quyền Admin:
> `git clone -c core.symlinks=true https://github.com/...`
---
Cho dù bạn đang sử dụng **Gemini CLI**, **Claude Code**, **Codex CLI**, **Cursor**, **GitHub Copilot**, **Antigravity**, hay **OpenCode**, những kỹ năng này được thiết kế để có thể sử dụng ngay lập tức và tăng cường sức mạnh cho trợ lý AI của bạn.
Repository này tập hợp những khả năng tốt nhất từ khắp cộng đồng mã nguồn mở, biến trợ lý AI của bạn thành một digital agency toàn diện có khả năng Kỹ thuật, Thiết kế, Bảo mật, Marketing và Vận hành Tự động.
## Tính năng & Danh mục
Repository được tổ chức thành các lĩnh vực chuyên biệt để biến AI của bạn thành một chuyên gia trên toàn bộ vòng đời phát triển phần mềm:
| Danh mục | Trọng tâm | Ví dụ kỹ năng |
| :--- | :--- | :--- |
| Kiến trúc (52) | Thiết kế hệ thống, ADRs, C4 và các mẫu có thể mở rộng | `architecture`, `c4-context`, `senior-architect` |
| Kinh doanh (35) | Tăng trưởng, định giá, CRO, SEO và thâm nhập thị trường | `copywriting`, `pricing-strategy`, `seo-audit` |
| Dữ liệu & AI (81) | Ứng dụng LLM, RAG, agents, khả năng quan sát, phân tích | `rag-engineer`, `prompt-engineer`, `langgraph` |
| Phát triển (72) | Làm chủ ngôn ngữ, mẫu thiết kế framework, chất lượng code | `typescript-expert`, `python-patterns`, `react-patterns` |
| Tổng quát (95) | Lập kế hoạch, tài liệu, vận hành sản phẩm, viết bài, hướng dẫn | `brainstorming`, `doc-coauthoring`, `writing-plans` |
| Hạ tầng (72) | DevOps, cloud, serverless, triển khai, CI/CD | `docker-expert`, `aws-serverless`, `vercel-deployment` |
| Bảo mật (107) | AppSec, pentesting, phân tích lỗ hổng, tuân thủ | `api-security-best-practices`, `sql-injection-testing`, `vulnerability-scanner` |
| Kiểm thử (21) | TDD, thiết kế kiểm thử, sửa lỗi, quy trình QA | `test-driven-development`, `testing-patterns`, `test-fixing` |
| Quy trình (17) | Tự động hóa, điều phối, công việc, agents | `workflow-automation`, `inngest`, `trigger-dev` |
## Bộ sưu tập Tuyển chọn
[Xem các Gói khởi đầu tại docs/vietnamese/BUNDLES.md](docs/vietnamese/BUNDLES.md) để tìm bộ công cụ hoàn hảo cho vai trò của bạn.
## Duyệt hơn 552 Kỹ năng
Chúng tôi đã chuyển danh sách đầy đủ các kỹ năng sang một danh mục riêng biệt để giữ cho file README này gọn gàng.
👉 **[Xem Danh mục Kỹ năng Đầy đủ (CATALOG.md)](CATALOG.md)**
## Cài đặt
Để sử dụng các kỹ năng này với **Claude Code**, **Gemini CLI**, **Codex CLI**, **Cursor**, **Antigravity**, hoặc **OpenCode**, hãy clone repository này vào thư mục kỹ năng của assistant của bạn:
```bash
# Cài đặt phổ thông (hoạt động với hầu hết các công cụ)
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
# Dành riêng cho Claude Code
git clone https://github.com/sickn33/antigravity-awesome-skills.git .claude/skills
# Dành riêng cho Gemini CLI
git clone https://github.com/sickn33/antigravity-awesome-skills.git .gemini/skills
# Dành riêng cho Cursor
git clone https://github.com/sickn33/antigravity-awesome-skills.git .cursor/skills
```
---
## Cách thức Đóng góp
Chúng tôi chào đón mọi sự đóng góp từ cộng đồng! Để thêm một kỹ năng mới:
1. **Fork** repository.
2. **Tạo một thư mục mới** bên trong `skills/` cho kỹ năng của bạn.
3. **Thêm file `SKILL.md`** với phần frontmatter bắt buộc (tên và mô tả).
4. **Chạy kiểm tra xác thực**: `python3 scripts/validate_skills.py`.
5. **Gửi một Pull Request**.
Vui lòng đảm bảo kỹ năng của bạn tuân thủ các thực hành tốt nhất của Antigravity/Claude Code.
---
## Người đóng góp & Ghi công
Chúng tôi đứng trên vai của những người khổng lồ.
👉 **[Xem Sổ cái Ghi công Đầy đủ (docs/vietnamese/SOURCES.md)](docs/vietnamese/SOURCES.md)**
Các nguồn đóng góp và nguồn chính bao gồm:
- **HackTricks**
- **OWASP**
- **Anthropic / OpenAI / Google**
- **Cộng đồng mã nguồn mở**
Bộ sưu tập này sẽ không thể hình thành nếu không có công việc tuyệt vời của cộng đồng Claude Code và các nguồn chính thức:
### Các nguồn Chính thức
- **[anthropics/skills](https://github.com/anthropics/skills)**: Thư mục skill chính thức của Anthropic - Xử lý tài liệu (DOCX, PDF, PPTX, XLSX), Hướng dẫn thương hiệu, Giao tiếp nội bộ.
- **[anthropics/claude-cookbooks](https://github.com/anthropics/claude-cookbooks)**: Các notebook và công thức chính thức để xây dựng với Claude.
- **[remotion-dev/skills](https://github.com/remotion-dev/skills)**: Skills chính thức của Remotion - Tạo video trong React với 28 quy tắc mô-đun.
- **[vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)**: Skills chính thức của Vercel Labs - Thực hành tốt nhất cho React, Hướng dẫn thiết kế Web.
- **[openai/skills](https://github.com/openai/skills)**: Danh mục skill của OpenAI Codex - Các kỹ năng của Agent, Trình tạo Skill, Lập kế hoạch Súc tích.
- **[supabase/agent-skills](https://github.com/supabase/agent-skills)**: Skills chính thức của Supabase - Thực hành tốt nhất cho Postgres.
### Những người đóng góp từ Cộng đồng
- **[rmyndharis/antigravity-skills](https://github.com/rmyndharis/antigravity-skills)**: Cho sự đóng góp khổng lồ của hơn 300+ kỹ năng Enterprise và logic tạo danh mục.
- **[obra/superpowers](https://github.com/obra/superpowers)**: Bản "Superpowers" gốc bởi Jesse Vincent.
- **[guanyang/antigravity-skills](https://github.com/guanyang/antigravity-skills)**: Các bản mở rộng Antigravity cốt lõi.
- **[diet103/claude-code-infrastructure-showcase](https://github.com/diet103/claude-code-infrastructure-showcase)**: Cơ sở hạ tầng và Hướng dẫn cho Backend/Frontend.
- **[ChrisWiles/claude-code-showcase](https://github.com/ChrisWiles/claude-code-showcase)**: Các mẫu React UI và Hệ thống Thiết kế.
- **[travisvn/awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills)**: Loki Mode và tích hợp Playwright.
- **[zebbern/claude-code-guide](https://github.com/zebbern/claude-code-guide)**: Bộ công cụ bảo mật toàn diện & Hướng dẫn (Nguồn cho khoảng 60 kỹ năng mới).
- **[alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills)**: Bộ công cụ Kỹ sư cao cấp và PM.
- **[karanb192/awesome-claude-skills](https://github.com/karanb192/awesome-claude-skills)**: Một danh sách khổng lồ các kỹ năng đã được xác thực cho Claude Code.
- **[zircote/.claude](https://github.com/zircote/.claude)**: Tham chiếu kỹ năng phát triển cho Shopify.
- **[vibeforge1111/vibeship-spawner-skills](https://github.com/vibeforge1111/vibeship-spawner-skills)**: Trợ lý AI, Tích hợp, Công cụ của nhà sáng tạo (57 kỹ năng, Apache 2.0).
- **[coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills)**: Các kỹ năng Marketing cho CRO, copywriting, SEO, quảng cáo trả phí và tăng trưởng (23 kỹ năng, MIT).
- **[vudovn/antigravity-kit](https://github.com/vudovn/antigravity-kit)**: Các mẫu AI Agent với Kỹ năng, Agents và Quy trình làm việc (33 kỹ năng, MIT).
- **[affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code)**: Bộ sưu tập cấu hình Claude Code đầy đủ từ người chiến thắng cuộc thi hackathon của Anthropic - chỉ phần kỹ năng (8 kỹ năng, MIT).
- **[webzler/agentMemory](https://github.com/webzler/agentMemory)**: Nguồn cho kỹ năng agent-memory-mcp.
- **[sstklen/claude-api-cost-optimization](https://github.com/sstklen/claude-api-cost-optimization)**: Tiết kiệm 50-90% chi phí Claude API với các chiến lược tối ưu hóa thông minh (MIT).
### Nguồn cảm hứng
- **[f/awesome-chatgpt-prompts](https://github.com/f/awesome-chatgpt-prompts)**: Cảm hứng cho Thư viện Prompt.
- **[leonardomso/33-js-concepts](https://github.com/leonardomso/33-js-concepts)**: Cảm hứng cho việc Làm chủ JavaScript.
---
## Giấy phép
Giấy phép MIT. Xem file [LICENSE](LICENSE) để biết chi tiết.
## Cộng đồng
- [Cộng đồng (Community Guidelines)](docs/vietnamese/COMMUNITY_GUIDELINES.md)
- [Chính sách Bảo mật (Security Policy)](docs/vietnamese/SECURITY_GUARDRAILS.md)
---
## Những người đóng góp cho Repo
Chúng tôi chính thức cảm ơn những người đóng góp sau đây đã giúp làm cho repository này trở nên tuyệt vời!
- [mvanhorn](https://github.com/mvanhorn)
- [rookie-ricardo](https://github.com/rookie-ricardo)
- [sck_0](https://github.com/sck_0)
- [Munir Abbasi](https://github.com/munirabbasi)
- [Mohammad Faiz](https://github.com/mohdfaiz2k9)
- [Ianj332](https://github.com/Ianj332)
- [sickn33](https://github.com/sickn33)
- [GuppyTheCat](https://github.com/GuppyTheCat)
- [Tiger-Foxx](https://github.com/Tiger-Foxx)
- [arathiesh](https://github.com/arathiesh)
- [1bcMax](https://github.com/1bcMax)
- [Ahmed Rehan](https://github.com/ar27111994)
- [BenedictKing](https://github.com/BenedictKing)
- [Nguyen Huu Loc](https://github.com/LocNguyenSGU)
- [Owen Wu](https://github.com/yubing744)
- [SuperJMN](https://github.com/SuperJMN)
- [Viktor Ferenczi](https://github.com/viktor-ferenczi)
- [krisnasantosa15](https://github.com/krisnasantosa15)
- [raeef1001](https://github.com/raeef1001)
- [taksrules](https://github.com/taksrules)
- [zebbern](https://github.com/zebbern)
- [Đỗ Khắc Gia Khoa](https://github.com/dokhacgiakhoa)
- [vuth-dogo](https://github.com/vuth-dogo)
## Lịch sử Star
[![Star History Chart](https://api.star-history.com/svg?repos=sickn33/antigravity-awesome-skills&type=date&legend=top-left)](https://www.star-history.com/#sickn33/antigravity-awesome-skills&type=date&legend=top-left)

51
docs/vietnamese/SECURITY_GUARDRAILS.md Normal file
View File

@@ -0,0 +1,51 @@
# 🛡️ Chính sách Bảo mật & Rào chắn An toàn (Guardrails)
Antigravity Awesome Skills là một bộ công cụ mạnh mẽ. Và quyền lực lớn luôn đi kèm với trách nhiệm lớn. Tài liệu này xác định **Quy tắc Ứng xử** cho tất cả các khả năng bảo mật và tấn công trong repository này.
## 🔴 Chính sách đối với Skill Tấn công (Vạch kẻ đỏ)
**Skill Tấn công là gì?**
Bất kỳ kỹ năng (skill) nào được thiết kế để xâm nhập, khai thác, làm gián đoạn hoặc mô phỏng tấn công chống lại các hệ thống.
_Ví dụ: Pentesting (Kiểm thử xâm nhập), SQL Injection, Mô phỏng Phishing, Red Teaming._
### 1. Tuyên bố từ chối trách nhiệm "Chỉ dành cho mục đích sử dụng đã được phê duyệt"
Mỗi skill tấn công **BẮT BUỘC** phải bắt đầu bằng tuyên bố từ chối trách nhiệm chính xác như sau trong file `SKILL.md`:
> **⚠️ CHỈ DÀNH CHO MỤC ĐÍCH SỬ DỤNG ĐÃ ĐƯỢC PHÊ DUYỆT**
> Skill này chỉ dành cho mục đích giáo dục hoặc đánh giá bảo mật đã được cấp phép.
> Bạn phải có sự cho phép rõ ràng bằng văn bản từ chủ sở hữu hệ thống trước khi sử dụng công cụ này.
> Việc lạm dụng công cụ này là bất hợp pháp và bị nghiêm cấm hoàn toàn.
### 2. Yêu cầu Xác nhận từ Người dùng
Các skill tấn công **KHÔNG BAO GIỜ** được chạy hoàn toàn tự động một cách tự ý (autonomously).
- **Yêu cầu**: Mô tả hoặc hướng dẫn của skill phải yêu cầu agent (trợ lý AI) *hỏi xác nhận của người dùng* trước khi thực thi bất kỳ lệnh khai thác hoặc tấn công nào.
- **Hướng dẫn cho Agent**: "Yêu cầu người dùng xác minh URL/IP mục tiêu trước khi chạy."
### 3. Thiết kế để An toàn
- **Không chứa mã độc (Weaponized Payloads)**: Các skill không được bao gồm malware hoạt động, ransomware, hoặc các mã khai thác không mang tính giáo dục.
- **Khuyến nghị dùng Sandbox**: Các hướng dẫn nên khuyến nghị chạy trong môi trường cô lập (Docker/VM).
---
## 🔵 Chính sách đối với Skill Phòng thủ
**Skill Phòng thủ là gì?**
Các công cụ dùng để tăng cường bảo mật (hardening), kiểm tra (auditing), giám sát (monitoring), hoặc bảo vệ hệ thống.
_Ví dụ: Linting (Kiểm tra lỗi code), Phân tích Log, Kiểm tra Cấu hình._
- **Quyền riêng tư dữ liệu**: Các kỹ năng phòng thủ không được tải dữ liệu lên các máy chủ bên thứ ba mà không có sự đồng ý rõ ràng của người dùng.
- **Không gây hư tổn (Non-Destructive)**: Các quy trình kiểm tra (audits) nên mặc định ở chế độ chỉ đọc (read-only).
---
## ⚖️ Tuyên bố Pháp lý
Bằng việc sử dụng repository này, bạn đồng ý rằng:
1. Bạn tự chịu trách nhiệm về hành động của mình.
2. Các tác giả và người đóng góp không chịu trách nhiệm cho bất kỳ thiệt hại nào do các công cụ này gây ra.
3. Bạn sẽ tuân thủ tất cả các luật địa phương, tiểu bang và liên bang liên quan đến an ninh mạng.

605
docs/vietnamese/SKILL_ANATOMY.md Normal file
View File

@@ -0,0 +1,605 @@
# Cấu trúc của một Skill - Hiểu về Hệ thống
**Bạn muốn hiểu cách các skill (kỹ năng) hoạt động bên trong?** Hướng dẫn này sẽ phân tích chi tiết từng phần của một file skill.
---
## 📁 Cấu trúc Thư mục Cơ bản
```
skills/
└── my-skill-name/
├── SKILL.md ← Bắt buộc: Định nghĩa skill chính
├── examples/ ← Tùy chọn: Các file ví dụ
│ ├── example1.js
│ └── example2.py
├── scripts/ ← Tùy chọn: Các script hỗ trợ
│ └── helper.sh
├── templates/ ← Tùy chọn: Các bản mẫu code (templates)
│ └── template.tsx
├── references/ ← Tùy chọn: Tài liệu tham khảo
│ └── api-docs.md
└── README.md ← Tùy chọn: Tài liệu bổ sung
```
**Quy tắc Cốt lõi:** Chỉ có file `SKILL.md` là bắt buộc. Tất cả những thành phần khác đều là tùy chọn!
---
## Cấu trúc file SKILL.md
Mỗi file `SKILL.md` có hai phần chính:
### 1. Frontmatter (Siêu dữ liệu - Metadata)
### 2. Nội dung (Hướng dẫn - Instructions)
Hãy cùng phân tích chi tiết từng phần:
---
## Phần 1: Frontmatter
Frontmatter nằm ở ngay đầu file, được bao bọc bởi cặp `---`:
```markdown
---
name: my-skill-name
description: "Mô tả ngắn gọn về chức năng của skill này"
---
```
### Các trường Bắt buộc
#### `name`
- **Định nghĩa:** Mã định danh của skill.
- **Định dạng:** chữ-thường-có-dấu-gạch-ngang (kebab-case).
- **Yêu cầu:** Phải khớp hoàn toàn với tên thư mục.
- **Ví dụ:** `stripe-integration`
#### `description`
- **Định nghĩa:** Tóm tắt chức năng trong một câu.
- **Định dạng:** Chuỗi ký tự nằm trong dấu ngoặc kép.
- **Độ dài:** Nên dưới 150 ký tự.
- **Ví dụ:** `"Các mẫu tích hợp thanh toán Stripe bao gồm checkout, đăng ký gói (subscriptions) và webhooks"`
### Các trường Tùy chọn
Một số skill bao gồm thêm siêu dữ liệu bổ sung:
```markdown
---
name: my-skill-name
description: "Mô tả ngắn"
risk: "safe" # safe | risk | official
source: "community"
tags: ["react", "typescript"]
---
```
---
## Phần 2: Nội dung
Sau phần frontmatter là nội dung thực tế của skill. Dưới đây là cấu trúc được đề xuất:
### Các mục Đề xuất
#### 1. Tiêu đề (H1)
```markdown
# Tiêu đề Skill
```
- Sử dụng tiêu đề rõ ràng, mang tính mô tả.
- Thường khớp hoặc mở rộng từ tên skill.
#### 2. Tổng quan (Overview)
```markdown
## Tổng quan
Một giải thích ngắn gọn về chức năng của skill và lý do tại sao nó tồn tại.
Khoảng 2-4 câu là lý tưởng.
```
#### 3. Khi nào cần sử dụng (When to Use)
```markdown
## Khi nào nên sử dụng Skill này
- Sử dụng khi bạn cần [tình huống 1]
- Sử dụng khi làm việc với [tình huống 2]
- Sử dụng khi người dùng hỏi về [tình huống 3]
```
**Tại sao điều này quan trọng:** Giúp AI biết khi nào cần kích hoạt skill này.
#### 4. Hướng dẫn Cốt lõi (Core Instructions)
```markdown
## Cách hoạt động
### Bước 1: [Hành động]
Hướng dẫn chi tiết...
### Bước 2: [Hành động]
Hướng dẫn thêm...
```
**Đây là linh hồn của skill** - các bước rõ ràng và có thể thực hiện được.
#### 5. Ví dụ (Examples)
```markdown
## Ví dụ
### Ví dụ 1: [Trường hợp sử dụng]
\`\`\`javascript
// Code ví dụ
\`\`\`
### Ví dụ 2: [Trường hợp sử dụng khác]
\`\`\`javascript
// Thêm code
\`\`\`
```
**Tại sao ví dụ lại quan trọng:** Chúng cho AI thấy chính xác kết quả đầu ra tốt trông như thế nào.
#### 6. Thực hành Tốt nhất (Best Practices)
```markdown
## Thực hành Tốt nhất
- ✅ Nên làm điều này
- ✅ Cũng nên làm điều này
- ❌ Không nên làm điều này
- ❌ Tránh điều này
```
#### 7. Các lỗi thường gặp (Common Pitfalls)
```markdown
## Các lỗi thường gặp
- **Vấn đề:** Mô tả lỗi
**Giải pháp:** Cách khắc phục
```
#### 8. Các Skill liên quan (Related Skills)
```markdown
## Các Skill liên quan
- `@other-skill` - Khi nào nên dùng skill này thay thế
- `@complementary-skill` - Cách các skill này hoạt động cùng nhau
```
---
## Viết Hướng dẫn Hiệu quả
### Sử dụng Ngôn ngữ Rõ ràng, Trực tiếp
**❌ Không tốt:**
```markdown
Bạn có lẽ nên cân nhắc việc kiểm tra xem người dùng đã xác thực hay chưa.
```
**✅ Tốt:**
```markdown
Kiểm tra xem người dùng đã được xác thực chưa trước khi tiếp tục.
```
### Sử dụng Động từ Hành động
**❌ Không tốt:**
```markdown
File nên được tạo ra...
```
**✅ Tốt:**
```markdown
Tạo file...
```
### Cụ thể và Chi tiết
**❌ Không tốt:**
```markdown
Thiết lập cơ sở dữ liệu một cách chính xác.
```
**✅ Tốt:**
```markdown
1. Tạo cơ sở dữ liệu PostgreSQL
2. Chạy migration: `npm run migrate`
3. Nạp dữ liệu ban đầu (seed): `npm run seed`
```
---
## Các Thành phần Tùy chọn
### Thư mục Scripts
Nếu skill của bạn cần các script hỗ trợ:
```
scripts/
├── setup.sh ← Tự động hóa thiết lập
├── validate.py ← Công cụ kiểm tra (validation)
└── generate.js ← Công cụ tạo code (generators)
```
**Tham chiếu chúng trong SKILL.md:**
```markdown
Chạy script thiết lập:
\`\`\`bash
bash scripts/setup.sh
\`\`\`
```
### Thư mục Examples
Các ví dụ thực tế minh họa skill:
```
examples/
├── basic-usage.js
├── advanced-pattern.ts
└── full-implementation/
├── index.js
└── config.json
```
### Thư mục Templates
Các mẫu code có thể tái sử dụng:
```
templates/
├── component.tsx
├── test.spec.ts
└── config.json
```
**Tham chiếu trong SKILL.md:**
```markdown
Sử dụng bản mẫu này làm điểm bắt đầu:
\`\`\`typescript
{{#include templates/component.tsx}}
\`\`\`
```
### Thư mục References
Tài liệu bên ngoài hoặc tham chiếu API:
```
references/
├── api-docs.md
├── best-practices.md
└── troubleshooting.md
```
---
## Hướng dẫn về Quy mô Skill
### Skill Tối giản (Minimum Viable Skill)
- **Frontmatter:** name + description
- **Nội dung:** 100-200 từ
- **Các mục:** Tổng quan + Hướng dẫn
### Skill Tiêu chuẩn (Standard Skill)
- **Frontmatter:** name + description
- **Nội dung:** 300-800 từ
- **Các mục:** Tổng quan + Khi nào sử dụng + Hướng dẫn + Ví dụ
### Skill Toàn diện (Comprehensive Skill)
- **Frontmatter:** name + description + các trường tùy chọn
- **Nội dung:** 800-2000 từ
- **Các mục:** Đầy đủ tất cả các mục đề xuất
- **Bổ sung:** Scripts, ví dụ, templates
**Quy tắc ngón tay cái:** Bắt đầu nhỏ, mở rộng dựa trên phản hồi.
---
## Thực hành Tốt nhất về Định dạng
### Sử dụng Markdown Hiệu quả
#### Khối Code (Code Blocks)
Luôn chỉ định ngôn ngữ:
```markdown
\`\`\`javascript
const example = "code";
\`\`\`
```
#### Danh sách (Lists)
Sử dụng định dạng nhất quán:
```markdown
- Mục 1
- Mục 2
- Mục con 2.1
- Mục con 2.2
```
#### Nhấn mạnh (Emphasis)
- **In đậm** cho các thuật ngữ quan trọng: `**quan trọng**`
- _In nghiêng_ để nhấn mạnh: `*nhấn mạnh*`
- `Code` cho lệnh hoặc code: `` `code` ``
#### Liên kết (Links)
```markdown
[Văn bản liên kết](https://example.com)
```
---
## ✅ Danh mục Kiểm tra Chất lượng (Quality Checklist)
Trước khi hoàn tất skill của bạn:
### Chất lượng Nội dung
- [ ] Hướng dẫn rõ ràng và có thể thực hiện được.
- [ ] Ví dụ thực tế và hữu ích.
- [ ] Không có lỗi chính tả hoặc ngữ pháp.
- [ ] Độ chính xác kỹ thuật đã được xác minh.
### Cấu trúc
- [ ] Frontmatter là YAML hợp lệ.
- [ ] Tên (Name) khớp với tên thư mục.
- [ ] Các phần được sắp xếp logic.
- [ ] Các tiêu đề tuân thủ cấp bậc (H1 → H2 → H3).
### Tính đầy đủ
- [ ] Phần Tổng quan giải thích "tại sao".
- [ ] Hướng dẫn giải thích "làm thế nào".
- [ ] Ví dụ cho thấy "cái gì".
- [ ] Các trường hợp biên (edge cases) được đề cập.
### Khả năng sử dụng
- [ ] Một người mới bắt đầu có thể làm theo.
- [ ] Một chuyên gia thấy nó hữu ích.
- [ ] AI có thể phân tích chính xác.
- [ ] Nó giải quyết một vấn đề thực tế.
---
## 🔍 Phân tích Ví dụ Thực tế
Hãy phân tích một skill thực tế: `brainstorming`
```markdown
---
name: brainstorming
description: "Bạn PHẢI sử dụng skill này trước bất kỳ công việc sáng tạo nào..."
---
```
**Phân tích:**
- ✅ Tên rõ ràng.
- ✅ Mô tả mạnh mẽ với tính cấp bách ("PHẢI sử dụng").
- ✅ Giải thích khi nào nên dùng.
```markdown
# Brainstorming Ý tưởng thành Thiết kế
## Tổng quan
Giúp chuyển đổi ý tưởng thành các thiết kế hoàn chỉnh...
```
**Phân tích:**
- ✅ Tiêu đề rõ ràng.
- ✅ Tổng quan súc tích.
- ✅ Giải thích giá trị mang lại.
```markdown
## Quy trình
**Hiểu ý tưởng:**
- Kiểm tra trạng thái dự án hiện tại trước.
- Đặt câu hỏi từng cái một.
```
**Phân tích:**
- ✅ Được chia thành các giai đoạn rõ ràng.
- ✅ Các bước cụ thể, có thể hành động.
- ✅ Dễ dàng thực hiện theo.
---
## Các Mẫu Nâng cao
### Logic có Điều kiện
```markdown
## Hướng dẫn
Nếu người dùng đang làm việc với React:
- Sử dụng functional components.
- Ưu tiên hooks hơn class components.
Nếu người dùng đang làm việc với Vue:
- Sử dụng Composition API.
- Tuân theo các mẫu của Vue 3.
```
### Tiết lộ Lũy tiến (Progressive Disclosure)
```markdown
## Cách dùng Cơ bản
[Hướng dẫn đơn giản cho các trường hợp phổ biến]
## Cách dùng Nâng cao
[Các mẫu phức tạp cho người dùng chuyên sâu]
```
### Tham chiếu Chéo (Cross-References)
```markdown
## Các Luồng công việc liên quan
1. Đầu tiên, dùng `@brainstorming` để thiết kế.
2. Sau đó, dùng `@writing-plans` để lập kế hoạch.
3. Cuối cùng, dùng `@test-driven-development` để triển khai.
```
---
## Đo lường Hiệu quả của Skill
Cách để biết skill của bạn có tốt hay không:
### Kiểm tra Tính Rõ ràng
- Người không quen thuộc với chủ đề có thể làm theo không?
- Có hướng dẫn nào mơ hồ không?
### Kiểm tra Tính Đầy đủ
- Nó có bao quát trường hợp thuận lợi (happy path) không?
- Nó có xử lý các trường hợp biên không?
- Các kịch bản lỗi đã được giải quyết chưa?
### Kiểm tra Tính Hữu ích
- Nó có giải quyết một vấn đề thực tế không?
- Chính bạn có sử dụng nó không?
- Nó có giúp tiết kiệm thời gian hoặc cải thiện chất lượng không?
---
## Học hỏi từ các Skill hiện có
### Nghiên cứu các Ví dụ sau
**Dành cho Người mới:**
- `skills/brainstorming/SKILL.md` - Cấu trúc rõ ràng.
- `skills/git-pushing/SKILL.md` - Đơn giản và tập trung.
- `skills/copywriting/SKILL.md` - Ví dụ tốt.
**Dành cho Nâng cao:**
- `skills/systematic-debugging/SKILL.md` - Toàn diện.
- `skills/react-best-practices/SKILL.md` - Nhiều file.
- `skills/loki-mode/SKILL.md` - Các luồng công việc phức tạp.
---
## 💡 Mẹo Chuyên nghiệp
1. **Bắt đầu với phần "Khi nào sử dụng"** - Điều này làm rõ mục đích của skill.
2. **Viết ví dụ trước** - Chúng giúp bạn hiểu những gì bạn đang dạy.
3. **Kiểm tra với AI** - Xem liệu nó có thực sự hoạt động trước khi gửi.
4. **Nhận phản hồi** - Nhờ người khác xem qua skill của bạn.
5. **Cải thiện liên tục** - Skill sẽ tốt lên theo thời gian dựa trên việc sử dụng.
---
## Các lỗi Thường gặp cần Tránh
### ❌ Lỗi 1: Quá mơ hồ
```markdown
## Hướng dẫn
Làm cho code tốt hơn.
```
**✅ Khắc phục:**
```markdown
## Hướng dẫn
1. Tách các logic lặp lại thành các hàm.
2. Thêm xử lý lỗi cho các trường hợp biên.
3. Viết unit tests cho các chức năng cốt lõi.
```
### ❌ Lỗi 2: Quá phức tạp
```markdown
## Hướng dẫn
[5000 từ chứa đầy thuật ngữ kỹ thuật dày đặc]
```
**✅ Khắc phục:**
Chia nhỏ thành nhiều skill hoặc sử dụng phương pháp tiết lộ lũy tiến.
### ❌ Lỗi 3: Không có ví dụ
```markdown
## Hướng dẫn
[Hướng dẫn mà không có bất kỳ ví dụ code nào]
```
**✅ Khắc phục:**
Thêm ít nhất 2-3 ví dụ thực tế.
### ❌ Lỗi 4: Thông tin lỗi thời
```markdown
Sử dụng React class components...
```
**✅ Khắc phục:**
Luôn cập nhật skill với các thực hành tốt nhất hiện tại.
---
## 🎯 Các bước Tiếp theo
1. **Đọc 3-5 skill hiện có** để thấy các phong cách khác nhau.
2. **Thử dùng bản mẫu skill** từ file `CONTRIBUTING.md`.
3. **Tạo một skill đơn giản** cho lĩnh vực bạn am hiểu.
4. **Kiểm tra nó** với trợ lý AI của bạn.
5. **Chia sẻ nó** qua Pull Request.
---
**Hãy nhớ rằng:** Mọi chuyên gia đều từng là người mới bắt đầu. Hãy bắt đầu đơn giản, học hỏi từ phản hồi và cải thiện theo thời gian! 🚀

21
docs/vietnamese/SOURCES.md Normal file
View File

@@ -0,0 +1,21 @@
# 📜 Nguồn gốc & Ghi công
Chúng tôi tin tưởng vào việc ghi nhận công sức một cách xứng đáng.
Nếu bạn nhận ra tác phẩm của mình ở đây mà chưa được ghi công đúng cách, vui lòng mở một Issue (Báo lỗi).
| Kỹ năng / Danh mục | Nguồn gốc | Giấy phép | Ghi chú |
| :-------------------------- | :----------------------------------------------------- | :------------- | :---------------------------- |
| `cloud-penetration-testing` | [HackTricks](https://book.hacktricks.xyz/) | MIT / CC-BY-SA | Được chuyển đổi cho trợ lý AI.|
| `active-directory-attacks` | [HackTricks](https://book.hacktricks.xyz/) | MIT / CC-BY-SA | Được chuyển đổi cho trợ lý AI.|
| `owasp-top-10` | [OWASP](https://owasp.org/) | CC-BY-SA | Chuyển đổi từ phương pháp gốc.|
| `burp-suite-testing` | [PortSwigger](https://portswigger.net/burp) | Không có | Chỉ là hướng dẫn sử dụng. |
| `crewai` | [CrewAI](https://github.com/joaomdmoura/crewAI) | MIT | Hướng dẫn về framework. |
| `langgraph` | [LangGraph](https://github.com/langchain-ai/langgraph) | MIT | Hướng dẫn về framework. |
| `react-patterns` | [React Docs](https://react.dev/) | CC-BY | Các mẫu thiết kế chính thức. |
| **Tất cả Skill Chính thức** | [Anthropic / Google / OpenAI] | Bản quyền riêng| Được khuyến khích bởi nhà CC. |
## Chính sách Giấy phép
- **Mã nguồn (Code)**: Tất cả mã nguồn gốc trong repository này tuân theo giấy phép **MIT**.
- **Nội dung (Content)**: Tài liệu hướng dẫn tuân theo giấy phép **CC-BY-4.0**.
- **Bên thứ ba**: Chúng tôi tôn trọng giấy phép từ phía nguồn gốc của các tài liệu. Nếu một kỹ năng được nhập về có giấy phép GPL, nó sẽ được đánh dấu rõ ràng hoặc bị loại trừ (chúng tôi hướng tới sự tương thích với MIT/Apache).

512
docs/vietnamese/VISUAL_GUIDE.md Normal file
View File

@@ -0,0 +1,512 @@
# Hướng dẫn Nhanh bằng Hình ảnh (Visual Guide)
**Học qua hình ảnh!** Hướng dẫn này sử dụng các sơ đồ và ví dụ trực quan để giúp bạn hiểu về các kỹ năng (skills).
---
## Cái nhìn Tổng quan
```
┌─────────────────────────────────────────────────────────────┐
│ BẠN (Lập trình viên) │
│ ↓ │
│ "Giúp tôi xây dựng hệ thống thanh toán" │
│ ↓ │
├─────────────────────────────────────────────────────────────┤
│ TRỢ LÝ AI (AI ASSISTANT) │
│ ↓ │
│ Tải kỹ năng @stripe-integration │
│ ↓ │
│ Trở thành chuyên gia về thanh toán Stripe │
│ ↓ │
│ Cung cấp hỗ trợ chuyên sâu kèm các ví dụ code │
└─────────────────────────────────────────────────────────────┘
```
---
## 📦 Cấu trúc Repository (Trực quan)
```
antigravity-awesome-skills/
│
├── 📄 README.md ← Tổng quan & danh sách skill
├── 📄 CONTRIBUTING.md ← Cách thức đóng góp
│
├── 📁 skills/ ← Nơi chứa tất cả hơn 250 skills
│ │
│ ├── 📁 brainstorming/
│ │ └── 📄 SKILL.md ← Định nghĩa skill
│ │
│ ├── 📁 stripe-integration/
│ │ ├── 📄 SKILL.md
│ │ └── 📁 examples/ ← Các phần bổ sung tùy chọn
│ │
│ └── ... (Hơn 250 skills khác)
│
├── 📁 scripts/ ← Quản lý & Xác thực
│ ├── validate_skills.py ← Công cụ kiểm soát chất lượng
│ └── generate_index.py ← Công cụ tạo danh mục (registry)
│
├── 📁 .github/
│ └── 📄 MAINTENANCE.md ← Hướng dẫn cho người duy trì
│
└── 📁 docs/ ← Tài liệu hướng dẫn
├── 📄 GETTING_STARTED.md ← Bắt đầu tại đây! (MỚI)
├── 📄 FAQ.md ← Giải đáp thắc mắc
├── 📄 BUNDLES.md ← Gói khởi đầu (MỚI)
├── 📄 QUALITY_BAR.md ← Tiêu chuẩn chất lượng
├── 📄 SKILL_ANATOMY.md ← Cách thức skill hoạt động
└── 📄 VISUAL_GUIDE.md ← Chính là file này!
```
---
## Cách Skills Hoạt động (Sơ đồ Luồng)
```
┌──────────────┐
│ 1. CÀI ĐẶT │ Sao chép skills vào .agent/skills/
1 └──────┬───────┘
│
↓
┌──────────────┐
│ 2. GỌI LỆNH │ Gõ: @ten-skill trong chat với AI
└──────┬───────┘
│
↓
┌──────────────┐
│ 3. TẢI DỮ LIỆU│ AI đọc file SKILL.md
└──────┬───────┘
│
↓
┌──────────────┐
│ 4. THỰC THI │ AI tuân theo hướng dẫn trong skill
└──────┬───────┘
│
↓
┌──────────────┐
│ 5. KẾT QUẢ │ Bạn nhận được hỗ trợ chuyên sâu!
└──────────────┘
```
---
## 🎯 Phân loại Skills (Bản đồ Trực quan)
```
┌─────────────────────────┐
│ 250+ AWESOME SKILLS │
└────────────┬────────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
┌────▼────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ SÁNG TẠO│ │ PHÁT TRIỂN │ │ BẢO MẬT │
│ (10) │ │ (25) │ │ (50) │
└────┬────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
• Thiết kế UI/UX • TDD • Hacking Đạo đức
• Nghệ thuật Canvas • Debugging • Metasploit
• Giao diện/Themes • Mẫu thiết kế React • Burp Suite
• SQLMap
│ │ │
└────────────────────────┼────────────────────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
┌────▼────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ AI │ │ TÀI LIỆU │ │ MARKETING │
│ (30) │ │ (4) │ │ (23) │
└────┬────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
• Hệ thống RAG • DOCX • SEO
• LangGraph • PDF • Copywriting
• Prompt Eng. • PPTX • CRO
• Voice Agents • XLSX • Quảng cáo trả phí
```
---
## Cấu trúc File Skill (Trực quan)
````
┌─────────────────────────────────────────────────────────┐
│ SKILL.md │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────┐ │
│ │ FRONTMATTER (Siêu dữ liệu) │ │
│ │ ───────────────────────────────────────────── │ │
│ │ --- │ │
│ │ name: my-skill │ │
│ │ description: "Công dụng của skill này" │ │
│ │ --- │ │
│ └───────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────┐ │
│ │ NỘI DUNG (Hướng dẫn) │ │
│ │ ───────────────────────────────────────────── │ │
│ │ │ │
│ │ # Tiêu đề Skill │ │
│ │ │ │
│ │ ## Tổng quan │ │
│ │ Skill này làm gì... │ │
│ │ │ │
│ │ ## Khi nào nên dùng │ │
│ │ - Sử dụng khi... │ │
│ │ │ │
│ │ ## Hướng dẫn │ │
│ │ 1. Bước đầu tiên... │ │
│ │ 2. Bước thứ hai... │ │
│ │ │ │
│ │ ## Ví dụ │ │
│ │ ```javascript │ │
│ │ // Code ví dụ │ │
│ │ ``` │ │
│ │ │ │
│ └───────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
````
---
## Cài đặt (Các bước Trực quan)
### Bước 1: Sao chép Repository
```
┌─────────────────────────────────────────┐
│ Terminal │
├─────────────────────────────────────────┤
│ $ git clone https://github.com/ │
│ sickn33/antigravity-awesome-skills │
│ .agent/skills │
│ │
│ ✓ Đang sao chép vào '.agent/skills'... │
│ ✓ Hoàn tất! │
└─────────────────────────────────────────┘
```
### Bước 2: Xác minh Cài đặt
```
┌─────────────────────────────────────────┐
│ File Explorer │
├─────────────────────────────────────────┤
│ 📁 .agent/ │
│ └── 📁 skills/ │
│ ├── 📁 brainstorming/ │
│ ├── 📁 stripe-integration/ │
│ ├── 📁 react-best-practices/ │
│ └── ... (Thêm 176 mục nữa) │
└─────────────────────────────────────────┘
```
### Bước 3: Sử dụng Skill
```
┌─────────────────────────────────────────┐
│ AI Assistant Chat │
├─────────────────────────────────────────┤
│ Bạn: @brainstorming giúp tôi thiết kế │
│ một ứng dụng todo │
│ │
│ AI: Tuyệt vời! Hãy để tôi giúp bạn suy │
│ nghĩ kỹ về việc này. Đầu tiên, hãy │
│ tìm hiểu các yêu cầu của bạn... │
│ │
│ Mục đích sử dụng chính là gì? │
│ a) Quản lý công việc cá nhân │
│ b) Hợp tác nhóm │
│ c) Lập kế hoạch dự án │
└─────────────────────────────────────────┘
```
---
## Ví dụ: Sử dụng Skill (Từng bước)
### Tình huống: Bạn muốn thêm thanh toán Stripe vào ứng dụng của mình
```
┌─────────────────────────────────────────────────────────────┐
│ BƯỚC 1: Xác định Nhu cầu │
├─────────────────────────────────────────────────────────────┤
│ "Tôi cần thêm xử lý thanh toán vào ứng dụng của mình" │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ BƯỚC 2: Tìm đúng Skill │
├─────────────────────────────────────────────────────────────┤
│ Tìm kiếm: "payment" hoặc "stripe" │
│ Tìm thấy: @stripe-integration │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ BƯỚC 3: Gọi lệnh Skill │
├─────────────────────────────────────────────────────────────┤
│ Bạn: @stripe-integration giúp tôi thêm thanh toán định kỳ │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ BƯỚC 4: AI Tải Kiến thức của Skill │
├─────────────────────────────────────────────────────────────┤
│ • Các mẫu Stripe API │
│ • Xử lý Webhook │
│ • Quản lý gói đăng ký (Subscription) │
│ • Thực hành tốt nhất │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ BƯỚC 5: Nhận Hỗ trợ Chuyên gia │
├─────────────────────────────────────────────────────────────┤
│ AI cung cấp: │
│ • Các ví dụ code │
│ • Hướng dẫn thiết lập │
│ • Các lưu ý về bảo mật │
│ • Chiến lược kiểm thử │
└─────────────────────────────────────────────────────────────┘
```
---
## Tìm kiếm Skills (Hướng dẫn Trực quan)
### Cách 1: Duyệt theo Danh mục
```
README.md → Cuộn xuống "Full Skill Registry" → Tìm danh mục → Chọn skill
```
### Cách 2: Tìm theo Từ khóa
```
Terminal → ls skills/ | grep "từ-khóa" → Xem các skill khớp
```
### Cách 3: Sử dụng Index
```
Mở file skills_index.json → Tìm từ khóa → Tìm đường dẫn đến skill
```
---
## Tạo Skill đầu tiên của bạn (Quy trình Trực quan)
```
┌──────────────┐
│ 1. Ý TƯỞNG │ "Tôi muốn chia sẻ kiến thức về Docker"
└──────┬───────┘
│
↓
┌──────────────┐
│ 2. KHỞI TẠO │ mkdir skills/docker-mastery
└──────┬───────┘ touch skills/docker-mastery/SKILL.md
│
↓
┌──────────────┐
│ 3. VIẾT │ Thêm frontmatter + nội dung
└──────┬───────┘ (Dùng template từ CONTRIBUTING.md)
│
↓
┌──────────────┐
│ 4. KIỂM THỬ │ Sao chép vào .agent/skills/
└──────┬───────┘ Thử: @docker-mastery
│
↓
┌──────────────┐
│ 5. XÁC THỰC │ python3 scripts/validate_skills.py
└──────┬───────┘
│
↓
┌──────────────┐
│ 6. GỬI ĐI │ git commit + push + Pull Request
└──────────────┘
```
---
## Các Cấp độ Phức tạp của Skill
```
┌─────────────────────────────────────────────────────────────┐
│ ĐỘ PHỨC TẠP CỦA SKILL │
├─────────────────────────────────────────────────────────────┤
│ │
│ ĐƠN GIẢN TIÊU CHUẨN PHỨC TẠP │
│ ──────── ────────── ──────── │
│ │
│ • 1 file • 1 file • Nhiều file│
│ • 100-200 từ • 300-800 từ • 800-2000 từ│
│ • Cấu trúc cơ bản • Cấu trúc đầy đủ • Có scripts │
│ • Không có phần phụ • Có ví dụ • Có ví dụ │
│ • Thực hành tốt nhất • Có template│
│ • Có tài liệu│
│ Ví dụ: Ví dụ: Ví dụ: │
│ git-pushing brainstorming loki-mode │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## 🎯 Tác động của việc Đóng góp (Trực quan)
```
Sự đóng góp của bạn
│
├─→ Cải thiện tài liệu hướng dẫn
│ │
│ └─→ Giúp hàng ngàn dev dễ hiểu hơn
│
├─→ Tạo ra Skill mới
│ │
│ └─→ Mang lại khả năng mới cho mọi người
│
├─→ Sửa lỗi/Lỗi chính tả
│ │
│ └─→ Tránh hiểu lầm cho người dùng tương lai
│
└─→ Thêm ví dụ
│
└─→ Giúp người mới học dễ dàng hơn
```
---
## Lộ trình Học tập (Roadmap Trực quan)
```
BẮT ĐẦU TẠI ĐÂY
│
↓
┌─────────────────┐
│ Đọc │
│ GETTING_STARTED │
└────────┬────────┘
│
↓
┌─────────────────┐
│ Thử dùng 2-3 Skill│
│ với Trợ lý AI │
└────────┬────────┘
│
↓
┌─────────────────┐
│ Đọc │
│ SKILL_ANATOMY │
└────────┬────────┘
│
↓
┌─────────────────┐
│ Nghiên cứu │
│ Skills hiện có │
└────────┬────────┘
│
↓
┌─────────────────┐
│ Tạo Skill │
│ đơn giản │
└────────┬────────┘
│
↓
┌─────────────────┐
│ Đọc │
│ CONTRIBUTING │
└────────┬────────┘
│
↓
┌─────────────────┐
│ Gửi PR │
└────────┬────────┘
│
↓
TRỞ THÀNH CONTRIBUTOR! 🎉
```
---
## 💡 Mẹo Nhanh (Bản ghi chú Trực quan)
```
┌─────────────────────────────────────────────────────────────┐
│ THAM KHẢO NHANH │
├─────────────────────────────────────────────────────────────┤
│ │
│ 📥 CÀI ĐẶT │
│ git clone [repo] .agent/skills │
│ │
│ 🎯 SỬ DỤNG │
│ @ten-skill [yêu cầu của bạn] │
│ │
│ 🔍 TÌM KIẾM │
│ ls skills/ | grep "từ-khóa" │
│ │
│ ✅ XÁC THỰC │
│ python3 scripts/validate_skills.py │
│ │
│ 📝 TẠO SKILL │
│ 1. mkdir skills/ten-skill-cua-ban │
│ 2. Tạo SKILL.md với frontmatter │
│ 3. Thêm nội dung │
│ 4. Thử nghiệm & xác thực │
│ 5. Gửi Pull Request (PR) │
│ │
│ 🆘 TRỢ GIÚP │
│ • docs/GETTING_STARTED.md - Cơ bản │
│ • CONTRIBUTING.md - Cách đóng góp │
│ • SKILL_ANATOMY.md - Tìm hiểu sâu │
│ • GitHub Issues - Đặt câu hỏi │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## Câu chuyện Thành công (Dòng thời gian Trực quan)
```
Ngày 1: Cài đặt skills
│
└─→ "Oa, @brainstorming đã giúp mình thiết kế ứng dụng!"
Ngày 3: Dùng 5 skills khác nhau
│
└─→ "Những kỹ năng này giúp mình tiết kiệm bao nhiêu thời gian!"
Tuần 1: Tạo skill đầu tiên
│
└─→ "Mình đã chia sẻ kiến thức của mình dưới dạng một skill!"
Tuần 2: Skill được gộp (merge) vào máy chủ
│
└─→ "Kỹ năng của mình đang giúp đỡ người khác! 🎉"
Tháng 1: Trở thành người đóng góp thường xuyên
│
└─→ "Mình đã đóng góp 5 skills và cải thiện rất nhiều tài liệu!"
```
---
## Các Bước Tiếp theo
1. ✅ **Hiểu** cấu trúc trực quan.
2. ✅ **Cài đặt** skills vào công cụ AI của bạn.
3. ✅ **Thử dùng** 2-3 skills từ các danh mục khác nhau.
4. ✅ **Đọc** file CONTRIBUTING.md.
5. ✅ **Tạo** skill đầu tiên của bạn.
6. ✅ **Chia sẻ** với cộng đồng.
---
**Bạn là người học qua hình ảnh?** Hy vọng hướng dẫn này sẽ giúp ích! Bạn vẫn còn thắc mắc? Hãy kiểm tra:
- [GETTING_STARTED.md](GETTING_STARTED.md) - Giới thiệu bằng văn bản.
- [SKILL_ANATOMY.md](SKILL_ANATOMY.md) - Phân tích chi tiết.
- [CONTRIBUTING.md](../CONTRIBUTING.md) - Cách thức đóng góp.
**Sẵn sàng đóng góp?** Bạn làm được mà! 💪

55
docs/vietnamese/skills/architecture/SKILL.md Normal file
View File

@@ -0,0 +1,55 @@
---
name: architecture
description: Khung ra quyết định kiến trúc. Phân tích yêu cầu, đánh giá đánh đổi, tài liệu hóa ADR. Sử dụng khi đưa ra các quyết định kiến trúc hoặc phân tích thiết kế hệ thống.
allowed-tools: Read, Glob, Grep
---
# Khung Quyết định Kiến trúc (Architecture Decision Framework)
> "Yêu cầu thúc đẩy kiến trúc. Sự đánh đổi định hình quyết định. ADRs lưu giữ lý do."
## 🎯 Quy tắc Đọc Chọn lọc
**CHỈ ĐỌC các file liên quan đến yêu cầu!** Kiểm tra bản đồ nội dung, tìm thứ bạn cần.
| File | Mô tả | Khi nào đọc |
|------|-------------|--------------|
| `context-discovery.md` | Các câu hỏi cần đặt ra, phân loại dự án | Bắt đầu thiết kế kiến trúc |
| `trade-off-analysis.md` | Mẫu ADR, khung phân tích đánh đổi | Tài liệu hóa quyết định |
| `pattern-selection.md` | Cây quyết định, anti-patterns | Lựa chọn mẫu (patterns) |
| `examples.md` | Ví dụ MVP, SaaS, Doanh nghiệp lớn | Tham chiếu triển khai |
| `patterns-reference.md` | Tra cứu nhanh các mẫu | So sánh các mẫu |
---
## 🔗 Các Kỹ năng Liên quan
| Kỹ năng | Dùng cho |
|-------|---------|
| `@[skills/database-design]` | Thiết kế schema cơ sở dữ liệu |
| `@[skills/api-patterns]` | Các mẫu thiết kế API |
| `@[skills/deployment-procedures]` | Kiến trúc triển khai |
---
## Nguyên tắc Cốt lõi
**"Đơn giản là đỉnh cao của sự tinh tế."**
- Bắt đầu đơn giản
- CHỈ thêm độ phức tạp khi đã chứng minh là cần thiết
- Bạn luôn có thể thêm các mẫu sau này
- Loại bỏ độ phức tạp khó hơn RẤT NHIỀU so với việc thêm vào
---
## Checklist Xác thực
Trước khi chốt kiến trúc:
- [ ] Các yêu cầu đã được hiểu rõ ràng
- [ ] Các ràng buộc đã được xác định
- [ ] Mỗi quyết định đều có phân tích đánh đổi
- [ ] Các phương án thay thế đơn giản hơn đã được xem xét
- [ ] ADRs đã được viết cho các quyết định quan trọng
- [ ] Chuyên môn của đội ngũ phù hợp với các mẫu được chọn

62
docs/vietnamese/skills/concise-planning/SKILL.md Normal file
View File

@@ -0,0 +1,62 @@
---
name: concise-planning
description: Sử dụng khi người dùng yêu cầu lập kế hoạch cho một tác vụ lập trình, nhằm tạo ra một danh sách kiểm tra (checklist) rõ ràng, khả thi và chia nhỏ (atomic).
---
# Lập Kế hoạch Súc tích (Concise Planning)
## Mục tiêu
Biến yêu cầu của người dùng thành một **kế hoạch hành động duy nhất** với các bước nhỏ, cụ thể (atomic steps).
## Quy trình làm việc
### 1. Quét Bối cảnh (Scan Context)
- Đọc `README.md`, tài liệu và các file code liên quan.
- Xác định các ràng buộc (ngôn ngữ, frameworks, kiểm thử).
### 2. Tương tác Tối thiểu
- Hỏi **tối đa 1–2 câu hỏi** và chỉ hỏi nếu thực sự bị chặn (blocking).
- Đưa ra các giả định hợp lý cho những ẩn số không gây cản trở.
### 3. Tạo Kế hoạch
Sử dụng cấu trúc sau:
- **Cách tiếp cận (Approach)**: 1-3 câu về cái gì và tại sao.
- **Phạm vi (Scope)**: Các gạch đầu dòng cho "Trong phạm vi" (In) và "Ngoài phạm vi" (Out).
- **Hạng mục Hành động (Action Items)**: Một danh sách gồm 6-10 tác vụ nhỏ, được sắp xếp theo thứ tự (Bắt đầu bằng động từ).
- **Xác thực (Validation)**: Ít nhất một mục dành cho việc kiểm thử.
## Mẫu Kế hoạch
```markdown
# Kế hoạch
<Cách tiếp cận cấp cao>
## Phạm vi (Scope)
- Trong phạm vi (In):
- Ngoài phạm vi (Out):
## Hạng mục Hành động (Action Items)
[ ] <Bước 1: Khám phá/Tìm hiểu>
[ ] <Bước 2: Triển khai>
[ ] <Bước 3: Triển khai>
[ ] <Bước 4: Xác thực/Kiểm thử>
[ ] <Bước 5: Triển khai/Commit>
## Câu hỏi Mở
- <Câu hỏi 1 (tối đa 3)>
```
## Hướng dẫn Checklist
- **Tính nguyên tử (Atomic)**: Mỗi bước nên là một đơn vị công việc logic duy nhất.
- **Bắt đầu bằng động từ (Verb-first)**: "Thêm...", "Tái cấu trúc (Refactor)...", "Xác minh...".
- **Cụ thể (Concrete)**: Nêu tên các file hoặc module cụ thể khi có thể.

33
docs/vietnamese/skills/git-pushing/SKILL.md Normal file
View File

@@ -0,0 +1,33 @@
---
name: git-pushing
description: Stage, commit, và push các thay đổi git với thông điệp commit theo chuẩn (conventional commit messages). Sử dụng khi người dùng muốn commit và push thay đổi, đề cập đến việc đẩy lên remote, hoặc yêu cầu lưu và đẩy công việc của họ. Cũng kích hoạt khi người dùng nói "push changes", "commit and push", "push this", "push to github", hoặc các yêu cầu quy trình công việc git tương tự.
---
# Quy trình Git Push
Stage tất cả thay đổi, tạo một commit theo chuẩn, và đẩy lên nhánh remote.
## Khi nào nên sử dụng
Tự động kích hoạt khi người dùng:
- Yêu cầu đẩy các thay đổi một cách rõ ràng ("push cái này", "commit và push")
- Đề cập đến việc lưu công việc lên remote ("lưu lên github", "push lên remote")
- Hoàn thành một tính năng và muốn chia sẻ nó
- Nói các cụm từ như "hãy push cái này lên" hoặc "commit những thay đổi này"
## Quy trình làm việc
**LUÔN LUÔN sử dụng script** - KHÔNG sử dụng các lệnh git thủ công:
```bash
bash skills/git-pushing/scripts/smart_commit.sh
```
Với thông điệp tùy chỉnh:
```bash
bash skills/git-pushing/scripts/smart_commit.sh "feat: them tinh nang"
```
Script sẽ xử lý: staging, thông điệp commit theo chuẩn, footer của Claude, và push với cờ -u.

700
docs/vietnamese/skills/kaizen/SKILL.md Normal file
View File

@@ -0,0 +1,700 @@
---
name: kaizen
description: Hướng dẫn cải tiến liên tục, chống lỗi và chuẩn hóa. Sử dụng kỹ năng này khi người dùng muốn cải thiện chất lượng code, tái cấu trúc (refactor) hoặc thảo luận về cải tiến quy trình.
---
# Kaizen: Cải tiến Liên tục
## Tổng quan
Những cải tiến nhỏ, diễn ra liên tục. Thiết kế để chống lỗi (Error-proof). Tuân theo những gì hiệu quả. Chỉ xây dựng những gì cần thiết.
**Nguyên tắc cốt lõi:** Nhiều cải tiến nhỏ đánh bại một thay đổi lớn. Ngăn chặn lỗi ngay từ lúc thiết kế, không phải bằng các bản vá.
## Khi nào nên Sử dụng
**Luôn áp dụng cho:**
- Triển khai và tái cấu trúc code
- Các quyết định về kiến trúc và thiết kế
- Cải thiện quy trình và luồng công việc
- Xử lý lỗi và xác thực (validation)
**Triết lý:** Chất lượng đến từ sự tiến bộ từng bước và sự ngăn ngừa, không phải sự hoàn hảo thông qua nỗ lực khổng lồ.
## Bốn Trụ cột
### 1. Cải tiến Liên tục (Kaizen)
Những cải tiến nhỏ, thường xuyên sẽ tích lũy thành những thành quả lớn.
#### Nguyên tắc
**Gia tăng (Incremental) hơn là Cách mạng:**
- Thực hiện thay đổi nhỏ nhất có thể nhưng cải thiện được chất lượng
- Một cải tiến tại một thời điểm
- Xác minh từng thay đổi trước khi sang bước tiếp theo
- Xây dựng đà phát triển thông qua những thắng lợi nhỏ
**Luôn để lại code tốt hơn lúc đầu:**
- Sửa các vấn đề nhỏ ngay khi bạn gặp chúng
- Refactor trong khi làm việc (trong phạm vi cho phép)
- Cập nhật các comment lỗi thời
- Xóa code chết (dead code) khi bạn thấy nó
**Tinh chỉnh lặp lại (Iterative refinement):**
- Phiên bản đầu tiên: làm cho nó hoạt động (work)
- Phiên bản thứ hai: làm cho nó rõ ràng (clear)
- Phiên bản thứ ba: làm cho nó hiệu quả (efficient)
- Đừng cố gắng làm cả ba cùng một lúc
<Good>
```typescript
// Lần lặp 1: Làm cho nó hoạt động
const calculateTotal = (items: Item[]) => {
let total = 0;
for (let i = 0; i < items.length; i++) {
total += items[i].price * items[i].quantity;
}
return total;
};
// Lần lặp 2: Làm cho nó rõ ràng (refactor)
const calculateTotal = (items: Item[]): number => {
return items.reduce((total, item) => {
return total + (item.price * item.quantity);
}, 0);
};
// Lần lặp 3: Làm cho nó mạnh mẽ (thêm validation)
const calculateTotal = (items: Item[]): number => {
if (!items?.length) return 0;
return items.reduce((total, item) => {
if (item.price < 0 || item.quantity < 0) {
throw new Error('Price and quantity must be non-negative');
}
return total + (item.price * item.quantity);
}, 0);
};
```
Mỗi bước đều hoàn chỉnh, đã được kiểm thử và hoạt động tốt
</Good>
<Bad>
```typescript
// Cố gắng làm mọi thứ cùng một lúc
const calculateTotal = (items: Item[]): number => {
// Validate, tối ưu hóa, thêm tính năng, xử lý trường hợp biên cùng lúc
if (!items?.length) return 0;
const validItems = items.filter(item => {
if (item.price < 0) throw new Error('Negative price');
if (item.quantity < 0) throw new Error('Negative quantity');
return item.quantity > 0; // Cũng lọc luôn số lượng bằng 0
});
// Cộng thêm caching, logging, chuyển đổi tiền tệ...
return validItems.reduce(...); // Quá nhiều mối quan tâm cùng lúc
};
```
Choáng ngợp, dễ lỗi, khó xác minh
</Bad>
#### Trong Thực tế
**Khi triển khai tính năng:**
1. Bắt đầu với phiên bản đơn giản nhất có thể hoạt động
2. Thêm một cải tiến (xử lý lỗi, validation, v.v.)
3. Kiểm thử và xác minh
4. Lặp lại nếu thời gian cho phép
5. Đừng cố làm cho nó hoàn hảo ngay lập tức
**Khi tái cấu trúc (refactoring):**
- Sửa từng vấn đề (code smell) một
- Commit sau mỗi cải tiến
- Giữ cho các bài kiểm tra luôn xanh (pass) trong suốt quá trình
- Dừng lại khi "đủ tốt" (hiệu suất giảm dần)
**Khi review code:**
- Đề xuất các cải tiến nhỏ (không phải viết lại toàn bộ)
- Ưu tiên: tối quan trọng → quan trọng → có thì tốt (nice-to-have)
- Tập trung vào những thay đổi có tác động lớn nhất trước
- Chấp nhận "tốt hơn trước đó" ngay cả khi chưa hoàn hảo
### 2. Poka-Yoke (Chống lỗi)
Thiết kế hệ thống ngăn chặn lỗi tại thời điểm biên dịch/thiết kế, không phải tại thời điểm chạy (runtime).
#### Nguyên tắc
**Làm cho lỗi không thể xảy ra:**
- Hệ thống Type bắt các sai sót
- Trình biên dịch thực thi các hợp đồng (contracts)
- Các trạng thái không hợp lệ không thể biểu diễn được
- Lỗi được bắt sớm (dịch chuyển sang trái quy trình sản xuất - left of production)
**Thiết kế để an toàn:**
- Thất bại nhanh và rõ ràng (Fail fast and loudly)
- Cung cấp thông báo lỗi hữu ích
- Làm cho con đường đúng đắn trở nên rõ ràng
- Làm cho con đường sai trở nên khó khăn
**Phòng thủ theo lớp:**
1. Hệ thống Type (thời điểm biên dịch)
2. Validation (thời điểm chạy, sớm)
3. Guards (điều kiện tiên quyết)
4. Ranh giới lỗi (xuống cấp nhẹ nhàng - graceful degradation)
#### Chống lỗi bằng Hệ thống Type
<Good>
```typescript
// Lỗi: trạng thái dạng string có thể là bất kỳ giá trị nào
type OrderBad = {
status: string; // Có thể là "pending", "PENDING", "pnding", bất cứ thứ gì!
total: number;
};
// Tốt: Chỉ các trạng thái hợp lệ mới khả thi
type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered';
type Order = {
status: OrderStatus;
total: number;
};
// Tốt hơn: Trạng thái đi kèm dữ liệu liên quan
type Order =
| { status: 'pending'; createdAt: Date }
| { status: 'processing'; startedAt: Date; estimatedCompletion: Date }
| { status: 'shipped'; trackingNumber: string; shippedAt: Date }
| { status: 'delivered'; deliveredAt: Date; signature: string };
// Giờ đây không thể có trạng thái 'shipped' mà thiếu 'trackingNumber'
```
Hệ thống Type ngăn chặn toàn bộ các lớp lỗi
</Good>
<Good>
```typescript
// Làm cho trạng thái không hợp lệ không thể biểu diễn
type NonEmptyArray<T> = [T, ...T[]];
const firstItem = <T>(items: NonEmptyArray<T>): T => {
return items[0]; // Luôn an toàn, không bao giờ undefined!
};
// Người gọi phải chứng minh mảng không rỗng
const items: number[] = [1, 2, 3];
if (items.length > 0) {
firstItem(items as NonEmptyArray<number>); // An toàn
}
```
Chữ ký hàm đảm bảo an toàn
</Good>
#### Chống lỗi bằng Validation
<Good>
```typescript
// Lỗi: Validation sau khi sử dụng
const processPayment = (amount: number) => {
const fee = amount * 0.03; // Đã dùng trước khi validate!
if (amount <= 0) throw new Error('Invalid amount');
// ...
};
// Tốt: Validate ngay lập tức
const processPayment = (amount: number) => {
if (amount <= 0) {
throw new Error('Payment amount must be positive');
}
if (amount > 10000) {
throw new Error('Payment exceeds maximum allowed');
}
const fee = amount * 0.03;
// ... giờ đã an toàn để sử dụng
};
// Tốt hơn: Validate tại ranh giới với branded type
type PositiveNumber = number & { readonly __brand: 'PositiveNumber' };
const validatePositive = (n: number): PositiveNumber => {
if (n <= 0) throw new Error('Must be positive');
return n as PositiveNumber;
};
const processPayment = (amount: PositiveNumber) => {
// amount được đảm bảo là số dương, không cần kiểm tra lại
const fee = amount * 0.03;
};
// Validate tại ranh giới hệ thống
const handlePaymentRequest = (req: Request) => {
const amount = validatePositive(req.body.amount); // Validate một lần
processPayment(amount); // Sử dụng mọi nơi an toàn
};
```
Validate một lần tại ranh giới, an toàn ở mọi nơi khác
</Good>
#### Guards và Điều kiện tiên quyết
<Good>
```typescript
// Return sớm ngăn chặn code lồng nhau sâu
const processUser = (user: User | null) => {
if (!user) {
logger.error('User not found');
return;
}
if (!user.email) {
logger.error('User email missing');
return;
}
if (!user.isActive) {
logger.info('User inactive, skipping');
return;
}
// Logic chính ở đây, đảm bảo user hợp lệ và đang hoạt động
sendEmail(user.email, 'Welcome!');
};
```
Guards làm cho các giả định trở nên rõ ràng và được thực thi
</Good>
#### Chống lỗi Cấu hình
<Good>
```typescript
// Lỗi: Cấu hình tùy chọn với mặc định không an toàn
type ConfigBad = {
apiKey?: string;
timeout?: number;
};
const client = new APIClient({ timeout: 5000 }); // Thiếu apiKey!
// Tốt: Cấu hình bắt buộc, lỗi sớm
type Config = {
apiKey: string;
timeout: number;
};
const loadConfig = (): Config => {
const apiKey = process.env.API_KEY;
if (!apiKey) {
throw new Error('API_KEY environment variable required');
}
return {
apiKey,
timeout: 5000,
};
};
// App lỗi ngay khi khởi động nếu config không hợp lệ, không phải lúc đang request
const config = loadConfig();
const client = new APIClient(config);
```
Lỗi lúc khởi động, không phải trong môi trường producton
</Good>
#### Trong Thực tế
**Khi thiết kế API:**
- Sử dụng Types để ràng buộc đầu vào
- Làm cho trạng thái không hợp lệ không thể biểu diễn
- Trả về Result<T, E> thay vì ném ra lỗi (throwing)
- Tài liệu hóa các điều kiện tiên quyết trong Types
**Khi xử lý lỗi:**
- Validate tại ranh giới hệ thống
- Sử dụng guards cho điều kiện tiên quyết
- Lỗi nhanh với thông báo rõ ràng
- Log ngữ cảnh để debug
**Khi cấu hình:**
- Ưu tiên bắt buộc hơn là tùy chọn có mặc định
- Validate tất cả config lúc khởi động
- Làm thất bại việc triển khai nếu config không hợp lệ
- Không cho phép cấu hình một phần
### 3. Công việc Chuẩn hóa (Standardized Work)
Tuân theo các mẫu đã được thiết lập. Tài liệu hóa những gì hiệu quả. Làm cho các thực hành tốt trở nên dễ dàng tuân theo.
#### Nguyên tắc
**Nhất quán hơn là Thông minh:**
- Tuân theo các mẫu của codebase hiện có
- Đừng phát minh lại những vấn đề đã được giải quyết
- Mẫu mới chỉ được dùng nếu tốt hơn đáng kể
- Sự đồng thuận của nhóm về các mẫu mới
**Tài liệu sống cùng code:**
- README cho thiết lập và kiến trúc
- CLAUDE.md cho quy ước lập trình AI
- Comment giải thích "tại sao", không phải "cái gì"
- Ví dụ cho các mẫu phức tạp
**Tự động hóa các tiêu chuẩn:**
- Linters thực thi phong cách (style)
- Type checks thực thi hợp đồng
- Tests xác minh hành vi
- CI/CD thực thi các cổng kiểm soát chất lượng (quality gates)
#### Tuân theo các Mẫu (Patterns)
<Good>
```typescript
// Mẫu codebase hiện tại cho API clients
class UserAPIClient {
async getUser(id: string): Promise<User> {
return this.fetch(`/users/${id}`);
}
}
// Code mới tuân theo cùng một mẫu
class OrderAPIClient {
async getOrder(id: string): Promise<Order> {
return this.fetch(`/orders/${id}`);
}
}
```
Sự nhất quán làm cho codebase dễ dự đoán
</Good>
<Bad>
```typescript
// Mẫu hiện tại sử dụng class
class UserAPIClient { /* ... */ }
// Code mới giới thiệu mẫu khác mà không thảo luận
const getOrder = async (id: string): Promise<Order> => {
// Phá vỡ sự nhất quán "vì tôi thích dùng hàm hơn"
};
```
Sự không nhất quán tạo ra sự nhầm lẫn
</Bad>
#### Các Mẫu Xử lý Lỗi
<Good>
```typescript
// Tiêu chuẩn dự án: Kiểu Result cho các lỗi có thể phục hồi
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
// Tất cả service tuân theo mẫu này
const fetchUser = async (id: string): Promise<Result<User, Error>> => {
try {
const user = await db.users.findById(id);
if (!user) {
return { ok: false, error: new Error('User not found') };
}
return { ok: true, value: user };
} catch (err) {
return { ok: false, error: err as Error };
}
};
// Người gọi sử dụng mẫu nhất quán
const result = await fetchUser('123');
if (!result.ok) {
logger.error('Failed to fetch user', result.error);
return;
}
const user = result.value; // Type-safe!
```
Mẫu tiêu chuẩn trên toàn bộ codebase
</Good>
#### Tiêu chuẩn Tài liệu
<Good>
```typescript
/**
* Thử lại một thao tác bất đồng bộ với exponential backoff.
*
* Why: Các yêu cầu mạng thất bại tạm thời; thử lại giúp cải thiện độ tin cậy
* When to use: Gọi API bên ngoài, thao tác cơ sở dữ liệu
* When not to use: Validation đầu vào người dùng, gọi hàm nội bộ
*
* @example
* const result = await retry(
* () => fetch('https://api.example.com/data'),
* { maxAttempts: 3, baseDelay: 1000 }
* );
*/
const retry = async <T>(
operation: () => Promise<T>,
options: RetryOptions
): Promise<T> => {
// Implementation...
};
```
Tài liệu hóa tại sao, khi nào và làm thế nào
</Good>
#### Trong Thực tế
**Trước khi thêm mẫu mới:**
- Tìm kiếm trong codebase các vấn đề tương tự đã được giải quyết
- Kiểm tra CLAUDE.md cho các quy ước dự án
- Thảo luận với nhóm nếu phá vỡ mẫu cũ
- Cập nhật tài liệu khi giới thiệu mẫu mới
**Khi viết code:**
- Khớp với cấu trúc file hiện có
- Sử dụng cùng quy ước đặt tên
- Tuân theo cùng cách tiếp cận xử lý lỗi
- Import từ cùng vị trí
**Khi review:**
- Kiểm tra tính nhất quán với code hiện có
- Chỉ ra các ví dụ trong codebase
- Đề xuất căn chỉnh với các tiêu chuẩn
- Cập nhật CLAUDE.md nếu có tiêu chuẩn mới xuất hiện
### 4. Just-In-Time (JIT - Vừa đủ, Đúng lúc)
Xây dựng những gì cần thiết ngay bây giờ. Không hơn, không kém. Tránh tối ưu hóa sớm và kỹ thuật quá mức (over-engineering).
#### Nguyên tắc
**YAGNI (You Aren't Gonna Need It - Bạn sẽ không cần nó đâu):**
- Chỉ triển khai các yêu cầu hiện tại
- Không có tính năng "phòng khi cần"
- Không có code "chúng ta có thể cần cái này sau này"
- Xóa bỏ sự suy đoán
**Thứ đơn giản nhất có thể hoạt động:**
- Bắt đầu với giải pháp đơn giản, trực tiếp
- Chỉ thêm độ phức tạp khi cần thiết
- Refactor khi yêu cầu thay đổi
- Đừng đoán trước nhu cầu tương lai
**Tối ưu hóa khi đã đo lường:**
- Không tối ưu hóa sớm
- Đo đạc (profile) trước khi tối ưu
- Đo lường tác động của thay đổi
- Chấp nhận hiệu suất "đủ tốt"
#### YAGNI trong Hành động
<Good>
```typescript
// Yêu cầu hiện tại: Log lỗi ra console
const logError = (error: Error) => {
console.error(error.message);
};
```
Đơn giản, đáp ứng nhu cầu hiện tại
</Good>
<Bad>
```typescript
// Kỹ thuật quá mức cho "nhu cầu tương lai"
interface LogTransport {
write(level: LogLevel, message: string, meta?: LogMetadata): Promise<void>;
}
class ConsoleTransport implements LogTransport { /*... */ }
class FileTransport implements LogTransport { /* ... */ }
class RemoteTransport implements LogTransport { /* ...*/ }
class Logger {
private transports: LogTransport[] = [];
private queue: LogEntry[] = [];
private rateLimiter: RateLimiter;
private formatter: LogFormatter;
// 200 dòng code cho "có lẽ chúng ta sẽ cần nó"
}
const logError = (error: Error) => {
Logger.getInstance().log('error', error.message);
};
```
Xây dựng cho các yêu cầu tưởng tượng trong tương lai
</Bad>
**Khi nào nên thêm độ phức tạp:**
- Yêu cầu hiện tại đòi hỏi nó
- Điểm đau (pain points) được xác định qua quá trình sử dụng
- Các vấn đề hiệu suất đã được đo lường
- Nhiều trường hợp sử dụng xuất hiện
<Good>
```typescript
// Bắt đầu đơn giản
const formatCurrency = (amount: number): string => {
return `$${amount.toFixed(2)}`;
};
// Yêu cầu phát triển: hỗ trợ nhiều loại tiền tệ
const formatCurrency = (amount: number, currency: string): string => {
const symbols = { USD: '$', EUR: '€', GBP: '£' };
return `${symbols[currency]}${amount.toFixed(2)}`;
};
// Yêu cầu phát triển: hỗ trợ bản địa hóa (localization)
const formatCurrency = (amount: number, locale: string): string => {
return new Intl.NumberFormat(locale, {
style: 'currency',
currency: locale === 'en-US' ? 'USD' : 'EUR',
}).format(amount);
};
```
Độ phức tạp chỉ được thêm vào khi cần
</Good>
#### Trừu tượng hóa Sớm (Premature Abstraction)
<Bad>
```typescript
// Một trường hợp sử dụng, nhưng xây dựng framework chung chung
abstract class BaseCRUDService<T> {
abstract getAll(): Promise<T[]>;
abstract getById(id: string): Promise<T>;
abstract create(data: Partial<T>): Promise<T>;
abstract update(id: string, data: Partial<T>): Promise<T>;
abstract delete(id: string): Promise<void>;
}
class GenericRepository<T> { /* 300 dòng */ }
class QueryBuilder<T> { /* 200 dòng */ }
// ... xây dựng toàn bộ ORM cho một bảng duy nhất
```
Trừu tượng hóa khổng lồ cho tương lai không chắc chắn
</Bad>
<Good>
```typescript
// Các hàm đơn giản cho nhu cầu hiện tại
const getUsers = async (): Promise<User[]> => {
return db.query('SELECT * FROM users');
};
const getUserById = async (id: string): Promise<User | null> => {
return db.query('SELECT * FROM users WHERE id = $1', [id]);
};
// Khi mẫu xuất hiện trên nhiều thực thể, thì mới trừu tượng hóa
```
Chỉ trừu tượng hóa khi mẫu đã được chứng minh qua 3+ trường hợp
</Good>
#### Tối ưu hóa Hiệu suất
<Good>
```typescript
// Hiện tại: Tiếp cận đơn giản
const filterActiveUsers = (users: User[]): User[] => {
return users.filter(user => user.isActive);
};
// Benchmark cho thấy: 50ms cho 1000 user (chấp nhận được)
// ✓ Ship nó, không cần tối ưu
// Sau này: Sau khi profiling cho thấy đây là nút thắt cổ chai
// Thì mới tối ưu với tìm kiếm index hoặc caching
```
Tối ưu hóa dựa trên đo lường, không phải giả định
</Good>
<Bad>
```typescript
// Tối ưu hóa sớm
const filterActiveUsers = (users: User[]): User[] => {
// "Cái này có thể chậm, nên hãy cache và index"
const cache = new WeakMap();
const indexed = buildBTreeIndex(users, 'isActive');
// 100 dòng code tối ưu
// Thêm độ phức tạp, khó bảo trì hơn
// Không có bằng chứng là nó cần thiết
};
```
Giải pháp phức tạp cho vấn đề chưa được đo lường
</Bad>
#### Trong Thực tế
**Khi triển khai:**
- Giải quyết vấn đề trước mắt
- Sử dụng cách tiếp cận thẳng thắn
- Chống lại suy nghĩ "nếu như" (what if)
- Xóa code suy đoán
**Khi tối ưu:**
- Profile trước, tối ưu sau
- Đo trước và sau
- Tài liệu hóa lý do cần tối ưu
- Giữ phiên bản đơn giản trong tests
**Khi trừu tượng hóa:**
- Đợi cho đến khi có 3+ trường hợp tương tự (Quy tắc số 3)
- Làm cho sự trừu tượng hóa đơn giản nhất có thể
- Thà lặp code còn hơn trừu tượng hóa sai
- Refactor khi mẫu đã rõ ràng
## Tích hợp với các Lệnh
Skill Kaizen hướng dẫn cách bạn làm việc. Các lệnh cung cấp phân tích có cấu trúc:
- **`/why`**: Phân tích nguyên nhân gốc rễ (5 Whys)
- **`/cause-and-effect`**: Phân tích đa yếu tố (Biểu đồ Xương cá)
- **`/plan-do-check-act`**: Các chu trình cải tiến lặp lại
- **`/analyse-problem`**: Tài liệu hóa toàn diện (A3)
- **`/analyse`**: Lựa chọn phương pháp thông minh (Gemba/VSM/Muda)
Sử dụng các lệnh cho việc giải quyết vấn đề có cấu trúc. Áp dụng skill cho việc phát triển hàng ngày.
## Cờ Đỏ (Red Flags)
**Vi phạm Cải tiến Liên tục:**
- "Tôi sẽ refactor nó sau" (không bao giờ xảy ra)
- Để lại code tệ hơn lúc bạn tìm thấy nó
- Viết lại kiểu "big bang" thay vì gia tăng từng chút một
**Vi phạm Poka-Yoke:**
- "Người dùng chỉ cần cẩn thận là được"
- Validation sau khi sử dụng thay vì trước đó
- Config tùy chọn mà không có validation
**Vi phạm Công việc Chuẩn hóa:**
- "Tôi thích làm theo cách của mình hơn"
- Không kiểm tra các mẫu hiện có
- Phớt lờ các quy ước dự án
**Vi phạm Just-In-Time:**
- "Chúng ta có thể cần cái này vào lúc nào đó"
- Xây dựng frameworks trước khi sử dụng chúng
- Tối ưu hóa mà không đo lường
## Hãy nhớ
**Kaizen là về:**
- Cải tiến nhỏ liên tục
- Ngăn ngừa lỗi bằng thiết kế
- Tuân theo các mẫu đã được kiểm chứng
- Chỉ xây dựng những gì cần thiết
**Không phải là về:**
- Hoàn hảo ngay lần thử đầu tiên
- Các dự án refactoring khổng lồ
- Các sự trừu tượng hóa thông minh (clever)
- Tối ưu hóa sớm
**Tư duy:** Đủ tốt cho hôm nay, tốt hơn vào ngày mai. Lặp lại.

44
docs/vietnamese/skills/lint-and-validate/SKILL.md Normal file
View File

@@ -0,0 +1,44 @@
---
name: lint-and-validate
description: "Quy trình kiểm soát chất lượng tự động, linting và phân tích tĩnh. Sử dụng sau mỗi lần sửa đổi code để đảm bảo tính đúng đắn của cú pháp và các tiêu chuẩn dự án. Kích hoạt với từ khóa: lint, format, check, validate, types, static analysis."
allowed-tools: Read, Glob, Grep, Bash
---
# Kỹ năng Kiểm tra lỗi và Xác thực (Lint and Validate)
> **BẮT BUỘC:** Chạy các công cụ xác thực phù hợp sau MỖI lần thay đổi code. Không được hoàn thành tác vụ cho đến khi code không còn lỗi.
### Quy trình theo Hệ sinh thái
#### Node.js / TypeScript
1. **Lint/Sửa lỗi:** `npm run lint` hoặc `npx eslint "đường_dẫn" --fix`
2. **Kiểu dữ liệu (Types):** `npx tsc --noEmit`
3. **Bảo mật:** `npm audit --audit-level=high`
#### Python
1. **Linter (Ruff):** `ruff check "đường_dẫn" --fix` (Nhanh & Hiện đại)
2. **Bảo mật (Bandit):** `bandit -r "đường_dẫn" -ll`
3. **Kiểu dữ liệu (MyPy):** `mypy "đường_dẫn"`
## Vòng lặp Chất lượng
1. **Viết/Sửa Code**
2. **Chạy Kiểm tra (Audit):** `npm run lint && npx tsc --noEmit`
3. **Phân tích Báo cáo:** Kiểm tra phần "BÁO CÁO KIỂM TRA CUỐI CÙNG" (FINAL AUDIT REPORT).
4. **Sửa & Lặp lại:** Việc gửi code có lỗi trong "KIỂM TRA CUỐI CÙNG" là KHÔNG được phép.
## Xử lý Lỗi
- Nếu `lint` thất bại: Sửa ngay các lỗi về phong cách (style) hoặc cú pháp.
- Nếu `tsc` thất bại: Sửa các lỗi không khớp kiểu dữ liệu trước khi tiếp tục.
- Nếu không có công cụ nào được cấu hình: Kiểm tra thư mục gốc dự án xem có `.eslintrc`, `tsconfig.json`, `pyproject.toml` không và đề xuất tạo mới.
---
**Quy tắc Nghiêm ngặt:** Không được commit hoặc báo cáo code là "hoàn thành" nếu chưa vượt qua các kiểm tra này.
---
## Scripts
| Script | Mục đích | Lệnh |
|--------|---------|---------|
| `scripts/lint_runner.py` | Kiểm tra lint hợp nhất | `python scripts/lint_runner.py <project_path>` |
| `scripts/type_coverage.py` | Phân tích độ bao phủ kiểu dữ liệu | `python scripts/type_coverage.py <project_path>` |

209
docs/vietnamese/skills/senior-architect/SKILL.md Normal file
View File

@@ -0,0 +1,209 @@
---
name: senior-architect
description: Kỹ năng kiến trúc phần mềm toàn diện để thiết kế các hệ thống có khả năng mở rộng, dễ bảo trì sử dụng ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin, Flutter, Postgres, GraphQL, Go, Python. Bao gồm tạo sơ đồ kiến trúc, các mẫu thiết kế hệ thống, khung quyết định về tech stack và phân tích phụ thuộc. Sử dụng khi thiết kế kiến trúc hệ thống, đưa ra các quyết định kỹ thuật, tạo sơ đồ kiến trúc, đánh giá sự đánh đổi hoặc xác định các mẫu tích hợp.
---
# Kiến trúc sư Cao cấp (Senior Architect)
Bộ công cụ hoàn chỉnh cho kiến trúc sư cao cấp với các công cụ hiện đại và thực hành tốt nhất.
## Khởi động Nhanh
### Các Khả năng Chính
Kỹ năng này cung cấp ba khả năng cốt lõi thông qua các script tự động:
```bash
# Script 1: Trình tạo Sơ đồ Kiến trúc
python scripts/architecture_diagram_generator.py [options]
# Script 2: Kiến trúc sư Dự án
python scripts/project_architect.py [options]
# Script 3: Bộ phân tích Phụ thuộc
python scripts/dependency_analyzer.py [options]
```
## Các Khả năng Cốt lõi
### 1. Trình tạo Sơ đồ Kiến trúc (Architecture Diagram Generator)
Công cụ tự động cho các tác vụ tạo sơ đồ kiến trúc.
**Tính năng:**
- Dựng khung (scaffolding) tự động
- Tích hợp sẵn thực hành tốt nhất
- Mẫu có thể cấu hình
- Kiểm tra chất lượng
**Cách dùng:**
```bash
python scripts/architecture_diagram_generator.py <project-path> [options]
```
### 2. Kiến trúc sư Dự án (Project Architect)
Công cụ phân tích và tối ưu hóa toàn diện.
**Tính năng:**
- Phân tích sâu
- Chỉ số hiệu năng
- Đề xuất
- Tự động sửa lỗi
**Cách dùng:**
```bash
python scripts/project_architect.py <target-path> [--verbose]
```
### 3. Bộ phân tích Phụ thuộc (Dependency Analyzer)
Công cụ nâng cao cho các tác vụ chuyên biệt.
**Tính năng:**
- Tự động hóa cấp độ chuyên gia
- Cấu hình tùy chỉnh
- Sẵn sàng tích hợp
- Đầu ra chuẩn production
**Cách dùng:**
```bash
python scripts/dependency_analyzer.py [arguments] [options]
```
## Tài liệu Tham khảo
### Các Mẫu Kiến trúc
Hướng dẫn toàn diện có sẵn tại `references/architecture_patterns.md`:
- Các mẫu và cách thực hành chi tiết
- Ví dụ code
- Thực hành tốt nhất
- Các anti-patterns cần tránh
- Các kịch bản thực tế
### Quy trình Thiết kế Hệ thống
Tài liệu quy trình hoàn chỉnh tại `references/system_design_workflows.md`:
- Quy trình từng bước
- Chiến lược tối ưu hóa
- Tích hợp công cụ
- Tinh chỉnh hiệu năng
- Hướng dẫn khắc phục sự cố
### Hướng dẫn Quyết định Kỹ thuật
Hướng dẫn tham chiếu kỹ thuật tại `references/tech_decision_guide.md`:
- Chi tiết về tech stack
- Ví dụ cấu hình
- Các mẫu tích hợp
- Các cân nhắc về bảo mật
- Hướng dẫn về khả năng mở rộng
## Tech Stack
**Ngôn ngữ:** TypeScript, JavaScript, Python, Go, Swift, Kotlin
**Frontend:** React, Next.js, React Native, Flutter
**Backend:** Node.js, Express, GraphQL, REST APIs
**Cơ sở dữ liệu:** PostgreSQL, Prisma, NeonDB, Supabase
**DevOps:** Docker, Kubernetes, Terraform, GitHub Actions, CircleCI
**Cloud:** AWS, GCP, Azure
## Quy trình Phát triển
### 1. Thiết lập và Cấu hình
```bash
# Cài đặt dependencies
npm install
# hoặc
pip install -r requirements.txt
# Cấu hình môi trường
cp .env.example .env
```
### 2. Chạy Kiểm tra Chất lượng
```bash
# Sử dụng script phân tích
python scripts/project_architect.py .
# Xem xét các đề xuất
# Áp dụng các bản sửa lỗi
```
### 3. Triển khai Thực hành Tốt nhất
Tuân theo các mẫu và thực hành được tài liệu hóa trong:
- `references/architecture_patterns.md`
- `references/system_design_workflows.md`
- `references/tech_decision_guide.md`
## Tóm tắt Thực hành Tốt nhất
### Chất lượng Code
- Tuân theo các mẫu đã được thiết lập
- Viết bài kiểm tra toàn diện
- Tài liệu hóa các quyết định
- Review thường xuyên
### Hiệu năng
- Đo lường trước khi tối ưu hóa
- Sử dụng bộ nhớ đệm (caching) phù hợp
- Tối ưu hóa các đường dẫn quan trọng (critical paths)
- Giám sát trên production
### Bảo mật
- Validate tất cả đầu vào
- Sử dụng parameterized queries
- Triển khai xác thực (authentication) đúng cách
- Giữ các dependencies luôn cập nhật
### Khả năng Bảo trì
- Viết code rõ ràng
- Sử dụng cách đặt tên nhất quán
- Thêm comment hữu ích
- Giữ cho mọi thứ đơn giản
## Các Lệnh Phổ biến
```bash
# Phát triển
npm run dev
npm run build
npm run test
npm run lint
# Phân tích
python scripts/project_architect.py .
python scripts/dependency_analyzer.py --analyze
# Triển khai
docker build -t app:latest .
docker-compose up -d
kubectl apply -f k8s/
```
## Khắc phục Sự cố
### Các Vấn đề Phổ biến
Kiểm tra phần khắc phục sự cố toàn diện trong `references/tech_decision_guide.md`.
### Nhận Trợ giúp
- Xem lại tài liệu tham khảo
- Kiểm tra thông báo đầu ra của script
- Tham khảo tài liệu của tech stack
- Xem lại nhật ký lỗi (error logs)
## Tài nguyên
- Tham chiếu Mẫu: `references/architecture_patterns.md`
- Hướng dẫn Quy trình: `references/system_design_workflows.md`
- Hướng dẫn Kỹ thuật: `references/tech_decision_guide.md`
- Tool Scripts: Thư mục `scripts/`