Skip to main content

​
VTS Skills

Trang này hướng dẫn người dùng (BA và các vai trò liên quan) sử dụng bộ VTS Skills để tạo tài liệu chuẩn Viettel bằng các công cụ AI như Claude, Codex, Antigravity, Cursor. VTS Skills không chỉ dành riêng cho tài liệu thiết kế chi tiết — một số skill có thể tái sử dụng cho nhiều loại tài liệu khác nhau tùy theo mục đích (như drawio, docx) và sẽ còn tiếp tục mở rộng trong tương lai. Bộ skill bao gồm cả các skill dùng chung lẫn các skill dùng riêng đặc thù cho từng loại tài liệu.

​
1. Đối tượng sử dụng

  • Business Analyst (BA) — người soạn thảo và sở hữu nội dung tài liệu.
  • Quản lý dự án — người rà soát cấu trúc và chất lượng tài liệu đầu ra.

​
2. Lõi của file DOCX là gì?

Word .docx thực chất là một thư mục nén dạng ZIP chứa các file XML và hình ảnh. Khi giải nén, cấu trúc chính bao gồm:
  • document.xml: Chứa toàn bộ chữ, bảng đặc tả và bố cục của tài liệu.
  • styles.xml: Lưu thông tin định dạng (font chữ, cỡ chữ, màu sắc, tiêu đề Heading).
  • media/: Thư mục lưu hình ảnh đính kèm (ảnh chụp màn hình, sơ đồ quy trình).
  • comments.xml: Nơi lưu trữ các nhận xét (comment) của người dùng.
VTS Skills hoạt động thế nào? AI tự động giải nén, đọc/ghi thông tin trực tiếp vào các file XML này để chèn nội dung, định dạng văn bản hoặc thêm bình luận, sau đó đóng gói lại thành file .docx hoàn chỉnh mà không làm hỏng file.

​
3. Công cụ AI trong hệ thống

Hiểu một cách đơn giản, Claude, Codex, Antigravity và Cursor đều là những “người soạn thảo” sử dụng các Skill để chuyển hóa yêu cầu của bạn thành văn bản Word theo yêu cầu.

Claude

Tải bản dành cho máy tính tại claude.ai/download.

Codex (ChatGPT)

Tải bản dành cho máy tính tại chatgpt.com/download.

Antigravity

Tải bản dành cho máy tính tại antigravity.google.

Cursor

Tải bản dành cho máy tính tại cursor.com.

​
4. Khái niệm “Skill” là gì?

Trong Agentic AI, Skill (Kỹ năng) là một bộ công cụ và chỉ dẫn được đóng gói sẵn để giải quyết một tác vụ cụ thể:
  • Chỉ dẫn nghiệp vụ: AI phải viết theo văn phong nào, dùng từ ngữ gì.
  • Tài liệu tham khảo: Các template mẫu, quy chuẩn viết tài liệu.
  • Công cụ tự động hóa: Các đoạn mã giúp AI tự động tính toán, vẽ sơ đồ.
Cài đặt Skill: Project hay Global? Mỗi Skill là một thư mục chứa file SKILL.md (chỉ dẫn) và các tài nguyên đi kèm. Có hai phạm vi cài đặt:
  • Project (theo dự án): Chỉ áp dụng cho dự án đó.
  • Global (toàn máy): Áp dụng cho mọi dự án trên máy tính cá nhân.
