Mert

---
name: trello-integration-skill
description: Kỹ năng này cho phép bạn tương tác với tài khoản Trello để liệt kê các bảng (boards), xem các danh sách (lists) và tạo thẻ công việc (cards) một cách tự động.
---

# Kỹ Năng Tích Hợp Trello (Trello Integration Skill)

Kỹ năng Tích hợp Trello cung cấp kết nối liền mạch giữa tác nhân AI (AI agent) và tài khoản Trello của người dùng. Nó trao quyền cho tác nhân tự động truy xuất các bảng và danh sách hiện có, cũng như tạo các thẻ công việc mới trên những bảng cụ thể dựa trên yêu cầu của người dùng.

## Tính năng
- **Truy xuất Bảng (Fetch Boards)**: Lấy danh sách toàn bộ các bảng Trello mà người dùng có quyền truy cập, bao gồm Tên, ID và đường dẫn URL của chúng.
- **Truy xuất Danh sách (Fetch Lists)**: Lấy tất cả các danh sách (các cột như "To Do", "In Progress", "Done") thuộc về một bảng cụ thể.
- **Tạo Thẻ (Create Cards)**: Tự động tạo các thẻ công việc mới với tiêu đề và phần mô tả bên trong các danh sách được chỉ định.

---

##  Thiết Lập & Điều Kiện Tiên Quyết

Để sử dụng kỹ năng này ở môi trường cục bộ, bạn cần cung cấp thông tin xác thực Trello Developer API của mình.

1. Khởi tạo thông tin xác thực của bạn tại [Cổng thông tin Nhà phát triển Trello (Quản trị Power-Ups)](https://trello.com/app-key).
2. Tạo một Khóa API (API Key).
3. Khởi tạo một Mã thông báo Bí mật (Secret Token - có quyền Đọc/Ghi).
4. Thêm các thông tin xác thực này vào tệp `.env` ở thư mục gốc của dự án:

```env
# Trello Integration
TRELLO_API_KEY=your_api_key_here
TRELLO_TOKEN=your_token_here
```

---

##  Cách Sử Dụng & Kiến Trúc

Kỹ năng này sử dụng các kịch bản Node.js độc lập nằm trong thư mục `.agent/skills/trello_skill/scripts/`.

### 1. Liệt Kê Tất Cả Các Bảng
Truy xuất toàn bộ các bảng của người dùng đã xác thực để xác định đúng `boardId` mục tiêu.

**Thực thi:**
```bash
node .agent/skills/trello_skill/scripts/list_boards.js
```

### 2. Liệt Kê Các Cột (Danh Sách) Trong Một Bảng
Truy xuất các danh sách nằm bên trong một bảng cụ thể để tìm chính xác mã `listId` (ví dụ: lấy mã ID của cột "To Do").

**Thực thi:**
```bash
node .agent/skills/trello_skill/scripts/list_lists.js <boardId>
```

### 3. Tạo Một Thẻ Mới
Đẩy một thẻ mới lên danh sách đã chỉ định. 

**Thực thi:**
```bash
node .agent/skills/trello_skill/scripts/create_card.js <listId> "<Card Title>" "<Optional Description>"
```
*(Luôn đặt tiêu đề thẻ và nội dung mô tả bên trong cặp dấu ngoặc kép để ngăn bash tách nhỏ các đối số có dấu cách).*

---

##  Quy Trình Làm Việc Của Tác Nhân AI

Khi người dùng yêu cầu quản lý hoặc thêm một công việc vào Trello, hãy tự động thực hiện tuần tự các bước sau:
1. **Xác định Đích đến**: Nếu chưa biết `listId` mục tiêu, trước tiên hãy chạy `list_boards.js` để xác định đúng `boardId`, sau đó thực thi `list_lists.js <boardId>` để lấy mã `listId` tương ứng (ví dụ: cho cột "To Do").
2. **Thực thi Lệnh**: Chạy kịch bản `create_card.js <listId> "Task Title" "Task Description"`.
3. **Báo cáo Kết quả**: Xác nhận đã tạo thẻ thành công với người dùng và cung cấp đường dẫn URL trực tiếp trỏ tới thẻ Trello vừa được tạo.
FILE:create_card.js
const path = require('path');
require('dotenv').config({ path: path.join(__dirname, '../../../../.env') });

const API_KEY = process.env.TRELLO_API_KEY;
const TOKEN = process.env.TRELLO_TOKEN;

if (!API_KEY || !TOKEN) {
    console.error("Error: TRELLO_API_KEY or TRELLO_TOKEN is missing from the .env file.");
    process.exit(1);
}

const listId = process.argv[2];
const cardName = process.argv[3];
const cardDesc = process.argv[4] || "";

if (!listId || !cardName) {
    console.error(`Usage: node create_card.js <listId> "card_name" ["card_description"]`);
    process.exit(1);
}

async function createCard() {
    const url = `https://api.trello.com/1/cards?idList=listId&key=API_KEY&token=TOKEN`;

    try {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Accept': 'application/json',
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                name: cardName,
                desc: cardDesc,
                pos: 'top'
            })
        });

        if (!response.ok) {
            const errText = await response.text();
            throw new Error(`HTTP error! status: response.status, message: errText`);
        }
        const card = await response.json();
        console.log(`Successfully created card!`);
        console.log(`Name: card.name`);
        console.log(`ID: card.id`);
        console.log(`URL: card.url`);
    } catch (error) {
        console.error("Failed to create card:", error.message);
    }
}

createCard();
FILE:list_board.js
const path = require('path');
require('dotenv').config({ path: path.join(__dirname, '../../../../.env') });

const API_KEY = process.env.TRELLO_API_KEY;
const TOKEN = process.env.TRELLO_TOKEN;

if (!API_KEY || !TOKEN) {
    console.error("Error: TRELLO_API_KEY or TRELLO_TOKEN is missing from the .env file.");
    process.exit(1);
}

async function listBoards() {
    const url = `https://api.trello.com/1/members/me/boards?key=API_KEY&token=TOKEN&fields=name,url`;
    try {
        const response = await fetch(url);
        if (!response.ok) throw new Error(`HTTP error! status: response.status`);
        const boards = await response.json();
        console.log("--- Your Trello Boards ---");
        boards.forEach(b => console.log(`Name: b.name\nID: b.id\nURL: b.url\n`));
    } catch (error) {
        console.error("Failed to fetch boards:", error.message);
    }
}

listBoards();
FILE:list_lists.js
const path = require('path');
require('dotenv').config({ path: path.join(__dirname, '../../../../.env') });

const API_KEY = process.env.TRELLO_API_KEY;
const TOKEN = process.env.TRELLO_TOKEN;

if (!API_KEY || !TOKEN) {
    console.error("Error: TRELLO_API_KEY or TRELLO_TOKEN is missing from the .env file.");
    process.exit(1);
}

const boardId = process.argv[2];
if (!boardId) {
    console.error("Usage: node list_lists.js <boardId>");
    process.exit(1);
}

async function listLists() {
    const url = `https://api.trello.com/1/boards/boardId/lists?key=API_KEY&token=TOKEN&fields=name`;
    try {
        const response = await fetch(url);
        if (!response.ok) throw new Error(`HTTP error! status: response.status`);
        const lists = await response.json();
        console.log(`--- Lists in Board boardId ---`);
        lists.forEach(l => console.log(`Name: "l.name"\nID: l.id\n`));
    } catch (error) {
        console.error("Failed to fetch lists:", error.message);
    }
}

listLists();