> ## Documentation Index
> Fetch the complete documentation index at: https://docs-agents.fpt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kỹ năng (Skills)

> Những việc lặp lại được đóng gói để agent dùng lại

Kỹ năng là một gói gồm hướng dẫn, tài nguyên và mã thực thi mà agent tải lên khi cần. Thay vì nhét mọi quy trình vào Instructions, bạn tách những việc lặp lại thành kỹ năng riêng để agent gọi ra đúng lúc.

<img src="https://mintcdn.com/fpt-62e894b4/MLGg3fcpvPErRgBt/images/agent-ky-nang.jpg?fit=max&auto=format&n=MLGg3fcpvPErRgBt&q=85&s=fa3b73a69db253a62d967fd99a64c009" alt="Agent Ky Nang" width="1470" height="724" data-path="images/agent-ky-nang.jpg" />

## Hai loại kỹ năng

| Loại | Ý nghĩa |
| - | - |
| **Kỹ năng riêng của agent** | Chỉ agent này dùng, thường do trợ lý tạo ra trong lúc dựng |
| **Kỹ năng của workspace** | Dùng chung cho nhiều agent, gắn vào bằng nút **Kết nối kỹ năng workspace** |

Mỗi kỹ năng có số phiên bản và trạng thái bật/tắt, kèm thông tin đang được bao nhiêu agent dùng.

## Thêm kỹ năng cho agent

* **Tạo kỹ năng** - tự viết một kỹ năng mới cho riêng agent.
* **Kết nối kỹ năng workspace** - lấy một kỹ năng đã có sẵn trong workspace.
* **Nhờ trợ lý** - mô tả việc cần lặp lại, trợ lý sẽ đề xuất tạo kỹ năng tương ứng và chờ bạn duyệt.

## Sửa, xóa và bật/tắt kỹ năng

<Steps>
  <Step title="Sửa kỹ năng">
    Bấm vào thẻ kỹ năng trong danh sách để mở lại form - đổi Tên, Mô tả, Loại kỹ năng, Biểu tượng, hoặc xem lại cây file SKILL.md và các file kèm theo. Nếu kỹ năng đang được nhiều agent khác dùng, Console cảnh báo trước: "Kỹ năng này đang được N agent sử dụng - thay đổi sẽ ảnh hưởng tất cả."

    <img src="https://mintcdn.com/fpt-62e894b4/vc1HifpBTpQOuJhR/images/skill-edit-modal.jpg?fit=max&auto=format&n=vc1HifpBTpQOuJhR&q=85&s=89ecb45db8b5871e61f81556c11e82ea" alt="Skill Edit Modal" width="1470" height="724" data-path="images/skill-edit-modal.jpg" />
  </Step>

  <Step title="Xóa kỹ năng khỏi agent">
    Bấm icon thùng rác cạnh tên kỹ năng. Với kỹ năng riêng của agent, xóa là xóa hẳn. Với kỹ năng của workspace, xóa ở đây chỉ gỡ liên kết khỏi agent này - bản gốc trong workspace vẫn còn, agent khác vẫn dùng bình thường.

    <img src="https://mintcdn.com/fpt-62e894b4/vc1HifpBTpQOuJhR/images/skill-delete-menu.jpg?fit=max&auto=format&n=vc1HifpBTpQOuJhR&q=85&s=59a9425e72f80f24c4dcdfb9c26f0805" alt="Skill Delete Menu" width="1470" height="724" data-path="images/skill-delete-menu.jpg" />
  </Step>

  <Step title="Bật / tắt kỹ năng">
    Chỉ áp dụng cho kỹ năng của workspace. Vào Tài nguyên > Kỹ năng, tìm kỹ năng cần tắt, gạt công tắc Đang bật sang tắt. Khi tắt, kỹ năng ngừng khả dụng cho MỌI agent đang gắn nó, không chỉ agent bạn đang xem - dùng khi cần tạm ngưng một kỹ năng mà không muốn xóa cấu hình.

    <img src="https://mintcdn.com/fpt-62e894b4/vc1HifpBTpQOuJhR/images/skill-toggle-on.jpg?fit=max&auto=format&n=vc1HifpBTpQOuJhR&q=85&s=a15fcee016bbd8aadc50d140e2ea1e6c" alt="Skill Toggle On" width="1470" height="724" data-path="images/skill-toggle-on.jpg" />
  </Step>