SKILL.md là chuẩn dùng chung — một skill viết cho Claude có thể dùng lại ở các công cụ khác mà không cần sửa. Chỉ khác nhau ở thư mục đặt skill:
Công cụCài Project (trong dự án)Cài Global (Home máy người dùng)
Claude.claude/skills/<tên-skill>/~/.claude/skills/<tên-skill>/
Codex.agents/skills/<tên-skill>/~/.codex/skills/<tên-skill>/
Antigravity.agent/skills/<tên-skill>/~/.gemini/antigravity/skills/<tên-skill>/
Cursor.cursor/skills/<tên-skill>/~/.cursor/skills/<tên-skill>/
Mẹo đặt một lần dùng cho nhiều tool: nhiều công cụ còn cùng đọc thư mục trung lập .agents/skills/ (project) và ~/.agents/skills/ (global), nên đặt skill ở đây là khỏi chép vào từng thư mục riêng. Riêng Cursor còn tự đọc luôn thư mục của Claude/Codex.
Cách mention (gọi) Skill cho từng công cụ AI sẽ tự kích hoạt skill khi yêu cầu của bạn khớp mô tả skill. Để chắc chắn Agent gọi đúng skill, hãy gọi tên skill trực tiếp trong prompt:
Công cụCách gọi skill thủ công
ClaudeGõ /tên-skill (ví dụ /docx)
CodexGõ $tên-skill (ví dụ $docx)
AntigravityNhắc tên skill trong prompt (skill tự kích hoạt theo mô tả)
CursorNhắc tên skill trong prompt (skill tự kích hoạt theo mô tả)
Ở Codex và Cursor, ký tự @ dùng để chèn file làm ngữ cảnh, không phải để gọi skill.

​
5. Bộ VTS Skills giải quyết việc gì?

Bộ skill gồm hai nhóm: skill dùng chung (tái sử dụng cho nhiều loại tài liệu) và skill TKCT chuyên dụng (đặc thù cho tài liệu thiết kế chi tiết). Skill dùng chung
  1. docx: Thao tác trực tiếp lõi XML của file Word (document.xml, styles.xml, comments.xml, thư mục media/) để chỉnh sửa, định dạng và đóng gói thành .docx. Đọc được mọi file Word và viết nội dung mới kế thừa đúng style của file đó.
  2. drawio: Tạo, chỉnh sửa, xuất sơ đồ Draw.io qua quy trình YAML offline. Xuất ra ảnh để chèn tài liệu hoặc file .drawio để chỉnh tay.
Skill TKCT chuyên dụng
tkct-document-builder là skill trung tâm của bộ TKCT. Trong phần lớn trường hợp, người làm thiết kế chi tiết chỉ cần gọi duy nhất skill này; nó sẽ tự điều phối và lần lượt kích hoạt các skill thành phần phù hợp, nên không cần chỉ định thủ công từng skill bên dưới.
  1. tkct-document-builder: Đóng vai trò điều phối toàn bộ quy trình sinh tài liệu — thu thập metadata, khởi tạo tài liệu từ file Word mẫu (style donor) để kế thừa định dạng chuẩn, sau đó lần lượt gọi các skill thành phần để hoàn thiện tài liệu.
  2. tkct-section-assembler: Dựng cấu trúc chi tiết cho từng màn hình chức năng theo 4 mục chuẩn (Thông tin chung, Thiết kế màn hình, Mô tả chi tiết thành phần, Luồng nghiệp vụ), đảm bảo nhất quán giữa các màn hình.
  3. tkct-style-guide: Tự động áp quy chuẩn định dạng Viettel (font Arial, cỡ chữ theo cấp heading, khoảng cách dòng, căn lề, màu chủ đạo, đánh số mục) để tài liệu luôn chuyên nghiệp, đồng bộ.
  4. tkct-field-table-generator: Từ danh sách trường hoặc mô tả giao diện thô, tự sinh bảng đặc tả chuẩn 6 cột (STT, Tên trường, Kiểu hiển thị, Input/Output, Giá trị mặc định, Mô tả nghiệp vụ & Mapping CSDL).
  5. tkct-data-governance: Phân tích schema bảng, khóa ngoại và ràng buộc dữ liệu để sinh phần đặc tả quản trị dữ liệu.
  6. tkct-workflow-writer: Mô tả chi tiết các luồng xử lý (happy path, rẽ nhánh, xử lý lỗi) cho các tác vụ Thêm/Sửa/Xóa/Phê duyệt,…
  7. tkct-flowchart-generator: Chuyển mô tả luồng nghiệp vụ dạng văn bản thành lưu đồ (Flowchart) rồi biên dịch ra ảnh, chèn vào đúng mục trong tài liệu Word.
  8. tkct-context-diagram: Vẽ sơ đồ ngữ cảnh (Context Diagram) trực quan hóa tương tác giữa Actor, UI Frontend, Backend API và Database để dễ hình dung kiến trúc chức năng.
  9. tkct-output-validator: Trước khi xuất .docx, tự rà soát toàn bộ tài liệu để phát hiện lỗi phổ biến (thiếu mục bắt buộc, bảng sai số cột/thiếu thông tin, sai style, liên kết sơ đồ lỗi).

