---
title: "스킬 포맷 사양 | Tajo"
description: "Brevo와 통합되는 AI 기반 자동화 스킬을 정의하는 skills.md 포맷에 대해 알아봅니다."
url: https://tajo.io/kr/docs/skills/overview/skills-format/
markdown: https://tajo.io/kr/docs/skills/overview/skills-format.md
lang: ko-KR
author: "Set Noa"
author_url: https://tajo.io/kr/set-noa/
robots: noindex
---

Tajo 사전 이용 신청

이름과 회사 이메일 주소를 입력하세요. Tajo 이용 신청을 확인할 수 있는 링크를 이메일로 보내드립니다.

# 스킬 포맷 사양

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

**skills.md** 포맷은 스킬의 구조, 구성 및 실행 방식을 정의합니다. 이 사양은 모든 Tajo 스킬에서 일관된 동작을 보장합니다.

## 파일 구조

스킬은 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 | 이 스킬을 활성화하는 이벤트 |
| `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 에이전트가 호출할 수 있습니다. 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 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 서버 모듈 |

### 스킬 vs 직접 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/kr/docs/mcp/agent-specification) 및 [에이전트 구축](https://tajo.io/kr/docs/mcp/building-agents)을 참조하세요.

## 모범 사례

Tip

**시맨틱 버저닝을 사용하여 스킬 버전을 관리하세요**. 호환성이 깨지는 변경은 주 버전 증가가 필요합니다.

1. **스킬을 집중적으로 유지** - 하나의 스킬은 한 가지 일을 잘 해야 합니다
2. **설명적인 이름 사용** - `acr`이 아닌 `abandoned-cart-recovery`
3. **조건 문서화** - 각 조건이 존재하는 이유를 설명하세요
4. **오류를 우아하게 처리** - 중요하지 않은 액션에는 `on_error: continue`를 사용하세요
5. **소규모 대상으로 테스트** - 개발 중에는 `status: experimental`을 사용하세요
6. 에이전트가 직접 호출할 수 있어야 하는 스킬에는 **MCP 노출을 추가하세요**

## 다음 단계

- [MCP & 에이전트 개요](https://tajo.io/kr/docs/mcp) - 스킬이 에이전틱 아키텍처에 어떻게 맞는지
- [에이전트 사양 포맷](https://tajo.io/kr/docs/mcp/agent-specification) - 스킬을 도구로 사용하는 에이전트 정의
- [에이전트 구축](https://tajo.io/kr/docs/mcp/building-agents) - 첫 번째 마케팅 에이전트 구축
- [데이터 동기화 스킬](https://tajo.io/kr/docs/skills/data-sync) - 데이터 동기화 스킬 탐색