</Steps>

<Note>
  Kỹ năng riêng của agent (tạo trực tiếp trong lúc dựng agent) không có công tắc bật/tắt - chỉ có thể sửa hoặc xóa hẳn.
</Note>

## Tải kỹ năng từ file có sẵn

Ngoài viết tay trong form, bạn có thể tải lên một kỹ năng đã soạn sẵn - tiện khi kỹ năng được viết ngoài, chia sẻ giữa các đội hoặc quản lý trong git. Console nhận ba dạng: **.md**, **.zip** và **.skill** (`.skill` thực chất là một gói zip đổi đuôi).

### Dạng .md - kỹ năng chỉ có hướng dẫn

Chọn dạng này khi kỹ năng chỉ là một bản hướng dẫn thuần văn bản, không cần file kèm. Phần đầu file phải là khối YAML kẹp giữa hai dòng `---`:

```yaml SKILL.md theme={null}
---
name: email-triage
description: Use when the user asks to process the inbox - classify, label, summarize emails and propose actions. Trigger words: phân loại email, xử lý hộp thư, triage inbox.
version: 1.0.0
---

# Phân loại & tóm tắt email

Quy trình lặp lại để xử lý hộp thư đến: phân loại, gắn nhãn, tóm tắt...
```

| Trường | Bắt buộc | Viết thế nào |
| - | - | - |
| `name` | Có | Chữ thường, nối bằng gạch ngang. Nên trùng tên file hoặc tên thư mục gốc |
| `description` | Có | Một câu trả lời cho "khi nào thì dùng kỹ năng này". Model đọc đúng dòng này để quyết định có gọi kỹ năng hay không, nên nêu kèm từ khóa kích hoạt |
| `version` | Nên có | Dạng `1.0.0`. Console hiển thị số này trên thẻ kỹ năng |

Phần nằm dưới khối YAML là nội dung hướng dẫn viết bằng Markdown - chính là thứ agent đọc và làm theo khi kỹ năng được kích hoạt.

### Dạng .zip / .skill - kỹ năng kèm tài nguyên

Khi kỹ năng cần thêm tài liệu tra cứu, mã chạy được hay file mẫu, đóng gói tất cả vào một file zip. Ràng buộc duy nhất của hệ thống: **phải có một file `SKILL.md` ở gốc gói**. Phần còn lại tùy bạn sắp xếp, nhưng quy ước dưới đây giúp agent định vị nhanh:

```text theme={null}
doi-soat-cong-no/
├── SKILL.md                  # bắt buộc - YAML + hướng dẫn chính
├── references/               # tài liệu tra cứu, agent chỉ mở khi cần
│   ├── quy-tac-doi-soat.md
│   └── bang-ma-loi.md
├── scripts/                  # mã thực thi
│   ├── doi_soat.py
│   └── xuat_excel.py
└── assets/                   # file mẫu, khung kết quả
    ├── mau-bao-cao.html
    └── logo-cong-ty.png
```

Sau khi tải lên, mở kỹ năng ra bạn sẽ thấy danh sách tệp trong gói ngay cạnh tên `SKILL.md`, kèm nút xem nội dung và tải gói về.

### Gói kỹ năng giữ nguyên mọi loại file

Khi bạn tải lên gói .zip hoặc .skill, hệ thống giữ nguyên toàn bộ file bên trong, không lọc bỏ theo định dạng. Agent đọc được cả tệp nhị phân đi kèm trong gói, nên một kỹ năng có thể mang theo biểu mẫu Excel, tài liệu PDF, ảnh minh họa hay file dữ liệu mẫu để dùng khi chạy.

