SF-AI-Agentforce-ConversationDesign Skill

"Users don't fail conversations — conversations fail users."

Conversation design is the discipline of crafting agent interactions that feel natural, resolve issues efficiently, and gracefully handle the unexpected. This skill brings structured conversation design methodology to Salesforce Agentforce, combining industry frameworks (Google, IBM, PatternFly) with Salesforce-specific implementation patterns.

⚡ Quick Start

New agent? Start here:

• Design your persona → Persona Design Guide

• Architect your topics → Topic Architecture Guide

• Write instructions → Instruction Writing Guide

• Score your design → Quality Scorecard

Existing agent needs improvement? Start here:

• Run the Quality Scorecard assessment

• Review Anti-Patterns for quick wins

• Build an Improvement Plan

📚 Document Map

Tier 1 — Start Here

Document Purpose

This file (SKILL.md) Scoring rubric, methodology overview, core principles

README.md Quick start, prerequisites, getting started

Tier 1.5 — Reference Guides (Extracted)

Document Purpose

Scoring Rubric Full 8-category detailed criteria tables

Quality Assessment Assessment process + quick health check

Continuous Improvement Iteration cycle, KPIs, utterance analysis

Tier 2 — Design Guides

Document Purpose

Persona Design Guide How to define agent personality, tone, and communication style

Topic Architecture Guide Bottom-up topic design, classification descriptions, scope boundaries

Instruction Writing Guide Three-level instruction framework with do's, don'ts, and examples

Tier 3 — Reference Resources

Document Purpose

Conversation Patterns IBM's 5 patterns mapped to Agentforce implementation

Industry Frameworks Google, IBM, PatternFly, Salesforce framework mappings

Anti-Patterns Common mistakes with examples and fixes

Guardrail Hierarchy Four-layer guardrail model for safety

Escalation Patterns Trigger catalog and Omni-Channel routing

Quality Metrics KPI definitions, benchmarks, measurement methods

Tier 4 — Templates & Examples

Document Purpose

Persona Document Fill-in persona template

Topic Architecture Topic mapping worksheet

Utterance Library Structured utterance collection template

Escalation Matrix Escalation decision matrix

Quality Scorecard 120-point assessment template

Improvement Plan Prioritized improvement template

Service Agent Persona Example: SaaS customer service persona

Retail Topic Architecture Example: retail agent topic hierarchy

Healthcare Escalation Example: healthcare escalation matrix

🏆 Scoring System (120 Points)

See references/scoring-rubric.md for the full per-criterion breakdown of all 8 categories.

Category Summary

Category Points Weight

1 Persona & Tone 15 12.5%

2 Topic Architecture 20 16.7%

3 Instruction Quality 20 16.7%

4 Dialog Flow Design 15 12.5%

5 Utterance Coverage 15 12.5%

6 Escalation Design 15 12.5%

7 Guardrails & Safety 10 8.3%

8 Continuous Improvement 10 8.3%

TOTAL 120 100%

Grade Scale

Grade Score Range Description

A 108-120 Production-ready, exceptional design

B 96-107 Good design, minor gaps

C 84-95 Adequate, needs targeted improvements

D 72-83 Significant gaps, not production-ready

F <72 Major redesign required

🎭 Persona Design

A persona defines your agent's personality, communication style, and behavioral constraints — the foundation for consistent, brand-aligned interactions.

Persona Components

• Identity — Name, role, department, target audience

• Tone Register — Casual, neutral, or formal (Agentforce setting)

• Personality Traits — 3-5 traits that shape response style

• Communication Style — Sentence length, vocabulary level, empathy patterns

• Limitations — What the agent explicitly will not do

• Messages — Welcome message and error/fallback message (<=800 chars each)

Salesforce Implementation

Agent Builder → Agent Settings → Instructions (Agent-Level) Agent Builder → Agent Settings → Tone (Casual/Neutral/Formal) Agent Builder → Channels → Welcome Message / Error Message

The persona lives primarily in agent-level instructions. Write them like training a new employee on Day 1 — focus on who they are and how they communicate, not on specific task procedures.

Deep Dive: Persona Design Guide | Template: Persona Document | Example: Service Agent Persona

🏗️ Topic Architecture

Topics group related actions under classification descriptions for routing. Use bottom-up design: list all actions → group by user intent → write classification descriptions → test for semantic distinctness.

Architecture Rules

Rule Guideline Rationale

Topic count <=10 per agent More topics = more classification ambiguity

Actions per topic <=5 per topic Keeps topics focused and testable

Classification overlap <30% shared vocabulary Prevents misrouting between similar topics

Scope boundaries Explicit out-of-scope list Prevents hallucination on unknown intents

Classification Descriptions

The single most important text in your agent design — they determine routing accuracy.

✅ GOOD: "This topic handles questions about existing order status, including tracking information, estimated delivery dates, and order modification requests. It does NOT handle new order placement or returns."

❌ BAD: "Order stuff"

Test: Can you read two descriptions and immediately tell which utterance belongs where?

