Skill: Governance

These are the rules, policies, and best practices that every AI agent in your organization must follow. Always check Guidelines before generating content, making decisions, or taking actions. One update here → every AI tool in your org gets smarter.

Guidelines are stored as markdown documents and are automatically available to all agents via smartGuidelines . Use this skill to read, create, update, and manage them.

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 .

When NOT to Use This Skill

• 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

Actions

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

Action When to Use Reference

CREATE Admin shares content or wants a new guideline reference/operations.md

UPDATE Admin wants to modify an existing guideline (section, append, replace) reference/operations.md

IMPROVE Admin wants to clean up, restructure, or improve guideline quality reference/operations.md

AUDIT A factual change affects multiple guidelines (pricing, branding, policy) reference/operations.md

VERIFY Confirm agents can see the updated content via smartGuidelines

reference/operations.md

ONBOARD First-time user with 0-2 guidelines — guide them through setup reference/onboarding.md

Before each action: Read the reference file for full workflows, conversation patterns, and code examples.

Works With Both SDK and MCP — One Skill, Two Interfaces

This skill works identically whether the LLM accesses guidelines via the SDK (code, scripts, IDE agents) or via MCP (Claude Desktop, ChatGPT, Cursor MCP connection).

Interface How it works Best for

SDK (@personize/sdk ) client.guidelines.list() , client.guidelines.update() , etc. Scripts, CI/CD, IDE agents, recipes

MCP (Model Context Protocol) guideline_list , guideline_read , guideline_create , guideline_update , guideline_delete tools Claude Desktop, ChatGPT, Cursor, any MCP-compatible client

MCP tools map 1:1 to SDK methods:

SDK Method MCP Tool Purpose

client.guidelines.list()

guideline_list

List all guidelines (includes governanceScope )

client.guidelines.getStructure(id)

guideline_read(guidelineId)

Get section headings (TOC) + governanceScope

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

guideline_read(guidelineId, header)

Get section content

client.guidelines.create(payload)

guideline_create(name, value, tags, description)

Create new guideline

client.guidelines.update(id, payload)

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

Update guideline

client.guidelines.delete(id)

guideline_delete(guidelineId)

Delete guideline

client.guidelines.history(id)

guideline_history(guidelineId)

View change history

client.ai.smartGuidelines({ message })

ai_smart_guidelines(message)

Verify/fetch guidelines

smartGuidelines Mode and Model

smartGuidelines has two modes and an optional model override:

Mode How it works Latency Cost When to use

fast

Embedding-based routing only — no LLM ~200ms 0.1 credits/call Real-time agents, loops, context injection

deep

LLM selects and composes guidelines ~3s 0.5 credits/call First call, complex queries, deep analysis

Mode rename: 'full' was renamed to 'deep' in the SDK types and API. If you see mode: 'full' in older code, update it to mode: 'deep' .

1 credit = $0.01. Use fast in production pipelines — it handles the majority of cases well at 5× lower cost.

// Fast — embedding-only, no LLM overhead (default for real-time) const guidelines = await client.ai.smartGuidelines({ message: 'cold email tone and constraints', mode: 'fast', });

// Deep — LLM-based routing, optional model override const guidelines = await client.ai.smartGuidelines({ message: 'cold email tone and constraints', mode: 'deep', model: 'anthropic/claude-sonnet-4-6', // optional — override the LLM used for routing });

No intelligence tiers — smartGuidelines does not use the basic /pro /pro_fast /ultra tier system (those are for memorize /batch-memorize only).

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 || [] .

When reading this skill document:

• 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

Prerequisites

SDK Mode

• @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! });

MCP Mode

• 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

What Guidelines Are

Guidelines are organization-wide documents — policies, best practices, playbooks, checklists, technical manuals, how-tos — stored as markdown. Once saved, they are automatically available to all agents in the organization via client.ai.smartGuidelines() . When any agent asks smartGuidelines a question like "how should I write a cold email?", it retrieves the relevant guidelines and includes them as context.

Examples: sales-playbook , brand-voice-guidelines , icp-definitions , data-handling-policy , engineering-standards , incident-response-runbook , known-bugs-and-workarounds , pricing-rules

Action Summaries

CREATE — Draft a New Guideline

• Ask admin for topic, audience, and source material