​
6. Quy trình sử dụng cơ bản

1

Cài đặt công cụ AI và tải Skills

Cài đặt một trong các công cụ AI (Claude, Codex, Antigravity, Cursor) theo hướng dẫn ở mục 3. Sau đó tải bộ Skill vts-skills.zip từ Google Drive.Nếu muốn thử nghiệm, tải thêm PTYC.zip và TKCT.zip trong cùng folder Google Drive.
2

Cài đặt Skills vào máy

Mở terminal ngay trong thư mục chứa file vts-skills.zip vừa tải về (thường là Downloads), vì lệnh bên dưới tìm file zip ở thư mục hiện tại của terminal — mở ở chỗ khác sẽ báo không thấy file.
  • Windows: mở File Explorer tới thư mục chứa file zip, gõ powershell vào thanh địa chỉ rồi Enter.
  • Mac: chuột phải vào thư mục trong Finder → Dịch vụ (Services) → New Terminal at Folder. Hoặc gõ cd trong Terminal rồi kéo thả thư mục vào và Enter.
Giải nén và chạy lệnh cài đặt khớp với hệ điều hành của bạn — các skill sẽ được copy vào ~/.agents/skills (thư mục trung lập mà nhiều công cụ cùng đọc, xem mục 4):
unzip -o vts-skills.zip -d vts-skills && sh vts-skills/install.sh
Muốn cài vào thư mục khác (ví dụ chỉ cho Claude), đặt biến SKILLS_DEST trước khi chạy:
SKILLS_DEST=~/.claude/skills sh vts-skills/install.sh
Xong. Mở lại agent là dùng được các skill.
3

Chuẩn bị đầu vào

Tạo một thư mục đầu vào theo đúng cấu trúc của 2 bộ thử nghiệm PTYC.zip và TKCT.zip (tải ở Bước 1). Mỗi bộ là một thư mục gồm các file sau:
TKCT/                    # thư mục đầu vào của bạn
├── prompt.rtf           # nội dung prompt ra lệnh cho AI
├── rules.txt            # (tùy chọn) luật ghi đè mặc định của skill
├── template.docx        # file Word mẫu (style donor) để kế thừa định dạng
├── template.drawio      # sơ đồ mẫu để AI tham khảo
├── screens/             # ảnh chụp màn hình các chức năng
│   ├── DanhSachPhongBan.png
│   ├── ThemMoiPhongBan.png
│   ├── SuaPhongBan.png
│   └── XoaPhongBan.png
└── env                  # thông tin kết nối CSDL để AI tự đọc schema
Giải nén PTYC.zip hoặc TKCT.zip để xem mẫu thật, rồi thay template.docx, ảnh trong screens/ và nội dung prompt.rtf bằng dữ liệu của bạn. File env chỉ cần khi muốn AI kết nối CSDL để lấy danh sách trường (như bộ TKCT); nếu không, mô tả trực tiếp danh sách trường trong prompt (như bộ PTYC).
prompt.rtf chỉ là định dạng văn bản thường thấy của trình soạn thảo (TextEdit trên Mac) — trên Windows bạn có thể tạo file .txt bằng Notepad cũng được, nội dung như nhau. File này chứa prompt mẫu: bạn mở ra, tinh chỉnh (find-tune) lại cho khớp dữ liệu của mình, rồi copy và dán vào khung chat của công cụ AI để ra lệnh.
rules.txt (hoặc rules.rtf) là file luật ghi đè tùy chọn. Bộ TKCT Skills có sẵn một số quy chuẩn mặc định (ví dụ font Arial), nhưng đôi khi template.docx của bạn lại dùng font khác (ví dụ Times New Roman). Khi đó, ghi luật riêng vào rules.txt, rồi trong prompt nhắc AI “follow rules.txt trước” — AI sẽ ưu tiên luật của bạn thay vì mặc định của skill.
4

Mở project trong Codex và kiểm tra Skills