<img src="https://mintcdn.com/fpt-62e894b4/91oWXyIxHSR9EXmO/images/skill_upload.jpg?fit=max&auto=format&n=91oWXyIxHSR9EXmO&q=85&s=5fe1d1eb18ce9f4e684d20b8b115f1d4" alt="Tải lên gói kỹ năng" width="1562" height="784" data-path="images/skill_upload.jpg" />

Yêu cầu tệp khi tải lên:

| Định dạng | Điều kiện |
| - | - |
| .md | Phải chứa name và description ở định dạng YAML |
| .zip hoặc .skill | Phải chứa một file SKILL.md |

<Note>
  .skill chỉ là file zip đổi đuôi, nên cách đóng gói của hai định dạng giống hệt nhau.
</Note>

<Tip>
  Đặt tài nguyên vào thư mục con theo đúng công dụng rồi trỏ tới trong SKILL.md. Agent chỉ mở file khi cần, nên gói gọn gàng thì chạy nhanh và ít nhầm hơn.
</Tip>

### Vì sao phải chia ra thay vì nhét hết vào SKILL.md

Agent không nạp cả gói vào ngữ cảnh mỗi lần chạy. Nó đọc theo ba nấc:

<Steps>
  <Step title="Đọc description">
    Dòng mô tả luôn nằm sẵn trong ngữ cảnh. Agent dựa vào đây để quyết định yêu cầu hiện tại có cần kỹ năng này không.
  </Step>

  <Step title="Nạp SKILL.md">
    Khi kỹ năng được kích hoạt, toàn bộ hướng dẫn trong SKILL.md mới được nạp vào.
  </Step>

  <Step title="Mở file kèm khi cần">
    Các file trong references/, scripts/, assets/ chỉ được đọc hoặc chạy khi SKILL.md trỏ tới chúng.
  </Step>
</Steps>

Nhờ vậy một kỹ năng chứa vài trăm trang quy định vẫn không làm phình ngữ cảnh lúc agent chưa cần đến. Nguyên tắc thực hành: giữ `SKILL.md` ngắn - quy trình, điều kiện dừng và đường dẫn tới file chi tiết; phần dài đẩy hết sang `references/`.

### Ví dụ: gói kỹ năng đối soát công nợ

Cuối mỗi tháng, kế toán phải đối chiếu sao kê ngân hàng với bảng theo dõi công nợ trên SharePoint rồi xuất báo cáo gửi trưởng phòng. Quy trình cố định, nhưng nhiều bước và có một bảng quy tắc khớp lệnh khá dài. Đóng gói lại:

| Tệp trong gói | Chứa gì |
| - | - |
| `SKILL.md` | Sáu bước của quy trình, chỗ nào phải dừng lại hỏi người dùng, và đường dẫn tới ba file bên dưới |
| `references/quy-tac-doi-soat.md` | Bảng quy tắc khớp lệnh và ngưỡng sai lệch được phép bỏ qua |
| `scripts/doi_soat.py` | Đọc hai nguồn, so khớp, trả về danh sách giao dịch chênh |
| `assets/mau-bao-cao.html` | Khung báo cáo để agent điền số vào |

Khi kế toán viên gõ "đối soát công nợ tháng 8", agent nhận ra qua `description`, nạp `SKILL.md`, chạy `doi_soat.py`, chỉ mở `quy-tac-doi-soat.md` khi gặp giao dịch lệch, rồi dựng báo cáo theo `mau-bao-cao.html`.

<Note>
  Tên kỹ năng nên viết thường, nối bằng dấu gạch ngang - `email-triage`, `doi-soat-cong-no` - và trùng với tên thư mục gốc trong gói zip. Tên có dấu cách hoặc tiếng Việt có dấu dễ gây lỗi khi agent gọi kỹ năng.
</Note>

<Note>
  Một kỹ năng đáng tách ra khi nó có quy trình rõ ràng và được dùng nhiều lần - ví dụ tóm tắt báo cáo định kỳ hay phân loại email đến. Việc chỉ làm một lần thì để trong Instructions gọn hơn.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.