---
title: "Skills 格式规范 | Tajo"
description: "学习 skills.md 格式，用于定义与 Brevo 集成的 AI 驱动自动化 Skills。"
url: https://tajo.io/zh-cn/docs/skills/overview/skills-format/
markdown: https://tajo.io/zh-cn/docs/skills/overview/skills-format.md
lang: zh-CN
author: "Set Noa"
author_url: https://tajo.io/zh-cn/set-noa/
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# Skills 格式规范

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

**skills.md** 格式定义了 Skills 的结构、配置和执行方式。该规范确保所有 Tajo Skills 具有一致的行为。

## 文件结构

Skill 在单个 Markdown 文件中定义，包含 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...
```

## Frontmatter 字段

### 必填字段

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `name` | string | 唯一标识符（kebab-case 格式） |
| `version` | string | 语义化版本号（如 “2.1.0”） |
| `description` | string | 简短描述（最多 160 个字符） |
| `category` | enum | 以下之一：`data-sync`、`email-marketing`、`sms-whatsapp`、`loyalty`、`analytics`、`integrations` |
| `triggers` | array | 激活此 Skill 的事件 |
| `actions` | array | 此 Skill 可执行的操作 |

### 可选字段

| 字段 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `status` | enum | `stable` | 以下之一：`stable`、`beta`、`experimental` |
| `brevoEndpoints` | array | `[]` | 使用的 Brevo API 端点 |
| `permissions` | array | `[]` | 所需的 Brevo API 权限 |
| `relatedSkills` | array | `[]` | 相关 Skills 的 ID |
| `featured` | boolean | `false` | 在 Skill 目录中突出显示 |

## 触发器（Triggers）

触发器定义哪些事件会激活 Skill。

### 事件触发器

```yaml
triggers:
  - event: cart_abandoned
    conditions:
      - cart_value: "> 50"        # 最低购物车金额
      - items_count: ">= 1"       # 至少一件商品
      - time_since_activity: "> 30m"  # 30 分钟无活动
    debounce: 5m                  # 等待 5 分钟后再次触发
```

### 定时触发器

```yaml
triggers:
  - schedule: "0 9 * * *"         # Cron 表达式（每天上午 9 点）
    timezone: "America/New_York"
  - schedule: every_hour
  - schedule: every_day
```

### Webhook 触发器

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

### 条件运算符

| 运算符 | 描述 | 示例 |
| --- | --- | --- |
| `=` | 等于 | `status: "active"` |
| `!=` | 不等于 | `status: "!= deleted"` |
| `>` | 大于 | `cart_value: "> 50"` |
| `>=` | 大于等于 | `items: ">= 1"` |
| `<` | 小于 | `age: "< 30"` |
| `<=` | 小于等于 | `quantity: "<= 10"` |
| `contains` | 字符串包含 | `email: "contains @gmail.com"` |
| `starts_with` | 字符串前缀 | `name: "starts_with Dr."` |
| `in` | 值在列表中 | `country: "in US,CA,UK"` |

## 操作（Actions）

Actions 定义 Skill 执行的操作。

### 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  # 或 'stop'
```

### Action 类型

| 类型 | 描述 |
| --- | --- |
| `brevo/send-email` | 发送事务性邮件 |
| `brevo/send-sms` | 发送 SMS 短信 |
| `brevo/send-whatsapp` | 发送 WhatsApp 消息 |
| `brevo/create-contact` | 创建新联系人 |
| `brevo/update-contact` | 更新联系人属性 |
| `brevo/delete-contact` | 删除联系人 |
| `brevo/add-to-list` | 将联系人添加到列表 |
| `brevo/remove-from-list` | 从列表中移除联系人 |
| `brevo/track-event` | 追踪自定义事件 |
| `http/request` | 发起 HTTP 请求 |
| `transform/map` | 转换数据 |
| `control/delay` | 等待后继续 |
| `control/condition` | 根据条件分支 |

### 模板变量

使用 `{{ }}` 语法引用数据：

```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' }}"
```

### 可用过滤器

