AGENT SKILL

skill-051

Helps developers configure API-triggered campaigns in the Clix console and

License 许可
MIT
最近更新
2026-06-04
Stars
★ 8
Forks
2

01 前言 Front Matter

name
skill-051
description
Helps developers configure API-triggered campaigns in the Clix console and

03 SKILL.md 正文

API-Triggered Campaigns (Backend → Clix)

Use this skill to set up API-triggered campaigns in the Clix console and trigger them from your backend with dynamic data (trigger.*) for:

  • Transactional notifications (orders, password reset, receipts)
  • Workflow messages (assignments, approvals)
  • System alerts (moderation, support tickets)
  • Programmatic sends where marketers/ops should control content + targeting

What the official docs guarantee (high-signal)

  • API-triggered campaigns are configured in the console, then triggered via: POST /api/v1/campaigns/{campaign_id}:trigger
  • Authentication uses secret headers:
    • X-Clix-Project-ID
    • X-Clix-API-Key
  • Request properties become trigger.* for:
    • Dynamic audience filtering (console audience rules)
    • Personalization in templates (title/body/deep links)
  • audience.broadcast=true sends to all users eligible under the campaign’s segment definition; audience.targets narrows to specific users/devices (still filtered by the segment definition).
  • Dynamic audience filters are intentionally constrained for performance: max 3 attributes in the audience definition.

MCP-first (source of truth)

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

  • Use clix-mcp-server:search_docs to confirm the latest API contract + limits:
    • query examples:
      • "API-triggered campaign trigger endpoint"
      • "campaigns/{campaign_id}:trigger audience targets broadcast"
      • "trigger.* dynamic audience filters limitations"

If MCP tools are not available, use the bundled references:

  • API contract → references/api-contract.md
  • Console setup + dynamic filters → references/console-setup.md
  • Backend patterns (auth, retries, timeouts) → references/backend-patterns.md
  • Security/key handling → references/security-and-keys.md
  • Personalization + dynamic filters → references/personalization-and-dynamic-filters.md
  • Debugging checklist → references/debugging.md

Workflow (copy + check off)

API-triggered campaign progress:
- [ ] 1) Confirm goals + trigger source (what backend event sends the message?)
- [ ] 2) Define campaign contract (properties keys/types; PII policy)
- [ ] 3) Configure campaign in console (API-triggered + audience rules + templates)
- [ ] 4) Implement backend trigger wrapper (auth, timeout, retries, logging)
- [ ] 5) Validate trigger plan JSON (schema + naming + safety)
- [ ] 6) Verify in Clix (test payloads, Message Logs, segment matching)

1) Confirm the minimum inputs

Ask only what’s needed:

  • Campaign: where is it in the console? do you already have campaign_id?
  • Channel: push / in-app / email / etc. (affects message template fields)
  • Audience mode: broadcast vs explicit targets
  • Dynamic filter keys: which trigger.* keys are used in audience rules
  • Properties: list of keys + types + example values (avoid PII by default)
  • Backend: runtime and HTTP client (Node/Fetch, Axios, Python, Go, etc.)

2) Create a “Trigger Plan” (before touching backend code)

Create api-trigger-plan.json in .clix/ (recommended) or project root.

Recommended location: .clix/api-trigger-plan.json

Plan schema (high-level):

  • campaign_id (string)
  • audience.mode: "broadcast" | "targets" | "default"
  • audience.targets (if mode is "targets")
  • dynamic_filter_keys (array of up to 3 snake_case keys)
  • properties (map of snake_case keys → { type, required?, example?, pii? })

Example:

{
  "campaign_id": "019aa002-1d0e-7407-a0c5-5bfa8dd2be30",
  "audience": {
    "mode": "broadcast"
  },
  "dynamic_filter_keys": ["store_location"],
  "properties": {
    "store_location": {
      "type": "string",
      "required": true,
      "example": "San Francisco"
    },
    "order_id": { "type": "string", "required": true, "example": "ORD-12345" },
    "item_count": { "type": "number", "required": true, "example": 3 },
    "pickup_time": { "type": "string", "required": false, "example": "2:30 PM" }
  }
}