• Check for overlap with existing variables (client.guidelines.list() )

• Draft with proper markdown structure (H1 title, H2 sections, actionable content)

• Propose kebab-case name, tags, description

• Show draft and ask for approval → create → verify with smartGuidelines

UPDATE — Modify Existing Guidelines

Choose the right update mode:

Scope Mode When

Single section section

"Update the Cold Email section"

Add to a section appendToSection

"Add a new rule to the Email Rules section"

Add new section append

"Add a GDPR section to the data policy"

Full rewrite replace

"Completely rewrite this variable"

Workflow: find variable → read structure → read target section → draft update → show before/after → apply with historyNote

IMPROVE — Enhance Writing Quality

Read content → analyze structure/clarity/formatting/completeness → draft improved version → show summary of changes → apply

AUDIT — Cross-Guideline Accuracy Scan

Admin reports a factual change → list ALL guidelines → search for old fact → draft corrections → present batch of proposed changes → apply each with historyNote

VERIFY — Confirm Agent Visibility

After any create/update: call smartGuidelines with relevant query → confirm the updated content appears.

Full workflows, conversation patterns, and code: Read reference/operations.md

Constraints

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

• 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.

• MUST include a descriptive historyNote on every update -- because change tracking enables audit trails, team collaboration, and rollback decisions.

• MUST call list() and check for name/topic overlap before creating a new guideline -- because duplicate guidelines cause conflicting governance and confuse downstream agents.

• 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.

• 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.

• 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.

• SHOULD reuse existing tags before inventing new ones -- because inconsistent tagging fragments filtering and makes audit harder.

• 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.

• 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.

• 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.

• SHOULD check history() before editing and mention recent changes by others -- because concurrent edits without awareness cause overwrites in team environments.

Guideline Quality at Scale

smartGuidelines uses hybrid semantic scoring (embeddings + keyword matching + governance scope boosts) to select the most relevant guidelines for each task. Its quality is directly affected by how guidelines are structured.

Fewer, Richer Guidelines > Many Small Ones

The retrieval pipeline has dynamic caps on how many guidelines it returns per query (~7-12 critical, ~5-8 supplementary, scaling with total count). This means:

Guideline count Retrieval quality Notes

1-20 Excellent LLM-based routing sees everything

20-50 Very good Embedding-based fast mode works well

50-80 Good Quality starts to depend on naming/tagging discipline

80+ Requires care Must follow all rules below to maintain quality

MUST prefer consolidating related content into fewer, well-structured guidelines over creating many small ones — because each guideline competes for limited retrieval slots, and a single rich document with clear H2 sections is retrieved more reliably than five fragments. The section-level extraction in full mode already supports delivering only the relevant sections from a large guideline.

Examples of consolidation:

Instead of these 5 guidelines... Create 1 guideline with sections

api-auth-rules , api-error-format , api-pagination , api-naming , api-versioning

api-conventions with H2 sections: Auth, Errors, Pagination, Naming, Versioning

bug-fix-process , known-bugs-list , debugging-tips

debugging-playbook with H2 sections: Process, Known Issues, Tips & Patterns

react-style-guide , react-testing , react-performance

react-standards with H2 sections: Style, Testing, Performance

Writing for Maximum Retrievability

• 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.

• 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.

• Tags = routing filters. Use consistent tags (engineering , security , sales , onboarding ). Agents can filter by tags to narrow the pool before scoring.

• 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 .

• 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.

When to Split vs. Merge

Split when topics serve different audiences or are queried in completely different contexts (e.g., sales-playbook and engineering-standards should stay separate even if both are long).

Merge when topics are often needed together for the same task (e.g., API auth rules and API error formats are almost always needed together when building endpoints).

Governance Scope: alwaysOn and triggerKeywords

Every guideline is automatically analyzed at save time to determine:

• 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.

These are inferred by LLM and stored automatically. Keep alwaysOn guidelines to a maximum of 2-3 — each one consumes a retrieval slot on every query.

How It Works (Architecture)

┌─────────────────────────────────────────────────────┐ │ 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 │ └────────────┘ └──────────────┘ └──────────────────┘

