clix-personalization

What this skill does

# Clix Personalization

Use this skill to help developers write **personalized Clix campaigns** using
template-based variables and light logic in:

- **Message content** (title, body, subtitle)
- **Links** (dynamic URL or deep link params)
- **Audience targeting** (conditional include/exclude rules)

## What the official docs guarantee (high-signal)

- **Data namespaces**:
  - `user.*` (user traits/properties)
  - `event.*` (event payload properties)
  - `trigger.*` (custom properties passed via API-trigger)
  - Device/system vars: `device.id`, `device.platform`, `device.locale`,
    `device.language`, `device.timezone`, plus `user.id`, `event.name`
- **Missing variables** render as an **empty string**.
- **Output**: print values with `{{ ... }}`.
- **Conditionals**: `{% if %}`, `{% else %}`, `{% endif %}` with operators
  `== != > < >= <= and or not`. Invalid conditions evaluate to `false`.
- **Loops**: `{% for x in y %}` / `{% endfor %}` (use guards for empty lists).
- **Filters**: `upcase`, `downcase`, `capitalize`, `default`, `join`, `split`,
  `escape`, `strip`, `replace` (chain with `|`).
- **Errors**: template rendering errors show up in **Message Logs**.

## MCP-first (source of truth)

If the Clix MCP tools are available, treat them as the source of truth:

- `clix-mcp-server:search_docs` for personalization behavior and supported
  syntax

If MCP tools are not available, use the bundled references in `references/`.

## Workflow (copy + check off)

```
Personalization progress:
- [ ] 1) Identify where the template runs (message / URL / audience rule)
- [ ] 2) Identify trigger type (event-triggered vs API-triggered)
- [ ] 3) Confirm available inputs (user.*, event.*, trigger.*, device.*)
- [ ] 4) Draft templates with guards/defaults
- [ ] 5) Validate template structure (balance tags, avoid missing vars)
- [ ] 6) Verify in Clix (preview/test payloads, check Message Logs)
```

## 1) Confirm the minimum inputs

Ask only what’s needed:

- **Where used**: title/body/subtitle vs URL/deep link vs audience targeting
  rule
- **Campaign trigger**:
  - Event-triggered → `event.*` is available
  - API-triggered → `trigger.*` is available
- **Inputs**:
  - Which `user.*` properties are set by the app
  - Which `event.*` / `trigger.*` properties are passed (include example
    payload)
- **Fallback policy**: what to show when data is missing (default strings,
  guards)

## 2) Produce a “Template Plan” (before tweaking lots of templates)

Return a compact table the user can approve:

- **field** (title/body/url/audience)
- **template** (Liquid)
- **required variables** (and their source: user/event/trigger/device)
- **fallbacks** (default filter and/or conditional guards)
- **example payload** + **expected rendered output**

## 3) Authoring guidelines (what to do by default)

- Prefer **simple variables + `default`** over complex branching.
- Add **guards** for optional data and for arrays (`size > 0`) before looping.
- Prefer **pre-formatted** properties from your app (e.g., `"7.4 miles"`,
  `"38m 40s"`) instead of formatting inside templates.
- Keep logic minimal; complex branching belongs in the app or segmentation
  setup.

## 4) Validation (fast feedback loop)

If you have a template file (recommended for review), run:

```bash
bash <skill-dir>/scripts/validate-template.sh path/to/template.liquid
```

This script does lightweight checks (matching `{% if %}`/`{% endif %}`,
`{% for %}`/`{% endfor %}`, and brace balancing). It can’t guarantee the
variables exist — you still need a payload + console verification.

## 5) Verification checklist

- **Missing data**: does the template still read well with empty strings?
- **Trigger type**: API triggers use `trigger.*` (not `event.*`).
- **Message Logs**: check rendering errors and fix syntax issues first.
- **Upstream data**:
  - If `user.*` is missing → fix user property setting (see
    `clix-user-management`)
  - If `event.*` is missing → fix event tracking payload (see
    `clix-event-tracking`)

## Progressive Disclosure

- **Level 1**: This `SKILL.md` (always loaded)
- **Level 2**: `references/` (load when writing/debugging templates)
- **Level 3**: `scripts/` (execute directly, do not load into context)

## References

- `references/template-syntax.md` - Variables, output, conditionals, loops,
  filters
- `references/common-patterns.md` - Copy/paste patterns for messages + URLs +
  guards
- `references/debugging.md` - Troubleshooting missing variables and Message Logs