| 过滤器 | 描述 | 示例 |
| --- | --- | --- |
| `default` | 默认值 | `{{ name \| default: 'Guest' }}` |
| `uppercase` | 转大写 | `{{ name \| uppercase }}` |
| `lowercase` | 转小写 | `{{ email \| lowercase }}` |
| `capitalize` | 首字母大写 | `{{ name \| capitalize }}` |
| `truncate` | 截断字符串 | `{{ desc \| truncate: 100 }}` |
| `date` | 格式化日期 | `{{ date \| date: 'YYYY-MM-DD' }}` |
| `currency` | 格式化货币 | `{{ price \| currency: 'EUR' }}` |
| `map` | 映射数组属性 | `{{ items \| map: 'name' }}` |
| `join` | 连接数组 | `{{ tags \| join: ', ' }}` |
| `first` | 数组第一项 | `{{ items \| first }}` |
| `last` | 数组最后一项 | `{{ items \| last }}` |
| `size` | 数组/字符串长度 | `{{ items \| size }}` |

## 权限

定义所需的 Brevo API 权限：

```yaml
permissions:
  - contacts:read        # 读取联系人数据
  - contacts:write       # 创建/更新联系人
  - email:send           # 发送事务性邮件
  - sms:send             # 发送 SMS 短信
  - lists:write          # 管理联系人列表
  - events:write         # 追踪事件
```

## 完整示例

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

## MCP Tool 暴露

Skills 可以作为 MCP tools 暴露，使 AI Agent 能够调用它们。在 frontmatter 中添加 `mcp` 字段：

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

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

### MCP 暴露的工作原理

当 Skill 包含 `mcp` 字段时，它将成为 AI Agent 可发现和调用的工具：

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

### MCP 字段说明

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `mcp.tool_name` | string | MCP 工具名称（格式：`tajo/skill-name`） |
| `mcp.description` | string | 工具发现时向 AI Agent 展示的描述 |
| `mcp.inputSchema` | object | 定义工具输入参数的 JSON Schema |
| `mcp.brevo_servers` | array | 此 Skill 所需的 Brevo MCP 服务器模块 |

### Skills 与 Direct MCP Tools 的对比

| 方面 | Skill 作为 MCP Tool | Direct Brevo MCP |
| --- | --- | --- |
| **抽象层次** | 高，Agent 说”挽回这个购物车” | 低，Agent 必须逐个调用 Brevo 端点 |
| **复杂度** | 封装多步骤逻辑 | Agent 必须自行编排每个步骤 |
| **安全护栏** | 内置于 Skill（条件、防抖） | Agent 必须自行实现 |
| **最适合** | 可重复的工作流 | 一次性操作 |

Tip

对于复杂的多步骤工作流，**将 Skills 用作 MCP tools**，避免 Agent 每次重复构建。对于简单的一次性操作（如查询联系人或发送单封邮件），使用 **direct Brevo MCP tools**。

### 组合 Skills 与 Agents

Agent 可以同时使用 Skills（作为 MCP tools）和直接的 Brevo MCP 模块：

```yaml
# Agent spec
---
name: retention-agent
tools:
  # Tajo Skills 作为 MCP tools
  - tajo/recover-abandoned-cart
  - tajo/customer-sync
  - tajo/win-back-sequence
  # Direct Brevo MCP modules
  - brevo_contacts
  - brevo_campaign_analytics
  - brevo_segments
---
```

这使 Agent 既能使用高层自动化（Skills）处理常见模式，又保留对底层接口（Brevo MCP）的访问以实现自定义逻辑。

详情请参阅 [Agent 规范格式](https://tajo.io/zh-cn/docs/mcp/agent-specification) 和 [构建 Agents](https://tajo.io/zh-cn/docs/mcp/building-agents)。

## 最佳实践

Tip

使用语义化版本号**为您的 Skills 控制版本**。破坏性变更需要升级主版本号。

1. **保持 Skills 专注** - 一个 Skill 应该做好一件事
2. **使用描述性名称** - 用 `abandoned-cart-recovery` 而不是 `acr`
3. **记录条件说明** - 解释每个条件存在的原因
4. **优雅处理错误** - 对非关键操作使用 `on_error: continue`
5. **小范围测试** - 开发期间使用 `status: experimental`
6. **添加 MCP 暴露** - 针对 Agent 应能直接调用的 Skills

## 后续步骤

- [MCP 与 Agents 概览](https://tajo.io/zh-cn/docs/mcp) - Skills 如何融入智能体架构
- [Agent 规范格式](https://tajo.io/zh-cn/docs/mcp/agent-specification) - 定义使用 Skills 作为工具的 Agent
- [构建 Agents](https://tajo.io/zh-cn/docs/mcp/building-agents) - 构建您的第一个营销 Agent
- [数据同步 Skills](https://tajo.io/zh-cn/docs/skills/data-sync) - 探索数据同步 Skills