Mở thư mục đầu vào (chuẩn bị ở Bước 3) như một project trong Codex, rồi xác nhận bộ Skill đã được cài đặt thành công.
  1. Ở mục Projects, bấm icon tạo project mới ở góc phải.
    Mục Projects trong Codex
  2. Chọn Use an existing folder.
    Chọn Use an existing folder
  3. Trỏ tới thư mục đầu vào bạn vừa chuẩn bị (ví dụ TKCT) rồi bấm Open.
    Chọn thư mục đầu vào
  4. Codex mở project, sẵn sàng nhận lệnh trong khung chat.
    Khung chat của project trong Codex
  5. Gõ $tkct vào khung chat. Nếu hiện ra danh sách các skill (Tkct Style Guide, Tkct Document Builder, Tkct Output Validator…) nghĩa là bộ Skill đã cài thành công. Nếu không thấy gì, kiểm tra lại Bước 2.
    Danh sách TKCT Skills hiện ra khi gõ $tkct
Codex chỉ quét thư mục skill khi khởi động. Nếu gõ $tkct mà danh sách chưa xuất hiện, hãy khởi động lại Codex để hệ thống nạp lại các skill vừa cài, sau đó kiểm tra lại.
5

Ra lệnh cho AI

Ngay trong khung chat của project Codex vừa mở ở Bước trước, mở prompt.rtf để tinh chỉnh prompt cho khớp dữ liệu của bạn, rồi dán vào khung chat. Trong prompt nhớ mention các skill cần dùng (Docx, Drawio, Tkct Document Builder…) và đính kèm các file liên quan (template.docx, template.drawio). Gửi lệnh và chờ AI xử lý.
Dán prompt kèm skill và file vào khung chat Codex
6

Nhận và kiểm tra file .docx

AI sinh ra file Word hoàn chỉnh (ví dụ template_..._updated.docx) cùng các script tạo tài liệu. tkct-output-validator tự rà soát trước khi xuất.
Kết quả AI trả về: file .docx và script sinh tài liệu
Bấm Open in để mở file .docx, đối chiếu nội dung và định dạng với yêu cầu. Nếu cần chỉnh, mô tả thay đổi ngay trong cùng khung chat để AI sinh lại.

​
7. Demo: 4 kịch bản sử dụng

Bạn có thể dùng các file mẫu prompt để ra lệnh cho AI sinh tài liệu theo nhu cầu.
  • Khi nào dùng: Cần tạo mới toàn bộ tài liệu TKCT cho một phân hệ từ con số 0.
  • Cách dùng: Điền thông tin chung (tên tài liệu, phân hệ, giới thiệu dự án, danh sách các đối tượng dữ liệu). AI sẽ tự động sinh toàn bộ trang bìa, changelog, trang ký tên và tất cả các mục chức năng chi tiết trong một file Word duy nhất.
# Tài liệu TKCT hoàn chỉnh (3 đối tượng, field do BA cung cấp)

## Prompt

Tôi cần tạo tài liệu TKCT hoàn chỉnh, hãy sử dụng [Docx] + [Tkct Document Builder] và tất cả các skill liên quan đến thiết kế chi tiết để tạo tài liệu với các thông tin sau:

### Thông tin tài liệu

| Trường          | Giá trị                                                              |
| --------------- | -------------------------------------------------------------------- |
| Tên tài liệu    | Phần mềm CSDL Nền tảng về kết cấu hạ tầng giao thông của Bộ Xây dựng |
| Mã tài liệu     | TKCT_GPCP_CQDT_BXD_CSDLNT_250611_v1.0                                |
| Phiên bản       | 1.0                                                                  |
| Ngày tạo        | 14/01/2026                                                           |
| Đơn vị          | Tổng Công ty Giải pháp Doanh nghiệp Viettel                          |
| Người lập       | Nguyễn Văn A                                                         |
| Người xem xét 1 | Trần Thị B                                                           |
| Người xem xét 2 | Lê Văn C                                                             |
| Người phê duyệt | Phạm Thị D                                                           |

### Phân hệ

| Trường           | Giá trị                             |
| ---------------- | ----------------------------------- |
| Tên phân hệ      | Phân hệ Biên tập, chỉnh lý dữ liệu  |
| Menu gốc         | Biên tập, chỉnh lý dữ liệu Đường bộ |
| Vai trò mặc định | Cán bộ quản lý                      |

