---
title: "Thông số kỹ thuật định dạng Skills | Tajo"
description: "Tìm hiểu định dạng skills.md để định nghĩa các Skills tự động hóa được hỗ trợ bởi AI tích hợp với Brevo."
url: https://tajo.io/vi/docs/skills/overview/skills-format/
markdown: https://tajo.io/vi/docs/skills/overview/skills-format.md
lang: vi-VN
author: "Set Noa"
author_url: https://tajo.io/vi/set-noa/
robots: noindex
---

Đăng ký quyền truy cập sớm

Nhập tên và địa chỉ email công việc của bạn. Chúng tôi sẽ gửi liên kết để xác nhận yêu cầu truy cập Tajo.

# Thông số kỹ thuật định dạng Skills

[Set Noa](https://tajo.io/vi/set-noa/)

Định dạng **skills.md** xác định cách Skills được cấu trúc, cấu hình và thực thi. Thông số kỹ thuật này đảm bảo hành vi nhất quán trên tất cả Tajo Skills.

## Cấu trúc tệp

Một skill được định nghĩa trong một tệp markdown duy nhất với YAML frontmatter:

```markdown
---
name: customer-sync
version: 2.1.0
description: Sync customer data to Brevo contacts
category: data-sync
status: stable

triggers:
  - event: customer_created
  - event: customer_updated
  - event: customer_deleted

actions:
  - brevo/create-contact
  - brevo/update-contact
  - brevo/delete-contact

brevoEndpoints:
  - POST /v3/contacts
  - PUT /v3/contacts/{identifier}
  - DELETE /v3/contacts/{identifier}

permissions:
  - contacts:write
  - contacts:read
---

# Customer Sync

Automatically synchronize customer data from your platform to Brevo contacts.

## Overview

This skill listens for customer lifecycle events and mirrors changes to Brevo...
```

## Các trường Frontmatter

### Các trường bắt buộc

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `name` | string | Định danh duy nhất (kebab-case) |
| `version` | string | Phiên bản Semantic (ví dụ: “2.1.0”) |
| `description` | string | Mô tả ngắn (tối đa 160 ký tự) |
| `category` | enum | Một trong: `data-sync`, `email-marketing`, `sms-whatsapp`, `loyalty`, `analytics`, `integrations` |
| `triggers` | array | Các sự kiện kích hoạt skill này |
| `actions` | array | Các thao tác skill này có thể thực hiện |

### Các trường tùy chọn

| Trường | Kiểu | Mặc định | Mô tả |
| --- | --- | --- | --- |
| `status` | enum | `stable` | Một trong: `stable`, `beta`, `experimental` |
| `brevoEndpoints` | array | `[]` | Các Brevo API endpoints được sử dụng |
| `permissions` | array | `[]` | Các quyền Brevo API cần thiết |
| `relatedSkills` | array | `[]` | ID của các skills liên quan |
| `featured` | boolean | `false` | Nổi bật trong danh mục skill |

## Triggers

Triggers xác định những sự kiện nào kích hoạt skill.

### Trigger sự kiện

```yaml
triggers:
  - event: cart_abandoned
    conditions:
      - cart_value: "> 50"        # Giá trị giỏ hàng tối thiểu
      - items_count: ">= 1"       # Ít nhất một mặt hàng
      - time_since_activity: "> 30m"  # 30 phút không hoạt động
    debounce: 5m                  # Chờ 5 phút trước khi kích hoạt lại
```

### Trigger lịch trình

```yaml
triggers:
  - schedule: "0 9 * * *"         # Biểu thức Cron (hàng ngày lúc 9 giờ sáng)
    timezone: "America/New_York"
  - schedule: every_hour
  - schedule: every_day
```

### Trigger Webhook

```yaml
triggers:
  - webhook: /skills/customer-sync/trigger
    method: POST
    authentication: api_key
```

### Toán tử điều kiện

| Toán tử | Mô tả | Ví dụ |
| --- | --- | --- |
| `=` | Bằng | `status: "active"` |
| `!=` | Không bằng | `status: "!= deleted"` |
| `>` | Lớn hơn | `cart_value: "> 50"` |
| `>=` | Lớn hơn hoặc bằng | `items: ">= 1"` |
| `<` | Nhỏ hơn | `age: "< 30"` |
| `<=` | Nhỏ hơn hoặc bằng | `quantity: "<= 10"` |
| `contains` | Chuỗi chứa | `email: "contains @gmail.com"` |
| `starts_with` | Tiền tố chuỗi | `name: "starts_with Dr."` |
| `in` | Giá trị trong danh sách | `country: "in US,CA,UK"` |

## Actions

Actions xác định các thao tác mà skill thực hiện.

### Định nghĩa Action

```yaml
actions:
  - id: send_reminder_email
    type: brevo/send-email
    parameters:
      template_id: 12345
      to: "{{ contact.email }}"
      params:
        first_name: "{{ contact.firstName }}"
        cart_items: "{{ cart.items }}"
    retry:
      attempts: 3
      backoff: exponential
    on_error: continue  # hoặc 'stop'
```

### Các loại Action

| Loại | Mô tả |
| --- | --- |
| `brevo/send-email` | Gửi email giao dịch |
| `brevo/send-sms` | Gửi tin nhắn SMS |
| `brevo/send-whatsapp` | Gửi tin nhắn WhatsApp |
| `brevo/create-contact` | Tạo liên hệ mới |
| `brevo/update-contact` | Cập nhật thuộc tính liên hệ |
| `brevo/delete-contact` | Xóa liên hệ |
| `brevo/add-to-list` | Thêm liên hệ vào danh sách |
| `brevo/remove-from-list` | Xóa liên hệ khỏi danh sách |
| `brevo/track-event` | Theo dõi sự kiện tùy chỉnh |
| `http/request` | Tạo yêu cầu HTTP |
| `transform/map` | Chuyển đổi dữ liệu |
| `control/delay` | Chờ trước khi tiếp tục |
| `control/condition` | Phân nhánh dựa trên điều kiện |

### Biến mẫu

Sử dụng cú pháp `{{ }}` để tham chiếu dữ liệu:

```yaml
parameters:
  to: "{{ contact.email }}"
  subject: "Your order #{{ order.number }} has shipped"
  params:
    name: "{{ contact.firstName | default: 'Customer' }}"
    items: "{{ cart.items | map: 'name' | join: ', ' }}"
    total: "{{ cart.total | currency: 'USD' }}"
```

### Các bộ lọc có sẵn

| Bộ lọc | Mô tả | Ví dụ |
| --- | --- | --- |
| `default` | Giá trị mặc định | `{{ name \| default: 'Guest' }}` |
| `uppercase` | Chữ hoa | `{{ name \| uppercase }}` |
| `lowercase` | Chữ thường | `{{ email \| lowercase }}` |
| `capitalize` | Viết hoa chữ đầu | `{{ name \| capitalize }}` |
| `truncate` | Cắt ngắn chuỗi | `{{ desc \| truncate: 100 }}` |
| `date` | Định dạng ngày | `{{ date \| date: 'YYYY-MM-DD' }}` |
| `currency` | Định dạng tiền tệ | `{{ price \| currency: 'EUR' }}` |
| `map` | Map thuộc tính mảng | `{{ items \| map: 'name' }}` |
| `join` | Nối mảng | `{{ tags \| join: ', ' }}` |
| `first` | Phần tử đầu tiên của mảng | `{{ items \| first }}` |
| `last` | Phần tử cuối cùng của mảng | `{{ items \| last }}` |
| `size` | Độ dài mảng/chuỗi | `{{ items \| size }}` |

## Quyền

Xác định các quyền Brevo API cần thiết:

```yaml
permissions:
  - contacts:read        # Đọc dữ liệu liên hệ
  - contacts:write       # Tạo/cập nhật liên hệ
  - email:send           # Gửi email giao dịch
  - sms:send             # Gửi tin nhắn SMS
  - lists:write          # Quản lý danh sách liên hệ
  - events:write         # Theo dõi sự kiện
```

## Ví dụ đầy đủ

```yaml
---
name: abandoned-cart-recovery
version: 3.0.0
description: Recover abandoned shopping carts with a multi-step email sequence
category: email-marketing
status: stable

triggers:
  - event: cart_abandoned
    conditions:
      - cart_value: "> 25"
      - customer_email: "exists"
      - items_count: ">= 1"
    debounce: 30m

actions:
  - id: wait_1h
    type: control/delay
    parameters:
      duration: 1h

  - id: check_purchase
    type: control/condition
    parameters:
      condition: "{{ cart.converted }} = false"
      then: send_first_email
      else: stop

  - id: send_first_email
    type: brevo/send-email
    parameters:
      template_id: {{ env.ABANDONED_CART_TEMPLATE_1 }}
      to: "{{ contact.email }}"
      params:
        first_name: "{{ contact.firstName }}"
        cart_url: "{{ cart.recovery_url }}"
        items: "{{ cart.items }}"
        total: "{{ cart.total | currency }}"

  - id: wait_24h
    type: control/delay
    parameters:
      duration: 24h

  - id: check_purchase_2
    type: control/condition
    parameters:
      condition: "{{ cart.converted }} = false"
      then: send_second_email
      else: stop

  - id: send_second_email
    type: brevo/send-email
    parameters:
      template_id: {{ env.ABANDONED_CART_TEMPLATE_2 }}
      to: "{{ contact.email }}"
      params:
        first_name: "{{ contact.firstName }}"
        cart_url: "{{ cart.recovery_url }}"
        discount_code: "{{ generate_discount(10, 'percent') }}"

brevoEndpoints:
  - POST /v3/smtp/email
  - GET /v3/contacts/{identifier}

permissions:
  - contacts:read
  - email:send

relatedSkills:
  - customer-sync
  - order-events
  - browse-abandonment
---

# Abandoned Cart Recovery

Recover lost sales with a proven multi-step email sequence...
```

## Hiển thị MCP Tool

Skills có thể được hiển thị dưới dạng MCP tools, cho phép AI agents có thể gọi chúng. Thêm trường `mcp` vào frontmatter của bạn:

```yaml
---
name: abandoned-cart-recovery
version: 3.0.0
description: Recover abandoned shopping carts with a multi-step email sequence
category: email-marketing

# Cấu hình MCP
mcp:
  tool_name: tajo/recover-abandoned-cart
  description: Execute abandoned cart recovery sequence for a specific cart
  inputSchema:
    type: object
    properties:
      cart_id:
        type: string
        description: The abandoned cart identifier
      customer_email:
        type: string
        description: Customer email address
      min_cart_value:
        type: number
        description: Minimum cart value to trigger recovery
        default: 25
    required: [cart_id, customer_email]
  brevo_servers:
    - brevo_contacts
    - brevo_email_campaign_management
    - brevo_templates
---
```

### Cách hoạt động của việc hiển thị MCP

Khi một skill có trường `mcp`, nó trở thành một tool mà AI agents có thể khám phá và gọi:

```
Agent: "Recover abandoned cart #4521 for user@example.com"
    ↓
MCP Tool Discovery: finds tajo/recover-abandoned-cart
    ↓
Tool Execution: runs the skill's action chain
    ↓
Brevo MCP Servers: contacts + email modules called
    ↓
Result: recovery sequence initiated
```

### Các trường MCP

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `mcp.tool_name` | string | Tên MCP tool (định dạng: `tajo/skill-name`) |
| `mcp.description` | string | Mô tả hiển thị cho AI agents trong quá trình khám phá tool |
| `mcp.inputSchema` | object | JSON Schema xác định các tham số đầu vào của tool |
| `mcp.brevo_servers` | array | Các mô-đun Brevo MCP server mà skill này cần |

### Skills so với Direct MCP Tools

| Khía cạnh | Skill dưới dạng MCP Tool | Direct Brevo MCP |
| --- | --- | --- |
| **Tính trừu tượng** | Cao, agent nói “khôi phục giỏ hàng này” | Thấp, agent phải gọi từng Brevo endpoint |
| **Độ phức tạp** | Đóng gói logic nhiều bước | Agent phải điều phối từng bước |
| **Biện pháp bảo vệ** | Tích hợp vào skill (điều kiện, debounce) | Agent phải tự triển khai |
| **Phù hợp nhất** | Quy trình có thể lặp lại | Thao tác một lần |

Tip

**Sử dụng Skills dưới dạng MCP tools** cho các quy trình phức tạp, nhiều bước mà agents không nên tự tạo lại mỗi lần. Sử dụng **direct Brevo MCP tools** cho các thao tác đơn giản, một lần như tra cứu liên hệ hoặc gửi một email.

### Kết hợp Skills và Agents

Một agent có thể sử dụng cả Skills (dưới dạng MCP tools) và Brevo MCP modules trực tiếp:

```yaml
# Agent spec
---
name: retention-agent
tools:
  # Tajo Skills dưới dạng MCP tools
  - tajo/recover-abandoned-cart
  - tajo/customer-sync
  - tajo/win-back-sequence
  # Direct Brevo MCP modules
  - brevo_contacts
  - brevo_campaign_analytics
  - brevo_segments
---
```

Điều này cung cấp cho agents tự động hóa cấp cao (Skills) cho các mẫu phổ biến trong khi vẫn giữ quyền truy cập cấp thấp (Brevo MCP) cho logic tùy chỉnh.

Xem [Định dạng thông số kỹ thuật Agent](https://tajo.io/vi/docs/mcp/agent-specification) và [Xây dựng Agents](https://tajo.io/vi/docs/mcp/building-agents) để biết thông tin đầy đủ.

## Thực tiễn tốt nhất

Tip

**Đánh phiên bản skills của bạn** bằng cách sử dụng semantic versioning. Các thay đổi phá vỡ tương thích yêu cầu tăng phiên bản chính.

1. **Giữ skills tập trung** - Một skill nên làm tốt một việc
2. **Sử dụng tên mô tả** - `abandoned-cart-recovery` không phải `acr`
3. **Ghi lại điều kiện** - Giải thích lý do tại sao mỗi điều kiện tồn tại
4. **Xử lý lỗi duyên dáng** - Sử dụng `on_error: continue` cho các actions không quan trọng
5. **Kiểm tra với đối tượng nhỏ** - Sử dụng `status: experimental` trong quá trình phát triển
6. **Thêm hiển thị MCP** cho các skills mà agents nên có thể gọi trực tiếp

## Bước tiếp theo

- [Tổng quan MCP & Agents](https://tajo.io/vi/docs/mcp) - Cách Skills phù hợp với kiến trúc agentic
- [Định dạng thông số kỹ thuật Agent](https://tajo.io/vi/docs/mcp/agent-specification) - Xác định agents sử dụng Skills dưới dạng tools
- [Xây dựng Agents](https://tajo.io/vi/docs/mcp/building-agents) - Xây dựng marketing agent đầu tiên của bạn
- [Data Sync Skills](https://tajo.io/vi/docs/skills/data-sync) - Khám phá các skills đồng bộ dữ liệu