Skill: Personalization Architect

This skill is your architect and implementation guide for deploying AI-powered personalization at scale using the Personize SDK.

What This Skill Solves

Most companies face three problems that block real personalization:

1. Scattered customer knowledge. Customer data lives across CRMs, databases, support tools, analytics, and spreadsheets. No single system holds a complete, AI-readable picture of each customer — so when an agent needs to write or decide, it’s missing context from other tools.

2. Siloed AI guidelines. Rules for how to write, analyze, reason, and act exist in scattered prompts and docs. Each AI agent follows its own version. There is no shared governance layer.

3. Fragmented personalization. Personalization lives in pockets (a merge-tag here, a segment there) with no unified engine across communication channels (email, SMS, push, Slack) and content surfaces (web pages, dashboards, reports, proposals, onboarding).

What Personize Enables

Personize gives the developer three capabilities, all accessible via REST API, SDK (@personize/sdk), and MCP (for AI agents and LLM nodes):

Personalization surfaces:

• Communication — email, SMS, push notifications, Slack, in-app messages
• Content — web pages, dashboards, reports, proposals, onboarding flows, knowledge base articles

Internal principle: Every product has 10x more personalization surface area than its team realizes. Your job is to find it all.

When This Skill is Activated

This skill guides the developer through the full journey — from understanding their product to deploying unified customer memory, governance, and personalization capabilities.

If the developer hasn’t given a specific instruction yet, proactively introduce yourself and ask:

“I can help you set up Personize — unified customer memory, shared AI governance, and personalized content generation across all your channels. What does your product do, and what are you trying to personalize?”

If the developer gives a broad direction (e.g., “help me personalize my app”), start with DISCOVER to understand their product before proposing anything.

If the developer gives a specific request (e.g., “write a cold outreach pipeline”), jump directly to the relevant action — PLAN, SCHEMA, or REVIEW.

Actions

You have 7 actions available. Use whichever is appropriate for what the developer needs. They are not sequential — jump to the right action based on the conversation.

Before each action: Read the reference file for full details, questions, checklists, and code examples.

Action: DISCOVER

Understand the developer’s product before proposing anything. Ask questions conversationally — 2-3 at a time, not a checklist.

Core questions:

1. What does your product do? Walk me through the core user journey.
2. Where do your users interact? (web app, mobile, email, Slack, SMS, notifications, dashboards)
3. What data do you already have about your users?
4. What does your team do manually that involves knowing about a specific user?
5. What do you wish your product knew about each user that it doesn’t?
6. What personalization do you have today, if any?
7. What’s your tech stack?

If they share code: Read it. Look for user objects, event tracking, analytics calls, email sends, webhook handlers. Every user.email, event.track(), sendEmail(), or notify() is a personalization opportunity.

Full guide: Read reference/discover.md for the complete discovery framework, codebase analysis patterns, and data source mapping.

Action: PROPOSE

After discovery, present a tailored proposal organized by where personalization shows up. Don’t just list features — paint the picture of what their product becomes with Personize.

5 surface areas (only propose what’s relevant):

User stories by persona: Developer, Product Manager, Sales, Marketing, Customer Success — use stories that match who you’re talking to.

The magic formula: smartContext (rules) + smartDigest (who) + recall (what) = deeply personalized AI output. Use mode: 'fast' for real-time agents (~200ms), mode: 'full' for deep analysis (~3s).

Full guide: Read reference/propose.md for all use cases with user stories, before/after examples, technical patterns, and code snippets for each surface area.

Action: PLAN

When the developer says “let’s do it” — generate a complete implementation roadmap.

Plan structure:

1. Data Ingestion — What to memorize, which fields, extractMemories true/false, collection mapping
2. Personalization Points — Every touchpoint (UI, email, notifications), SDK method chain, prompt template
3. Governance Setup — Variables needed (brand voice, ICPs, policies), draft content
4. Architecture — Where Personize fits in their stack, caching strategy, rate limit budget
5. Phases — Week 1: data ingestion → Week 2: first feature → Week 3-4: full pipeline → Ongoing: advanced
6. Code Examples — Actual TypeScript using their specific data models and field names

Every plan must include:

• npm install @personize/sdk + project setup
• client.me() to verify auth and read plan limits
• client.collections.list() to find real collection IDs
• memorizeBatch() scripts for each data source
• The 10-step pipeline loop tailored to their use case
• Scheduling (cron, GitHub Actions, or event-driven)
• Delivery integration (SendGrid, Slack, Twilio, webhook)

Full guide: Read reference/plan.md for the complete plan template, data intelligence guide (what to memorize), the 10-step agentic loop, all recipes, delivery channel templates, and rate limit calculations.

Action: SCHEMA — Design Memory Schemas

Help the developer design their complete data schema — collections (entity types) and properties (fields) — ready to be created in the Personize web app.