### Danh sách đối tượng dữ liệu

Mỗi dòng = một đối tượng cần tạo section Sửa + Xóa:

| STT | Tên đối tượng  | Tên bảng DB    | Menu con       | Bảng lookup                            |
| --- | -------------- | -------------- | -------------- | -------------------------------------- |
| 1   | Tuyến đường bộ | T_TuyenDuongBo | Tuyến đường bộ | T_LoaiDuong, T_TinhThanh               |
| 2   | Cầu đường bộ   | T_CauDuongBo   | Cầu đường bộ   | T_LoaiCau, T_TinhThanh, T_TuyenDuongBo |
| 3   | Hầm đường bộ   | T_HamDuongBo   | Hầm đường bộ   | T_LoaiHam, T_TinhThanh, T_TuyenDuongBo |

### Danh sách trường cho từng đối tượng

#### Tuyến đường bộ

| STT | Tên trường       | Tên hiển thị         | Kiểu dữ liệu      | Bắt buộc | Lookup table |
| --- | ---------------- | -------------------- | ----------------- | -------- | ------------ |
| 1   | MaTuyenDuongBo   | Mã tuyến đường bộ    | Textbox           | Y        | —            |
| 2   | TenTuyenDuongBo  | Tên tuyến đường bộ   | Textbox           | Y        | —            |
| 3   | LoaiDuongId      | Loại đường           | Combobox          | Y        | T_LoaiDuong  |
| 4   | TinhThanhId      | Tỉnh/Thành           | Combobox          | Y        | T_TinhThanh  |
| 5   | ChieuDai         | Chiều dài (km)       | Textbox (số thực) | N        | —            |
| 6   | NgayDuaVaoSuDung | Ngày đưa vào sử dụng | Datepicker        | N        | —            |

(Cung cấp tương tự cho Cầu đường bộ, Hầm đường bộ.)

### Lịch sử thay đổi

| Phiên bản | Ngày       | Loại | Mô tả thay đổi   | Người thực hiện |
| --------- | ---------- | ---- | ---------------- | --------------- |
| 1.0       | 14/01/2026 | A    | Tạo mới tài liệu | Nguyễn Văn A    |

_(A = Tạo mới, M = Sửa đổi, D = Xóa bỏ)_

### Ảnh màn hình

Cung cấp đường dẫn ảnh cho H6 `Màn hình` của từng đối tượng (Sửa + Xóa).

Tạo tài liệu TKCT hoàn chỉnh bao gồm:

1. Trang bìa với đầy đủ thông tin metadata
2. Bảng lịch sử thay đổi (7 cột)
3. Trang chữ ký (4 vai trò)
4. Mục lục placeholder
5. Sơ đồ cho từng đối tượng: sơ đồ ngữ cảnh và lưu đồ quy trình
6. Tất cả sections Sửa + Xóa cho từng đối tượng (Thông tin chung chức năng, Màn hình, Mô tả chi tiết các thành phần, Luồng nghiệp vụ/Luồng dữ liệu)
Demo: Sinh tài liệu TKCT hoàn chỉnh
  • Khi nào dùng: Tài liệu đã có sẵn, bạn chỉ muốn tạo thêm chi tiết cho một đối tượng dữ liệu (gồm cả hai chức năng Sửa và Xóa).
  • Cách dùng: Cung cấp thông tin đối tượng (ví dụ: Bến phà đường bộ) và danh sách trường. AI sẽ tạo đầy đủ sơ đồ ngữ cảnh, sơ đồ quy trình, bảng đặc tả trường UI và các bước nghiệp vụ cho cả 2 chức năng Sửa/Xóa.
# Bến phà đường bộ (1 đối tượng, Sửa + Xóa)

## Prompt

Tôi cần tạo đầy đủ nội dung cho đối tượng dữ liệu **Bến phà đường bộ** trong tài liệu TKCT, bao gồm cả section Sửa và Xóa. Hãy sử dụng [Docx] + [Tkct Document Builder] và tất cả các skill liên quan đến thiết kế chi tiết để bổ sung.

**Thông tin đối tượng:**

