On this page

Skills 格式规范

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

文件结构

Skill 在单个 Markdown 文件中定义，包含 YAML frontmatter：

---
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 字段

必填字段

字段类型描述
namestring唯一标识符（kebab-case 格式）
versionstring语义化版本号（如 “2.1.0”）
descriptionstring简短描述（最多 160 个字符）
categoryenum以下之一：data-sync、email-marketing、sms-whatsapp、loyalty、analytics、integrations
triggersarray激活此 Skill 的事件
actionsarray此 Skill 可执行的操作

可选字段

字段类型默认值描述
statusenumstable以下之一：stable、beta、experimental
brevoEndpointsarray[]使用的 Brevo API 端点
permissionsarray[]所需的 Brevo API 权限
relatedSkillsarray[]相关 Skills 的 ID
featuredbooleanfalse在 Skill 目录中突出显示

触发器（Triggers）

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

事件触发器 

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

定时触发器 

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

Webhook 触发器 

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 定义 

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根据条件分支

模板变量

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

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 权限：

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

完整示例 

---
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 字段：

---
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 [email protected]"
    ↓
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_namestringMCP 工具名称（格式：tajo/skill-name）
mcp.descriptionstring工具发现时向 AI Agent 展示的描述
mcp.inputSchemaobject定义工具输入参数的 JSON Schema
mcp.brevo_serversarray此 Skill 所需的 Brevo MCP 服务器模块

Skills 与 Direct MCP Tools 的对比

方面Skill 作为 MCP ToolDirect 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 模块：

# 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 规范格式 和 构建 Agents。

最佳实践

Tip

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

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

后续步骤

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

auto-detect
AI 助手

你好！关于文档有任何问题都可以问我。