---
title: "スキルフォーマット仕様 | Tajo"
description: "Brevoと連携するAI駆動オートメーションスキルを定義するためのskills.mdフォーマットを学びます。"
url: https://tajo.io/jp/docs/skills/overview/skills-format/
markdown: https://tajo.io/jp/docs/skills/overview/skills-format.md
lang: ja-JP
author: "Set Noa"
author_url: https://tajo.io/jp/set-noa/
robots: noindex
---

先行利用を申し込む

お名前と会社のメールアドレスを入力してください。Tajoへのアクセス申請を確認するためのリンクをメールでお送りします。

# スキルフォーマット仕様

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

**skills.md**フォーマットは、スキルの構造、設定、実行方法を定義します。この仕様により、すべてのTajoスキルが一貫した動作をします。

## ファイル構成

スキルはYAMLフロントマター付きの単一のマークダウンファイルで定義されます。

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

## フロントマターフィールド

### 必須フィールド

| フィールド | 型 | 説明 |
| --- | --- | --- |
| `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 | このスキルを起動するイベント |
| `actions` | array | このスキルが実行できる操作 |

### オプションフィールド

| フィールド | 型 | デフォルト | 説明 |
| --- | --- | --- | --- |
| `status` | enum | `stable` | `stable`、`beta`、`experimental`のいずれか |
| `brevoEndpoints` | array | `[]` | 使用するBrevo APIエンドポイント |
| `permissions` | array | `[]` | 必要なBrevo APIパーミッション |
| `relatedSkills` | array | `[]` | 関連スキルのID |
| `featured` | boolean | `false` | スキルカタログで強調表示 |

## トリガー

トリガーはスキルを起動するイベントを定義します。

### イベントトリガー

```yaml
triggers:
  - event: cart_abandoned
    conditions:
      - cart_value: "> 50"        # Minimum cart value
      - items_count: ">= 1"       # At least one item
      - time_since_activity: "> 30m"  # 30 minutes of inactivity
    debounce: 5m                  # Wait 5 minutes before re-triggering
```

### スケジュールトリガー

```yaml
triggers:
  - schedule: "0 9 * * *"         # Cron expression (daily at 9am)
    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"` |

## アクション

アクションはスキルが実行する操作を定義します。

### アクション定義

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

### アクションタイプ

| タイプ | 説明 |
| --- | --- |
| `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        # Read contact data
  - contacts:write       # Create/update contacts
  - email:send           # Send transactional emails
  - sms:send             # Send SMS messages
  - lists:write          # Manage contact lists
  - events:write         # Track events
```

## 完全な例

```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ツールとしての公開

スキルはMCPツールとして公開でき、AIエージェントから呼び出し可能になります。フロントマターに`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 Configuration
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公開の仕組み

スキルに`mcp`フィールドがあると、AIエージェントが発見して呼び出せるツールになります。

```
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エージェントに表示される説明 |
| `mcp.inputSchema` | object | ツールの入力パラメータを定義するJSON Schema |
| `mcp.brevo_servers` | array | このスキルが必要とするBrevo MCPサーバーモジュール |

### スキルと直接MCPツールの比較

| 側面 | MCPツールとしてのスキル | 直接Brevo MCP |
| --- | --- | --- |
| **抽象化** | 高い, エージェントは「このカートをリカバリー」と言うだけ | 低い, エージェントは個別のBrevoエンドポイントを呼び出す必要がある |
| **複雑さ** | 多段階のロジックをカプセル化 | エージェントが各ステップをオーケストレートする必要がある |
| **ガードレール** | スキル内に組み込み（条件、デバウンス） | エージェントが独自に実装する必要がある |
| **適した用途** | 繰り返し可能なワークフロー | 単発の操作 |

Tip

**MCPツールとしてのスキル**は、エージェントに毎回作り直させたくない複雑な多段階ワークフローに使用してください。コンタクトの参照や単発メール送信のようなシンプルな一回限りの操作には**直接Brevo MCPツール**を使用します。

### スキルとエージェントの組み合わせ

エージェントは（MCPツールとしての）スキルと直接Brevo MCPモジュールの両方を使えます。

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

これにより、エージェントは一般的なパターンに対して高レベルのオートメーション（スキル）を使いつつ、カスタムロジック用に低レベルアクセス（Brevo MCP）も維持できます。

詳しくは[エージェント仕様フォーマット](https://tajo.io/jp/docs/mcp/agent-specification)と[エージェントの構築](https://tajo.io/jp/docs/mcp/building-agents)をご覧ください。

## ベストプラクティス

Tip

**スキルにはセマンティックバージョニング**を使ってバージョンを付けてください。破壊的変更はメジャーバージョンの引き上げが必要です。

1. **スキルは焦点を絞る** - 1つのスキルで1つのことを上手にこなす
2. **わかりやすい名前を使う** - `acr`ではなく`abandoned-cart-recovery`
3. **条件をドキュメント化** - 各条件が存在する理由を説明する
4. **エラーを優雅に処理** - クリティカルでないアクションには`on_error: continue`を使う
5. **小さなオーディエンスでテスト** - 開発中は`status: experimental`を使う
6. **MCP公開を追加** - エージェントが直接呼び出せるべきスキルに

## 次のステップ

- [MCPとエージェントの概要](https://tajo.io/jp/docs/mcp) - スキルがエージェントアーキテクチャにどう収まるか
- [エージェント仕様フォーマット](https://tajo.io/jp/docs/mcp/agent-specification) - スキルをツールとして使うエージェントを定義
- [エージェントの構築](https://tajo.io/jp/docs/mcp/building-agents) - 最初のマーケティングエージェントを構築
- [データ同期スキル](https://tajo.io/jp/docs/skills/data-sync) - データ同期スキルを見る