3) Configure campaign in the console (API-triggered)

  • Set the campaign type to API-Triggered.
  • Build audience rules using {{ trigger.* }} for dynamic filters.
  • Use {{ trigger.* }} in message templates + deep links.

See: references/console-setup.md for exact guidance and limitations.

4) Implement backend trigger wrapper (best practices)

Backend wrapper responsibilities:

  • Auth: load X-Clix-Project-ID and X-Clix-API-Key from environment/secret store (never commit).
  • Timeout: set a short timeout (e.g., 3–10s) and fail fast.
  • Retries: retry only on transient failures (network/5xx), with backoff; do not retry blindly on 4xx.
  • Dedupe: prevent double-sends in your system (e.g., unique key per order event) since the API call is “send-like”.
  • Logging: log campaign_id, your correlation id (order id), and the Clix response (e.g., trigger_id).

Copy/paste examples:

  • Node: examples/trigger-campaign-node.js
  • Python: examples/trigger-campaign-python.py

5) Validate the plan (fast feedback loop)

Run:

bash <skill-dir>/scripts/validate-api-trigger-plan.sh .clix/api-trigger-plan.json

This validator checks:

  • valid JSON
  • campaign_id present
  • dynamic_filter_keys is ≤ 3 and snake_case
  • properties keys are snake_case and have valid types
  • example values match declared types
  • targets entries specify exactly one of project_user_id or device_id

6) Verify (Clix + end-to-end)

Minimum verification:

  • Campaign is API-Triggered and campaign_id matches.
  • If using dynamic audience filters, the trigger.* keys exist in the API call and match audience rules exactly.
  • Trigger once with a known-good payload; confirm delivery + inspect Message Logs for rendering errors.

See references/debugging.md.

Progressive Disclosure

  • Level 1: This SKILL.md (always loaded)
  • Level 2: references/ (load when implementing details)
  • Level 3: examples/ (load when copy/pasting backend code)
  • Level 4: scripts/ (execute directly; do not load into context)

References

  • references/api-contract.md
  • references/console-setup.md
  • references/backend-patterns.md
  • references/security-and-keys.md
  • references/personalization-and-dynamic-filters.md
  • references/debugging.md

04 同仓库更多 Skills

legendtkl
legendtkl/agentic-skill-router

foo

A test skill named foo

★ 8
legendtkl
legendtkl/agentic-skill-router

bar

飞书 — bar with quoted Chinese

★ 8
legendtkl
legendtkl/agentic-skill-router

agentic-skill-router

First use any clearly matching enabled local/user Agent Skill. If none matches, prefer this router for skill-shaped requests involving a named tool, API, service, CLI, platform, file format, dataset, or domain workflow, including when a generic built-in skill such as browser, Chrome, or web search also seems applicable; use built-ins directly only when explicitly requested or when the task is primarily live browsing, logged-in page operation, clicking, screenshotting, or current webpage inspection. Also use directly to audit, slim, disable, restore, or route locally installed Agent Skills across supported hosts. Examples include Vercel, Netlify, Cloudflare, Render, Playwright, Sentry, Linear, GitHub, OpenAI APIs, PDF, DOCX, PPTX, and spreadsheets.

★ 8
legendtkl
legendtkl/agentic-skill-router

syn-video-trim

Skill for trimming and cutting clips in the context of video files. Use when the user's task is specifically about trimming and cutting clips.

★ 8
legendtkl
legendtkl/agentic-skill-router

syn-video-transcode

Skill for transcoding codecs and resolutions in the context of video files. Use when the user's task is specifically about transcoding codecs and resolutions.

★ 8
legendtkl
legendtkl/agentic-skill-router

syn-video-thumbnail

Skill for extracting thumbnails and frames in the context of video files. Use when the user's task is specifically about extracting thumbnails and frames.

★ 8