- Tên đối tượng: `Bến phà đường bộ`
- Tên bảng DB chính: `T_BenPhaDuongBo`
- Menu điều hướng: `Biên tập, chỉnh lý dữ liệu Đường bộ → Bến phà đường bộ`
- Vai trò người dùng: `Cán bộ quản lý`
- Trường định danh chính: `MaDinhDanh`
- Tên hiển thị định danh: `Mã bến phà đường bộ`
- Tên phân hệ: `Phân hệ Biên tập, chỉnh lý dữ liệu`

**Bảng lookup liên quan:**

- `C_LoaiBenPhaDuongBo` — Loại bến phà đường bộ
- `C_CapKyThuatBenPha` — Cấp kỹ thuật bến phà
- `C_TinhThanh` — Tỉnh/Thành phố
- `C_TinhTrangHoatDong` — Tình trạng hoạt động
- `T_TuyenDuongBo` — Tuyến đường bộ

**Danh sách trường của form Sửa:**

| STT | Tên trường                        | Tên hiển thị         | Kiểu dữ liệu        | Bắt buộc | Lookup table        |
| --- | --------------------------------- | -------------------- | ------------------- | -------- | ------------------- |
| 1   | MaDinhDanh                        | Mã bến phà đường bộ  | Textbox             | Y        | —                   |
| 2   | TenGoi                            | Tên bến phà đường bộ | Textbox             | Y        | —                   |
| 3   | LoaiBenPhaDuongBo.TenMuc          | Loại bến phà         | Combobox            | N        | C_LoaiBenPhaDuongBo |
| 4   | CapKyThuatBenPha.TenMuc           | Cấp kỹ thuật         | Combobox            | N        | C_CapKyThuatBenPha  |
| 5   | DiaPhanHanhChinh.TinhThanh.TenMuc | Tỉnh/Thành phố       | Combobox            | Y        | C_TinhThanh         |
| 6   | TinhTrangHoatDong.TenMuc          | Tình trạng hoạt động | Combobox            | Y        | C_TinhTrangHoatDong |
| 7   | TuyenDuongBo.TenGoi               | Tuyến đường bộ       | Combobox            | N        | T_TuyenDuongBo      |
| 8   | KenhSongDuongThuy                 | Kênh sông đường thủy | Textbox             | N        | —                   |
| 9   | NgayXayDung                       | Ngày xây dựng        | Datepicker          | N        | —                   |
| 10  | NgayKhaiThac                      | Ngày khai thác       | Datepicker          | N        | —                   |
| 11  | SoLuongPhaToiDa                   | Số lượng phà tối đa  | Textbox (số nguyên) | N        | —                   |
| 12  | ChieuDaiBen                       | Chiều dài bến (m)    | Textbox (số thực)   | N        | —                   |

### Ảnh màn hình

- Sửa: `screens/Benphaduongbo-Sua-screen-1.png`, `screens/Benphaduongbo-Sua-screen-2.png`, `screens/Benphaduongbo-Sua-screen-3.png`
- Xóa: `screens/Benphaduongbo-Xoa-screen-1.png`, `screens/Benphaduongbo-Xoa-screen-2.png`

Tạo đầy đủ:

1. **Sơ đồ ngữ cảnh** cho `Bến phà đường bộ` với actor `Cán bộ quản lý` và các thao tác Sửa, Xóa.
2. **Section Sửa** — H5 `Sửa dữ liệu bến phà đường bộ`, 4 H6: Thông tin chung chức năng, Màn hình, Mô tả chi tiết các thành phần (bảng 6 cột), Luồng nghiệp vụ (5 Bước).
3. **Section Xóa** — H5 `Xóa dữ liệu bến phà đường bộ`, 4 H6: Thông tin chung chức năng, Màn hình, Mô tả chi tiết các thành phần (bảng popup 5 dòng), Luồng dữ liệu (4 Bước + flowchart).
Demo: Sinh nội dung cho một đối tượng dữ liệu
  • Khi nào dùng: Chỉ muốn viết thiết kế chi tiết cho một chức năng duy nhất (chỉ riêng Sửa hoặc chỉ riêng Xóa) để bổ sung vào tài liệu.
  • Cách dùng: Khai báo đối tượng và chọn loại thao tác. AI sẽ sinh đúng cấu trúc 4 mục H6 tiêu chuẩn của riêng chức năng đó.