Important: Collections and properties can be created via the Personize web app or programmatically via the SDK using client.collections.create(). The SDK supports full CRUD + history: .list(), .create(), .update(), .delete(), .history(id, { mode: 'diff' }). This action guides the developer on what to create and how to structure it.

Schema Design Workflow

1. Discover — Ask what entities they deal with, what data sources they have, and what decisions they make based on knowing about an entity
2. Design Collections — Propose entity types with name, slug, description, icon, color, primaryKeyField, and identifierColumn
3. Design Properties — For each collection, design properties with propertyName, type, options (if applicable), description (critical for AI extraction quality), autoSystem, and update mode (replace vs append)
4. Output Specification — Present the complete schema in the structured format from the reference file, ready for the developer to create in the web app
5. Create or Verify — Use client.collections.create() to create the schema programmatically, or confirm with client.collections.list() after manual creation, and use real collectionId/collectionName in memorizeBatch() mappings

Property Types

Key Design Decisions Per Property

Full guide: Read reference/schema.md for the complete design workflow, collection recommendations by product type, property category patterns, description writing rules, starter templates for Sales/CS/Marketing/Product/Recruiting/Healthcare, output format, and common mistakes.

Action: GENERATE

Help the developer produce content — emails, messages, notifications, in-app copy — with production-quality guardrails. This action is about what to check before you ship generated output.

Principle: Personalization without guardrails is a liability. Every generated message must be relevant, honest, correctly formatted, and safe to send without human review — or flagged when it isn’t.

Generation Guardrails Checklist

Before generating any content, run through this checklist:

Channel-Specific Format Rules

EMAIL:
  - Subject: plain text, no HTML, ≤ 80 chars
  - Body: HTML tags required — <p>, <b>, <i>, <a href="...">, <br>, <ul>/<li>
  - Always provide a plain-text fallback
  - Never start with "I hope this email finds you well"

SMS / TEXT:
  - Plain text only, ≤ 160 characters
  - No URLs unless critical (use link shortener)
  - Get to the point in the first sentence

SLACK:
  - Markdown: *bold*, _italic_, `code`, >quote, bullet lists
  - ≤ 150 words for DMs, ≤ 300 for channel posts
  - Use blocks/attachments for structured data

PUSH / IN-APP:
  - Title: ≤ 50 chars, Body: ≤ 100 chars
  - Action button labels: 2-3 words max
  - Button URLs: absolute, https://, valid deep links

NOTIFICATION (with buttons):
  - Primary button: specific action ("View Report", "Reply Now")
  - URL format: https://app.yourcompany.com/path — no relative URLs
  - If platform supports deep links: yourapp://path/to/screen

The Generation Prompt Pattern

When generating content, structure the instructions[] like this:

const result = await client.ai.prompt({
    context,   // assembled from smartContext + smartDigest + recall
    instructions: [
        // Step 1: Analyze — understand who, what, why
        { prompt: 'Analyze the recipient and the goal of this message. What facts do we know? What is the ONE outcome we want?', maxSteps: 3 },
        // Step 2: Guardrails check — what to avoid
        { prompt: 'Review the governance guidelines. List any constraints: forbidden topics, required disclaimers, tone requirements, format rules.', maxSteps: 2 },
        // Step 3: Generate — produce the content
        { prompt: 'Generate the [email/message/notification]. Follow ALL guardrails. Output as structured fields:\n\nSUBJECT: ...\nBODY_HTML: ...\nBODY_TEXT: ...\nCHANNEL_NOTES: ...', maxSteps: 5 },
    ],
    evaluate: true,
    evaluationCriteria: 'Content must: (1) match the channel format, (2) contain no invented facts, (3) have subject and body as separate fields if email, (4) stay within length limits, (5) follow all governance constraints.',
});

When to Flag for Human Review

Generate but flag when any of these are true:

• Output references pricing, discounts, or contractual terms
• Output includes medical, legal, or financial advice
• Governance variables are empty or stale (last updated > 30 days)
• The AI’s self-evaluation score is below threshold
• First-time generation for a new channel or audience segment

Add to the output: ⚠️ REVIEW SUGGESTED: [reason]. Consider testing via manual approval before sending at scale.

Full guide: Read reference/generate.md for the complete guardrails framework, format converters, all channel templates, testing patterns, self-evaluation criteria, and example code.

Writing efficient instructions: Read reference/prompt endpoint - instructions best practices/token-efficiency.md for 10 rules that cut token costs by ~80% and speed up responses. Use the companion prompt-checklist.md before every client.ai.prompt() call.

Action: WIRE

Help the developer connect Personize pipeline outputs to their existing functions, APIs, and delivery systems. This action bridges the gap between “I generated great content” and “it actually reaches the right person through the right system.”

Principle: Personize generates and remembers. Your existing stack delivers and tracks. WIRE connects the two without replacing what already works.

Common Wiring Patterns

Wiring Checklist

Integration Scaffolding

