> ## Documentation Index
> Fetch the complete documentation index at: https://skillpieces.io/llms.txt
> Use this file to discover all available pages before exploring further.

# VTS Skills

> Hướng dẫn sử dụng bộ VTS Skills để sinh tài liệu bằng AI

# 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.

<Note>
  **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.
</Note>

## 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.

<CardGroup cols={2}>
  <Card title="Claude" icon="robot" href="https://claude.ai/download">
    Tải bản dành cho máy tính tại claude.ai/download.
  </Card>

  <Card title="Codex (ChatGPT)" icon="terminal" href="https://chatgpt.com/download">
    Tải bản dành cho máy tính tại chatgpt.com/download.
  </Card>

  <Card title="Antigravity" icon="rocket" href="https://antigravity.google">
    Tải bản dành cho máy tính tại antigravity.google.
  </Card>

  <Card title="Cursor" icon="code" href="https://cursor.com">
    Tải bản dành cho máy tính tại cursor.com.
  </Card>
</CardGroup>

## 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>/`             |

<Note>
  **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.
</Note>

**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                                     |
| --------------- | ----------------------------------------------------------- |
| **Claude**      | Gõ `/tên-skill` (ví dụ `/docx`)                             |
| **Codex**       | Gõ `$tên-skill` (ví dụ `$docx`)                             |
| **Antigravity** | Nhắc tên skill trong prompt (skill tự kích hoạt theo mô tả) |
| **Cursor**      | Nhắc tên skill trong prompt (skill tự kích hoạt theo mô tả) |

<Note>
  Ở Codex và Cursor, ký tự **`@`** dùng để chèn *file* làm ngữ cảnh, **không
  phải** để gọi skill.
</Note>

## 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**