# Sửa Nút giao đường bộ (1 section)

## Prompt

Tôi cần tạo section **Sửa** cho đối tượng dữ liệu **Nút giao đường bộ** trong tài liệu TKCT. Hãy sử dụng [Docx] + [Tkct Document Builder] và tất cả các skill liên quan đến thiết kế chi tiết để bổ sung.

**Thông tin đối tượng:**

- Tên đối tượng: `Nút giao đường bộ`
- Tên bảng DB: `T_NutGiaoDuongBo`
- Menu điều hướng: `Biên tập, chỉnh lý dữ liệu Đường bộ → Nút giao đường bộ`
- Vai trò người dùng: `Cán bộ quản lý`
- Trường định danh: `MaDinhDanh`
- Tên hiển thị định danh: `Mã nút giao đường bộ`
- Loại thao tác: **Sửa**

**Danh sách trường:**

| STT | Tên trường                        | Tên hiển thị            | Kiểu dữ liệu | Bắt buộc | Lookup table        |
| --- | --------------------------------- | ----------------------- | ------------ | -------- | ------------------- |
| 1   | MaDinhDanh                        | Mã nút giao đường bộ    | Textbox      | Y        | —                   |
| 2   | TenGoi                            | Tên nút giao đường bộ   | Textbox      | Y        | —                   |
| 3   | LoaiNutGiao.TenMuc                | Loại nút giao           | Combobox     | N        | C_LoaiNutGiao       |
| 4   | HinhDangNutGiao.TenMuc            | Hình dạng nút giao      | Combobox     | N        | C_HinhDangNutGiao   |
| 5   | DiaPhanHanhChinh.TinhThanh.TenMuc | Tỉnh/Thành phố          | Combobox     | Y        | C_TinhThanh         |
| 6   | TinhTrangHoatDong.TenMuc          | Tình trạng hoạt động    | Combobox     | Y        | C_TinhTrangHoatDong |
| 7   | DenTinHieuGiaoThong               | Đèn tín hiệu giao thông | Checkbox     | N        | —                   |

**Bảng lookup liên quan:** `C_LoaiNutGiao`, `C_HinhDangNutGiao`, `C_TinhThanh`, `C_TinhTrangHoatDong`

### Ảnh màn hình

- Sửa: `screens/Nutgiaoduongbo-Sua-screen-1.png` … `screens/Nutgiaoduongbo-Sua-screen-5.png`

Tạo đầy đủ section này:

1. H5 heading `Sửa dữ liệu nút giao đường bộ` (không numeric prefix)
2. H6 `Thông tin chung chức năng` (vai trò + đường dẫn menu, 2 đoạn)
3. H6 `Màn hình` (placeholder ảnh)
4. H6 `Mô tả chi tiết các thành phần` (bảng 6 cột chuẩn TKCT)
5. H6 `Luồng nghiệp vụ` (5 Bước)
Demo: Sinh một chức năng đơn lẻ
  • Khi nào dùng: Trường hợp bạn không có danh sách trường và không muốn nhập thủ công.
  • Cách dùng: Cung cấp thông tin kết nối CSDL và danh sách các bảng (ví dụ: T_TuyenDuongBo). AI sẽ tự động kết nối vào DB (quyền chỉ đọc), đọc cấu trúc bảng, xác định loại dữ liệu (Textbox, Combobox, Datepicker…) và tự động điền bảng đặc tả trường cho tài liệu.
# Tài liệu TKCT hoàn chỉnh (10 đối tượng, field resolve từ DB)

## Prompt

Tôi cần tạo tài liệu TKCT hoàn chỉnh, hãy sử dụng [Docx] + [Tkct Document Builder] và tất cả các skill liên quan đến thiết kế chi tiết để tạo tài liệu.

### Danh sách đối tượng dữ liệu