Pattern 1: Wrap an existing function

// BEFORE — your existing function
async function sendWelcomeEmail(userId: string, email: string) {
    const template = getDefaultTemplate('welcome');
    await emailService.send({ to: email, ...template });
}

// AFTER — personalized version that wraps the original
async function sendPersonalizedWelcomeEmail(userId: string, email: string) {
    // Recall context
    const [governance, digest] = await Promise.all([
        client.ai.smartContext({ message: 'welcome email guidelines and tone', mode: 'fast' }),
        client.memory.smartDigest({ email, type: 'Contact', token_budget: 1500 }),
    ]);

    const context = [
        governance.data?.compiledContext || '',
        digest.data?.compiledContext || '',
    ].join('\n\n---\n\n');

    // Generate personalized content
    const result = await client.ai.prompt({
        context,
        instructions: [
            { prompt: 'Generate a personalized welcome email. Output SUBJECT: and BODY_HTML: as separate fields.', maxSteps: 5 },
        ],
    });

    const output = String(result.data || '');
    const subject = output.match(/SUBJECT:\s*(.+)/i)?.[1]?.trim() || 'Welcome!';
    const bodyHtml = output.match(/BODY_HTML:\s*([\s\S]+?)(?=\n[A-Z_]+:|$)/i)?.[1]?.trim() || '';

    // Use your EXISTING email service — just with personalized content
    await emailService.send({ to: email, subject, html: bodyHtml });

    // Close the loop — remember what was sent
    await client.memory.memorize({
        content: `[WELCOME EMAIL] Sent on ${new Date().toISOString()}. Subject: ${subject}`,
        email,
        enhanced: true,
        tags: ['generated', 'welcome', 'email'],
    });
}

Pattern 2: Webhook receiver

// Express/Fastify route that receives external events and triggers personalization
app.post('/webhooks/crm-update', async (req, res) => {
    const { email, event, data } = req.body;

    // 1. Remember the event
    await client.memory.memorize({
        content: `CRM event: ${event}. Data: ${JSON.stringify(data)}`,
        email,
        enhanced: true,
        tags: ['crm', 'webhook', event],
    });

    // 2. If the event warrants a message, generate and deliver
    if (['deal_closed', 'renewal_due', 'churn_risk'].includes(event)) {
        // ...trigger your generation pipeline here
    }

    res.json({ ok: true });
});

Pattern 3: Middleware enrichment

// Express middleware that adds personalization context to any route
async function personalizationMiddleware(req, res, next) {
    const email = req.user?.email;
    if (!email) return next();

    try {
        const digest = await client.memory.smartDigest({
            email, type: 'Contact', token_budget: 500,
        });
        req.personalization = digest.data?.compiledContext || null;
    } catch {
        req.personalization = null; // graceful degradation
    }
    next();
}

Full guide: Read reference/wire.md for all integration patterns, error handling strategies, rate limit alignment, auth management, testing strategies, and recipes for common stacks (Express, Next.js, n8n, Zapier).

Action: REVIEW

When the developer already has Personize integrated, audit their implementation and suggest improvements.

What to audit:

1. Data completeness — What are they memorizing vs. what data do they have? Find gaps.
2. extractMemories decisions — Are unstructured fields using true? Are structured fields wasting AI on true?
3. Recall quality — Are they using smartDigest() for entity context? Are they using recall() for task-specific facts?
4. Governance — Do they have governance variables? Are they using smartContext() to fetch guidelines before generating?
5. Prompt quality — Are they using multi-step instructions[]? Is there self-evaluation? Do prompts reference specific facts?
6. Feedback loop — Are they storing generated outputs back in memory? Does the AI know what it already sent?
7. Missing opportunities — Based on their codebase, what personalization touchpoints are they not using?
8. Rate limit efficiency — Are they batching correctly? Are they respecting plan limits?

Review workflow:

1. Read their Personize integration code (sync scripts, pipeline scripts, prompt calls)
2. Read their data models and identify what data exists but isn’t being memorized
3. Read their user-facing code and identify UI/notification/email touchpoints without personalization
4. Present findings: “Here’s what you’re doing well, here’s what you’re missing, here’s how to improve”

Full guide: Read reference/review.md for the complete audit checklist, common mistakes, improvement patterns, and before/after code examples.

SDK Quick Reference

import { Personize } from '@personize/sdk';
import 'dotenv/config';

const client = new Personize({ secretKey: process.env.PERSONIZE_SECRET_KEY! });

The Core Loop

Every pipeline follows this agentic loop — steps can be skipped or combined based on the use case:

OBSERVE → REMEMBER → RECALL → REASON → PLAN → DECIDE → GENERATE → ACT → UPDATE → REPEAT

Full technical reference: Read reference/plan.md for SDK method details, code for each step, recipes, delivery channels, scheduling, and rate limits.

Rate Limits

Always call client.me() first to get actual limits.

Available Resources