<Note>
  `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.
</Note>

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

<Steps>
  <Step title="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](#3-công-cụ-ai-trong-hệ-thống). Sau đó tải bộ Skill
    `vts-skills.zip` từ [Google Drive](https://drive.google.com/drive/folders/1T5pgFYdxJzSj08TRWDm23ASMk0H5uvXI?usp=sharing).

    Nếu muốn thử nghiệm, tải thêm `PTYC.zip` và `TKCT.zip` trong cùng folder
    Google Drive.
  </Step>

  <Step title="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.

    <Tip>
      * **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.
    </Tip>

    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):

    <CodeGroup>
      ```bash Mac / Linux theme={null}
      unzip -o vts-skills.zip -d vts-skills && sh vts-skills/install.sh
      ```

      ```powershell Windows (PowerShell) theme={null}
      Expand-Archive -Force vts-skills.zip vts-skills; ./vts-skills/install.ps1
      ```
    </CodeGroup>

    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:

    ```bash theme={null}
    SKILLS_DEST=~/.claude/skills sh vts-skills/install.sh
    ```

    Xong. Mở lại agent là dùng được các skill.
  </Step>

  <Step title="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:

    <Tabs>
      <Tab title="TKCT (có kết nối CSDL)">
        ```text theme={null}
        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
        ```
      </Tab>

      <Tab title="PTYC (không kết nối CSDL)">
        ```text theme={null}
        PTYC/                    # 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
            ├── ClientList.png
            ├── ClientDetail.png
            └── DanhSachPhongBan.png
        ```
      </Tab>
    </Tabs>

    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).

    <Note>
      `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.
    </Note>

    <Note>
      `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.
    </Note>
  </Step>

  <Step title="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.

           <Frame>
             <img src="https://mintcdn.com/solostylist/LNOqt5Bssg2lppqZ/images/vts-skills/codex-verify/open-projects.png?fit=max&auto=format&n=LNOqt5Bssg2lppqZ&q=85&s=837033ceb4c17bd969b3e4ceb1df91d4" alt="Mục Projects trong Codex" width="295" height="114" data-path="images/vts-skills/codex-verify/open-projects.png" />
           </Frame>

    2. Chọn **Use an existing folder**.

           <Frame>
             <img src="https://mintcdn.com/solostylist/LNOqt5Bssg2lppqZ/images/vts-skills/codex-verify/use-existing-folder.png?fit=max&auto=format&n=LNOqt5Bssg2lppqZ&q=85&s=1aedd0fba8a6959f679abda742005600" alt="Chọn Use an existing folder" width="275" height="116" data-path="images/vts-skills/codex-verify/use-existing-folder.png" />
           </Frame>

    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**.

           <Frame>
             <img src="https://mintcdn.com/solostylist/LNOqt5Bssg2lppqZ/images/vts-skills/codex-verify/select-input-folder.png?fit=max&auto=format&n=LNOqt5Bssg2lppqZ&q=85&s=e166da358d4508218c69f88c77d76a55" alt="Chọn thư mục đầu vào" width="885" height="456" data-path="images/vts-skills/codex-verify/select-input-folder.png" />
           </Frame>

    4. Codex mở project, sẵn sàng nhận lệnh trong khung chat.

           <Frame>
             <img src="https://mintcdn.com/solostylist/LNOqt5Bssg2lppqZ/images/vts-skills/codex-verify/project-chat.png?fit=max&auto=format&n=LNOqt5Bssg2lppqZ&q=85&s=2aebb4f544e149dd049de2a6d4d53750" alt="Khung chat của project trong Codex" width="1137" height="723" data-path="images/vts-skills/codex-verify/project-chat.png" />
           </Frame>

    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.

           <Frame>
             <img src="https://mintcdn.com/solostylist/LNOqt5Bssg2lppqZ/images/vts-skills/codex-verify/verify-skills-list.png?fit=max&auto=format&n=LNOqt5Bssg2lppqZ&q=85&s=e9bd880b36dcaa488b4af6c9ec1a3427" alt="Danh sách TKCT Skills hiện ra khi gõ $tkct" width="753" height="434" data-path="images/vts-skills/codex-verify/verify-skills-list.png" />
           </Frame>

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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ý.

    <Frame>
      <img src="https://mintcdn.com/solostylist/pVQJBMEPownIsoD4/images/vts-skills/codex-run/paste-prompt.png?fit=max&auto=format&n=pVQJBMEPownIsoD4&q=85&s=873e24e51c119dbfc2b9a09d418fd59e" alt="Dán prompt kèm skill và file vào khung chat Codex" width="762" height="477" data-path="images/vts-skills/codex-run/paste-prompt.png" />
    </Frame>
  </Step>

  <Step title="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.

    <Frame>
      <img src="https://mintcdn.com/solostylist/pVQJBMEPownIsoD4/images/vts-skills/codex-run/output-result.png?fit=max&auto=format&n=pVQJBMEPownIsoD4&q=85&s=8cf85c309c6ab6a8fc70a4e241c0fecc" alt="Kết quả AI trả về: file .docx và script sinh tài liệu" width="760" height="175" data-path="images/vts-skills/codex-run/output-result.png" />
    </Frame>

    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.
  </Step>
</Steps>

## 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.

<AccordionGroup>
  <Accordion title="7.1. Sinh tài liệu hoàn chỉnh">
    * **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.

    ```markdown theme={null}
    # 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**

    <iframe width="100%" height="400" src="https://www.youtube.com/embed/nJm4-QV3X34" title="Sinh tài liệu TKCT hoàn chỉnh" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
  </Accordion>

  <Accordion title="7.2. Sinh nội dung cho một đối tượng">
    * **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.

    ```markdown theme={null}
    # 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**

    <iframe width="100%" height="400" src="https://www.youtube.com/embed/OuyP1Gf08jI" title="Sinh nội dung cho một đối tượng dữ liệu" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
  </Accordion>

  <Accordion title="7.3. Sinh một chức năng đơn lẻ">
    * **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 đó.

    ```markdown theme={null}
    # 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ẻ**

    <iframe width="100%" height="400" src="https://www.youtube.com/embed/TziKNB_jkzE" title="Sinh một chức năng đơn lẻ" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
  </Accordion>

  <Accordion title="7.4. Sinh tài liệu tự động từ CSDL">
    * **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.

    ```markdown theme={null}
    # 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**

    <iframe width="100%" height="400" src="https://www.youtube.com/embed/R00dlxJGZPo" title="Sinh tài liệu tự động từ Cơ sở Dữ liệu" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
  </Accordion>
</AccordionGroup>

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

<AccordionGroup>
  <Accordion title="AI không kích hoạt đúng skill">
    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.
  </Accordion>

  <Accordion title="File .docx sai định dạng / font">
    Đả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.
  </Accordion>

  <Accordion title="Sơ đồ vẽ ra chưa chuẩ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.
  </Accordion>

  <Accordion title="Không kết nối được CSDL">
    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.
  </Accordion>
</AccordionGroup>