| STT | Tên đối tượng                 | Tên bảng DB                | Menu con                      | Bảng lookup   |
| --- | ----------------------------- | -------------------------- | ----------------------------- | ------------- |
| 1   | Tuyến đường bộ                | T_TuyenDuongBo             | Tuyến đường bộ                | Resolve từ DB |
| 2   | Cầu đường bộ                  | T_CauDuongBo               | Cầu đường bộ                  | Resolve từ DB |
| …   | …                             | …                          | …                             | …             |
| 10  | Bến xe đường bộ               | T_BenXeDuongBo             | Bến xe đường bộ               | Resolve từ DB |

### Nguồn schema CSDL

Không cung cấp danh sách trường trong input này. Agent phải tự lấy schema theo tên bảng từ CSDL mẫu:

| Trường             | Giá trị                                        |
| ------------------ | ---------------------------------------------- |
| Loại CSDL          | MySQL 8 Docker                                 |
| File môi trường    | `eval-cases/schema-from-db/mysql/.env`         |
| File schema đầu ra | `resolved-schema.md`                           |
| Danh sách bảng     | `T_TuyenDuongBo`, `T_CauDuongBo`, … (10 bảng)  |

Trước khi sinh tài liệu, agent phải resolve schema CSDL bằng file `.env` và xuất ra `resolved-schema.md`. Nội dung cấu hình kết nối không được paste vào prompt/output; agent chỉ dùng user CSDL chỉ đọc khi truy vấn schema.

Sau đó agent đọc `resolved-schema.md` và dùng các cột/description lấy từ CSDL làm nguồn dữ liệu chuẩn cho:

- Bảng `Mô tả chi tiết các thành phần`
- Mapping `TableName.ColumnName`
- Bảng lookup / D-box trong flowchart
- Luồng nghiệp vụ / Luồng dữ liệu nhắc tới CSDL

### Yêu cầu

- Schema trường cho 10 đối tượng được resolve từ MySQL bằng resolver CSDL trước khi sinh tài liệu.
- Schema resolver dùng user CSDL chỉ đọc lấy từ file môi trường local.
- Bảng mô tả trường giữ nguyên mapping `TableName.ColumnName` (ví dụ `T_TuyenDuongBo.TenGoi`).
- Số lượng trường trong mỗi bảng output khớp với metadata CSDL, không rút gọn.
Demo: Sinh tài liệu tự động từ Cơ sở Dữ liệu

​
8. Xử lý sự cố thường gặp

Gọi tên skill trực tiếp trong prompt theo cú pháp của từng công cụ (/tên-skill cho Claude, $tên-skill cho Codex). Kiểm tra skill đã nằm đúng thư mục Project/Global chưa. Công cụ chỉ quét thư mục skill khi khởi động, nên đôi khi cần tắt và mở lại Codex (hoặc Claude) để hệ thống nạp lại các skill vừa cài.
Đảm bảo có mention docx và tkct-document-builder, và khởi tạo tài liệu từ file Word mẫu (style donor) để kế thừa định dạng chuẩn Viettel.TKCT Skills được xây theo một template chuẩn. Nếu template của bạn khác với template chuẩn, Agent có thể bị nhầm lẫn, dẫn đến kết quả chưa ổn định. Khi đó, hãy trao đổi với Agent để rút ra các quy tắc riêng cho template của bạn và lưu vào rules.txt. Ở những lần sinh tài liệu sau, chủ động mention file rules.txt và yêu cầu Agent ưu tiên các quy tắc đó — dần dần Agent sẽ bám theo đúng phong cách tài liệu của bạn.
Nếu sơ đồ Agent sinh ra chưa căn chỉnh đúng format chuẩn, hãy bỏ file template.drawio (sơ đồ mẫu mà bạn cho là đúng) vào thư mục làm việc, rồi yêu cầu Agent dùng skill drawio phân tích sơ đồ mẫu đó và vẽ lại tương tự. Agent sẽ bám theo bố cục, style và quy ước của file mẫu thay vì tự suy diễn.
Trước tiên, tự kiểm tra máy tính có kết nối được CSDL hay không bằng một công cụ khác (MySQL Workbench, DBeaver, mysql CLI…) với đúng thông tin trong file .env. Nếu các công cụ này cũng không kết nối được thì vấn đề nằm ở mạng/CSDL, không phải ở skill. Đảm bảo dùng user CSDL chỉ đọc và CSDL đang chạy. Không paste thông tin kết nối trực tiếp vào prompt.