smartGuidelines

This skill supports two workflows: conversational editing (chat, SDK scripts, automated pipelines) and GitOps sync (

.md

files in a Git repo synced to the API). Both produce the same output: well-structured guidelines available to all agents via

smartGuidelines

.

• Need to store data about contacts/companies → use entity-memory
• Need multi-agent coordination state (tasks, updates, issues) → use collaboration
• Need to plan a full Personize integration → use solution-architect

@personize/sdk

client.guidelines.list()

client.guidelines.update()

guideline_list

guideline_read

guideline_create

guideline_update

guideline_delete

client.guidelines.list()

guideline_list

governanceScope

client.guidelines.getStructure(id)

guideline_read(guidelineId)

governanceScope

client.guidelines.getSection(id, { header })

guideline_read(guidelineId, header)

client.guidelines.create(payload)

guideline_create(name, value, tags, description)

client.guidelines.update(id, payload)

guideline_update(guidelineId, value, updateMode, ...)

client.guidelines.delete(id)

guideline_delete(guidelineId)

client.guidelines.history(id)

guideline_history(guidelineId)

client.ai.smartGuidelines({ message })

ai_smart_guidelines(message)

governanceScope

is a read-only field returned on

guideline_list

and

guideline_read

(structure mode). It contains

alwaysOn

(boolean) and

triggerKeywords

(string array) — auto-inferred at save time. See the "Governance Scope" section below for details.

Response shape note:

client.guidelines.list()

returns

{ data: { actions: [...], count, nextToken? } }

— guidelines are in

data.actions

, not a top-level array. Iterate with

res.data?.actions || []

.

• If you're connected via MCP, use the MCP tool names (

  guideline_list

  ,

  guideline_update

  , etc.)
• If you're running via SDK, use the

  client.guidelines.*

  methods
• All workflows, rules, and best practices apply equally to both interfaces

• @personize/sdk

  installed

• PERSONIZE_SECRET_KEY

  env var set to an

  sk_live_...

  key

import { Personize } from '@personize/sdk';
const client = new Personize({ secretKey: process.env.PERSONIZE_SECRET_KEY! });

• Personize MCP server connected (SSE endpoint:

  https://agent.personize.ai/mcp/sse

  )
• API key provided via

  ?api_key=sk_live_...

  or OAuth configured
• Tools

  guideline_list

  ,

  guideline_read

  ,

  guideline_create

  ,

  guideline_update

  ,

  guideline_delete

  ,

  guideline_history

  , and

  ai_smart_guidelines

  are automatically available

1. Ask admin for topic, audience, and source material
2. Check for overlap with existing variables (

   client.guidelines.list()

   )
3. Draft with proper markdown structure (H1 title, H2 sections, actionable content)
4. Propose kebab-case name, tags, description
5. Show draft and ask for approval → create → verify with

   smartGuidelines

smartGuidelines

Full workflows, conversation patterns, and code: Read

reference/operations.md

Keywords follow RFC 2119: MUST = non-negotiable, SHOULD = strong default (override with stated reasoning), MAY = agent discretion.

1. MUST show the admin the proposed change before calling any mutating API -- because silent modifications erode trust and prevent catching errors before they reach production.
2. MUST include a descriptive

   historyNote

   on every update -- because change tracking enables audit trails, team collaboration, and rollback decisions.
3. MUST call

   list()

   and check for name/topic overlap before creating a new guideline -- because duplicate guidelines cause conflicting governance and confuse downstream agents.
4. SHOULD use section-level updates (

   section

   or

   appendToSection

   mode) over full

   replace

   -- because scoped edits reduce blast radius and allow concurrent editing; override only when structural reorganization requires full rewrite.
5. MUST call

   smartGuidelines()

   after any create or update to verify the change is visible to agents -- because the API call succeeding does not guarantee semantic retrievability.
6. SHOULD preserve the existing heading structure when updating a section -- because reorganizing adjacent sections creates unintended diffs and may break other agents' section-targeted queries.
7. SHOULD reuse existing tags before inventing new ones -- because inconsistent tagging fragments filtering and makes audit harder.
8. MUST write guideline content for agent consumption: explicit instructions, unambiguous language, headers that match likely

   smartGuidelines

   search queries -- because agents cannot infer intent from vague prose the way humans do.
9. SHOULD limit each guideline to a single concept or policy domain -- because mono-topic guidelines produce higher-relevance

   smartGuidelines

   matches and are easier to maintain.
10. MUST preserve the admin's voice and intent when improving structure or formatting -- because the admin owns the content; the agent is a writing assistant, not an editor-in-chief.
11. SHOULD check

    history()

    before editing and mention recent changes by others -- because concurrent edits without awareness cause overwrites in team environments.

1. Name = search query. Name guidelines as a developer would search for them:

   api-conventions

   not

   doc-v2-final

   . The name is the highest-weight signal in scoring.
2. Description = summary sentence. Write the description as if answering "what is this?":

   "REST API design rules: authentication, error handling, pagination, and naming conventions"

   . Descriptions feed directly into embedding and keyword scoring.
3. Tags = routing filters. Use consistent tags (

   engineering

   ,

   security

   ,

   sales

   ,

   onboarding

   ). Agents can filter by tags to narrow the pool before scoring.