Deep Dive: Topic Architecture Guide | Template: Topic Architecture | Example: Retail Topic Architecture

✍️ Instruction Writing

Instructions operate at three levels: Agent-level (persona, global rules, 200-500w), Topic-level (workflow logic, 100-300w), Action-level (when/how to invoke, 50-150w).

Core Principles

• Guidance over determinism — Guide reasoning, don't hard-code every decision. "Prioritize empathy and escalate if unresolved within 2-3 exchanges" vs scripting every anger keyword.

• Positive framing — "Always verify identity before accessing account details" not "Don't ever access without verifying."

• Business principles, not decision trees — If your instruction contains if...then...else with thresholds, it belongs in Flow/Apex.

• Knowledge over hard-coding — Use Knowledge actions (RAG) for policies, don't inline policy text in instructions.

Deep Dive: Instruction Writing Guide

🔄 Dialog Flow Patterns

Every conversation follows a six-phase lifecycle: Greeting → Classification → Gathering → Processing → Response → Close.

Key design rules:

• Progressive disclosure: Max 2-3 choices per turn. If more options exist, ask a qualifying question first.

• Context preservation: Reference prior turns, avoid re-asking for information already provided.

• Error recovery: Define clarification prompts, disambiguation paths, and graceful fallbacks for every phase.

• Explicit closing: Summarize what was accomplished, offer follow-up, farewell appropriate to tone.

📝 Utterance Design

Utterances are test cases for your topic architecture — they validate that classification descriptions route correctly.

Categories & Targets

Category Purpose Target per Topic

Happy Path Primary intent, clear phrasing

=5

Synonym Alternate vocabulary

=3

Edge Case Ambiguous, multi-intent

=2

Adversarial Injection, manipulation (global)

=5

Out-of-Scope Should NOT match (global)

=5

Process: Start with real data (CRM cases, chat logs) → brainstorm synonyms → add edge cases → include adversarial → test in Testing Center → iterate on failures.

Template: Utterance Library

🚨 Escalation Design

Escalation is not failure — it's a safety net ensuring customers always reach resolution.

Trigger Catalog

Trigger Type Condition Priority

Explicit Customer requests human agent P1

Safety Self-harm, threats, emergency, legal P1

Sentiment Customer frustration or anger P2

Complexity

6 turns without resolution P2

Policy Request exceeds agent authority P2

Technical Action failure, system error P3

When escalating, pass: conversation transcript, customer identity, issue summary, actions taken, and escalation reason. Agentforce provides a pre-built Escalation Topic that routes via Omni-Channel.

Deep Dive: Escalation Patterns | Template: Escalation Matrix

🛡️ Guardrails & Safety

Safety operates through four layers: Einstein Trust Layer (platform — toxicity detection, PII masking, automatic), Topic Classification (scope boundaries as first defense), Instructions (behavioral constraints — "never provide legal/medical advice"), Flow/Apex (deterministic business rule enforcement).

Critical Rule: Never rely on instructions alone for safety-critical decisions. Instructions are probabilistic. Financial limits, compliance checks, and approval gates MUST be in Flow or Apex.

Deep Dive: Guardrail Hierarchy

📊 Quality Assessment & Continuous Improvement

See references/quality-assessment.md for the full assessment process and 5-question quick health check.

See references/continuous-improvement.md for the Monitor → Analyze → Fix → Retest → Deploy iteration cycle, KPI targets, and utterance analysis process.

⚠️ Anti-Patterns

Anti-Pattern Impact Fix

1 Negative instructions Confuses LLM reasoning Reframe positively

2 Over-constraining Rigid, brittle responses Use guiding principles

3 Business rules in instructions Inconsistent enforcement Move to Flow/Apex

4 Monolithic topics Poor classification accuracy Split into focused topics

5 Overlapping classifications Misrouting Make descriptions distinct

6 Missing escalation paths Dead-end conversations Define triggers for all failure modes

7 No utterance testing Untested classification Build utterance library

8 Hard-coded policies Stale information Use Knowledge actions

9 Ignoring context Repetitive re-asking Leverage conversation state

10 Happy-path-only testing Fragile in production Test edge cases and adversarial

Deep Dive: Anti-Patterns — Full examples with before/after fixes.

🔗 Chain Integration

This skill is the first step in the Agentforce development chain:

From This Skill To Skill What's Handed Off

Topic architecture sf-ai-agentscript Topic names, actions, classification descriptions

Instruction sets sf-ai-agentscript Three-level instructions for agent script

Utterance library sf-ai-agentforce-testing Test cases for multi-turn testing

Escalation matrix sf-flow Escalation flow logic

Action definitions sf-apex / sf-flow Action implementation requirements

📎 Credits & References

• Google Conversation Design Guidelines

• IBM Natural Conversation Framework

• Red Hat PatternFly AI Design System

• Salesforce Conversational AI Design Guide

• Salesforce Architect: Agentic Patterns & Taxonomy

See CREDITS.md for full attribution.