Guidelines are one layer of the three-layer agent operating model — together with Memory (entity-memory skill) and Workspace (collaboration skill). Every agent should call smartGuidelines() for rules, smartDigest() /recall() for entity knowledge, and recall() by workspace tags for coordination — all before acting. Guidelines provide the governance that makes the other two layers safe to use autonomously.

Full architecture guide: See the collaboration skill's reference/architecture.md for the complete three-layer model, composition patterns, and adoption path.

Team Collaboration

When multiple people manage guidelines, follow these practices:

• 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.

Advanced: Multi-Organization Governance

DO NOT raise this topic proactively. Most users have a single organization. Only discuss multi-org governance when the user explicitly describes managing multiple orgs (e.g., agency with client brands, platform with per-customer orgs) and already has a working Personize integration.

Guidelines are per-organization — each org has its own isolated set. In multi-org deployments:

• Shared policies, separate execution. If all orgs must follow the same compliance rules, maintain a canonical source (Git repo, template) and sync it to each org separately using sync.ts or the SDK. There is no cross-org guideline inheritance.

• Per-org brand voice. Each org's brand-voice guideline should reflect that org's identity — this is the primary reason to use multi-org instead of a single org with tags.

• Audit independently. Use client.guidelines.history(id) per org. Changes in one org do not affect others.

• Same skill, different key. All governance workflows in this skill work identically — just initialize the SDK with the target org's API key.

Production Guardrails (Recommended, Opt-in)

For shared/production deployments, add guardrails to autonomous learning. These are recommendations and are off by default so existing accounts keep working.

• --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

Recommended two-stage CI pattern:

• Learn stage (non-mutating): run scan-git --require-approval --proposals-file ...

• Apply stage (approved): run batch --file ... or re-run scan-git --autoApply with stricter bounds

This skill keeps auto-apply available for teams that want speed, but production defaults SHOULD include a review path.

Use Cases & Deployment Patterns

This skill supports three deployment patterns beyond conversational editing:

Use Case What It Does Reference

IDE-Integrated Guidelines Developers read/write guidelines from Claude Code, Codex, Cursor, Copilot reference/use-cases.md

Autonomous Learning LLMs auto-extract learnings from incidents, code reviews, conversations reference/use-cases.md

Document Ingestion Batch-import policies from folders of docs (wikis, Notion, Google Docs) reference/use-cases.md

Full guide: Read reference/use-cases.md for code examples, recipes, context engineering best practices, and layered context architecture.

Available Resources

Resource Contents

reference/operations.md

Full workflows for CREATE, UPDATE, IMPROVE, AUDIT, VERIFY + conversation patterns + SDK code

reference/collaboration.md

Version history, conflict avoidance, attribution, team patterns, weekly review

reference/onboarding.md

First-time setup, starter templates (brand voice, ICP), handling existing content

reference/use-cases.md

IDE integration, autonomous learning, document ingestion, context engineering

reference/team-setup.md

Team onboarding runbook for SDK + Skills + MCP + governance CI guardrails

recipes/ide-governance-bridge.ts

Fetch guidelines from IDE, push learnings back

recipes/auto-learning-loop.ts

Automatically extract and persist learnings

recipes/document-ingestion.ts

Batch-import policies from a folder of documents

templates/project-governance-setup.md

Step-by-step guide for governance-aware projects

templates/context-engineering-guide.md

Deep dive on context engineering principles

sync.ts

GitOps sync script — push local .md files to Personize variables API

github-action.yml

GitHub Actions workflow for auto-syncing on push

Variables as Code (GitOps Sync)

For teams that prefer managing guidelines in Git, the included sync.ts script syncs local .md files to Personize variables. Filename = variable name, file content = variable value.

Quick start:

npx ts-node sync.ts --pull # Bootstrap: download remote → local npx ts-node sync.ts --dry-run # Preview changes npx ts-node sync.ts # Sync (create + update, never delete) npx ts-node sync.ts --delete # Sync with deletion of remote-only

CI integration: Two GitHub Actions workflows auto-sync on push (governance-sync.yml ) and auto-extract learnings from code commits (governance-learn.yml ).

Full guide: Read reference/team-setup.md for the complete GitOps workflow, folder conventions, YAML frontmatter format, sync algorithm, CI integration YAML, safety guarantees, pull mode, auto-learning from commits, IDE bridge setup, and the step-by-step team onboarding runbook.