4. H2 headers = section search targets. In full mode, the LLM can select individual sections by header. Write headers that match how people describe the topic:

   ## Error Response Format

   not

   ## Section 3.2

   .
5. Front-load key terms. Put the most important terms in the first 1000 characters of content — this preview is included in the embedding for semantic matching.

• alwaysOn — whether this guideline applies to virtually all tasks (e.g., core company values, universal compliance). alwaysOn guidelines are always included regardless of similarity score.
• triggerKeywords — action and domain words that trigger inclusion (e.g., "email", "pricing", "customer", "deploy"). Each matching keyword boosts the guideline's retrieval score.

┌─────────────────────────────────────────────────────┐
│                   GUIDELINES                         │
│              (Personize Variables)                   │
│                                                     │
│  sales-playbook    brand-voice    data-policy        │
│  icp-definitions   engineering-standards   ...       │
└────────┬─────────────────┬─────────────────┬────────┘
         │ smartGuidelines     │ SDK API          │ Sync
         ▼                 ▼                  ▼
┌────────────┐   ┌──────────────┐   ┌──────────────────┐
│ AI Agents  │   │ IDE/Dev Tool │   │ CI/CD Pipelines  │
│ (chat,     │   │ Claude Code  │   │ GitHub Actions   │
│  workflows │   │ Codex/Cursor │   │ Cron jobs        │
│  pipelines)│   │ Gemini/Copilot│  │ n8n workflows    │
└────────────┘   └──────────────┘   └──────────────────┘

entity-memory

collaboration

smartGuidelines()

smartDigest()

recall()

recall()

Full architecture guide: See the

collaboration

skill's

reference/architecture.md

for the complete three-layer model, composition patterns, and adoption path.

• Version history: Every update is tracked. Use

  client.guidelines.history(id)

  or

  guideline_history

  to review changes. Always start with

  limit: 1

  .
• Conflict avoidance: Use section-level updates (

  updateMode: 'section'

  ) — two people can safely update different sections concurrently. Read before writing.
• Attribution: Write attribution-rich

  historyNote

  values — include what changed, why, and who requested it.
• Ownership by tag:

  sales-*

  variables owned by sales team,

  engineering-*

  by engineering.

Full guide: Read

reference/collaboration.md

for version history patterns, conflict avoidance workflows, team patterns, and weekly review scripts.

• --require-approval

  : write proposals JSON, do not mutate guidelines

• --proposals-file

  : persist proposals to a reviewable path/artifact

• --min-confidence 0.60-0.75

  : skip weak AI extractions

• --max-updates N

  : cap per-run blast radius

• --dry-run

  : test extraction/routing with zero writes

• --no-auto-apply

  : require an explicit promote/apply step

1. Learn stage (non-mutating): run

   scan-git --require-approval --proposals-file ...

2. Apply stage (approved): run

   batch --file ...

   or re-run

   scan-git --autoApply

   with stricter bounds

reference/use-cases.md

reference/use-cases.md

reference/use-cases.md

Full guide: Read

reference/use-cases.md

for code examples, recipes, context engineering best practices, and layered context architecture.

governance/
└── variables/
    ├── sales-playbook.md
    ├── icp-definitions.md
    ├── brand-voice-guidelines.md
    └── pricing-rules.md

• Filename = variable name (without

  .md

  ). Use kebab-case.
• File content = variable value (markdown body after optional frontmatter).
• YAML frontmatter (optional) = tags and description:

---
tags: [sales, governance]
description: Sales team playbook and best practices
---

1. Read local files — Scan

   governance/variables/*.md

   , parse frontmatter and body.
2. Fetch remote state — Call

   client.guidelines.list()

   .
3. Diff by name — Match local filenames to remote variable names:
   • Local only → CREATE
   • Both exist, content differs → UPDATE
   • Both exist, content identical → SKIP
   • Remote only → DELETE (only with

     --delete

     flag)
4. Execute operations — Create/update/delete via SDK.
5. Print summary —

   Created: N, Updated: N, Deleted: N, Unchanged: N

• --delete

  is never implied. Remote-only variables are only removed when explicitly requested.

• --dry-run

  shows the full diff before any changes.
• Pull mode (

  --pull

  ) writes local files but never modifies remote variables.
• Frontmatter tags are preserved during update — only the value is compared.
• Version history: Every update is tracked with the commit message or a sync note.

1. Bootstrap:

   npx ts-node sync.ts --pull

2. Edit

   governance/variables/sales-playbook.md

3. Preview:

   npx ts-node sync.ts --dry-run

4. Push:

   npx ts-node sync.ts

5. Commit and push to Git — CI auto-syncs on merge to main

1. .github/workflows/governance-sync.yml

   — Syncs

   governance/variables/

   to Personize on push to main

2. .github/workflows/governance-learn.yml

   — Extracts learnings from

   src/

   commits on push to main

PERSONIZE_SECRET_KEY

• module-map.md — Every module's purpose, dependencies, danger zones
• high-risk-changes.md — What needs approval, migration rules
• coding-standards.md — Naming, patterns, file structure
• api-conventions.md — Endpoints, response format, auth
• security-standards.md — Auth, PII, API key handling

For Cursor: add the same block to `.cursorrules`.
For Copilot: add to `.github/copilot-instructions.md`.