Voicenter Bot Intent Detail Author

Skill 2 — Intent Detail Author

This skill fills the language-heavy fields of an Agent Spec's section 5 — the per-intent content that determines how the bot collects slots, what it says during execution, and what it does post-execution. It is one of three skills in the Voicenter Bot generation pipeline:

• Skill 1 (Agent Spec Designer): structural design via interview → fills sections 1, 2, 3, 4, 4.5, section 6 (initial), section 7 (init); creates section 5 stubs marked [structural].
• Skill 2 (this skill): language-heavy per-intent content → fills section 5 entries, marks them [detailed]; updates 4.5.3, 6.1, 7.3, 7.4, 7.5.
• Skill 3 (JSON Assembler & Publish): mechanical projection of the spec into Bot JSON wire format.

Source of truth is the spec markdown. No skill invents values.

---

1. Required reading at invocation

Before touching the spec, load context from these references.

| Read | Why | |---|---| | Doc 1 §6.B.2 — IntentConfig.prompts.validationPrompt | Skill 2 authors this field | | Doc 1 §6.B.3 — IntentResponces.Configuration | Per-RT Configuration shape Skill 2 fills | | Doc 1 §11 — RT=1/2/3/4 cross-RT field summary | Step 3 RT-specific authoring | | Doc 1 §11.2 — RT=2 apisilencebehaviour pairing | Step 3 RT=2 authoring | | Doc 1 §13 — Mustache + variable categories | Mustache resolvability check | | Doc 1 §14.3.2 — Conversation Routines style | Iron rule for validationPrompt + intentInstructions | | Doc 1 §14.3.3 — Slot validation guidance | Step 1 + Step 2 | | Doc 1 §14.3.5 — Mustache referencing slots before collection | Mustache directional ordering | | Doc 1 §14.3.6 — RT=2 apisilencebehaviour completeness | Step 3 RT=2 | | Doc 1 §14.3.11 — Bot-level disambiguation in per-intent fields | Step 4 misplacement check | | Doc 1 §14.3.12 — Slot validation in intentInstructions | Step 4 misplacement check | | Doc 1 §14.3.13 — Persistent policy in single intent | Step 4 misplacement check | | Doc 1 §14.3.14 — Field-purpose cheat sheet | Disambiguating misplacement | | Doc 2 §5 — Skill 2 architecture | What Skill 2 does | | Doc 2 §3.6 — Status mechanic for section 5 intents | Reactivation logic |

Also load this file from this skill's package:

• conversation-routines-style-guide.md — concrete templates and worked examples for validationPrompt and intentInstructions across RTs

---

2. Setup

2.1 Detect runtime

| Signal | Runtime | |---|---| | Conversation in claude.ai or mobile app, no workspace file system, no agent-spec.md accessible | Single-conversation | | Workspace file system available (Claude Code), agent-spec.md readable as a file | Claude Code |

State the detected runtime to the user. They can correct.

2.2 Read the spec

Single-conversation: read backward through the conversation context to find the most recent spec emission (from Skill 1 or a prior Skill 2 invocation). The spec is identifiable by its ## 1. Bot Identity header and ## 7. Generation Metadata footer.

Claude Code: read agent-spec.md from the workspace (or whatever filename the user references).

If no spec is found, abort with the message: "No Agent Spec found. Skill 2 requires an existing spec produced by Skill 1. Invoke Skill 1 (Agent Spec Designer) first."

2.3 Build the work queue

Walk section 5. Identify all intents whose status is [structural] or [detailed-revisit]. These are the work queue.

| Status | Treatment | |---|---| | [structural] | Stub from Skill 1 greenfield. Author from scratch. | | [detailed-revisit] | Was previously [detailed]; reset by Skill 1 patch mode. Treat identically to [structural] for walking purposes — author from scratch. Distinguish in section 7.3 log entry by labeling the work as "redetail" rather than "detail". | | [detailed] | Skip. Already fully authored. |

Empty queue case: if no intents are [structural] or [detailed-revisit], report: "All intents are already [detailed]. No work for Skill 2. Invoke Skill 3 (JSON Assembler) to emit the wire-format JSON." Halt.

2.4 Scan section 7.3 for staged notes from Skill 1

Skill 1's validation can extract per-intent procedural logic from the persona (Check 3) or other sources, and stages it for Skill 2 by writing entries in section 7.3 of the form:

[ISO timestamp]  Skill 1  greenfield|patch  ...  stage for Skill 2: intent  should carry the post-execution logic "" (extracted from  during Skill 1 validation).

Build an internal map: { intent_identifier → list of staged snippets }. When authoring step 4 (post-execution intentInstructions) for an intent that has staged notes, surface the snippets to the user as starting material, not directives. Format:

> Skill 1 staged the following content for this intent's post-execution instructions: "". I'll incorporate it into the draft below — confirm or edit.

Staged snippets that the user discards should be logged to 7.3 as "discarded staged note from Skill 1: ". This keeps the audit trail intact.

2.5 State the plan

Tell the user:

• Detected runtime
• Number of intents in the work queue
• Number of staged notes from Skill 1 (if any)
• Next step: propose a batching plan

Then proceed to section 3.

---

3. Batching plan

Per decision A (locked Conv 2), Skill 2 walks the work queue in batches with user confirmation between them. This prevents context bloat and keeps the user in the loop on progress.

3.1 Algorithm

queue = [intents with status [structural] or [detailed-revisit]]
hard_intents = [intent in queue if its hard-intent flag in section 4 = true]
soft_intents = [intent in queue if its hard-intent flag in section 4 = false]

batches = []

# Each hard intent is a singleton batch
FOR each hard_intent in hard_intents (in section-4 order):
  batches.append([hard_intent])

# Soft intents grouped by adaptive sizing
total_count = len(queue)
target_checkpoints = derive_checkpoint_count(total_count)
soft_batch_size = ceil(len(soft_intents) / max(1, target_checkpoints - len(hard_intents)))
soft_batch_size = min(soft_batch_size, 6)  # upper bound

current_batch = []
FOR each soft_intent in soft_intents (in section-4 order):
  current_batch.append(soft_intent)
  IF len(current_batch) == soft_batch_size:
    batches.append(current_batch)
    current_batch = []

IF current_batch is not empty:
  batches.append(current_batch)

derive_checkpoint_count(total_count):

• ≤ 5 intents: 2 checkpoints (with hard intent isolated if any)
• 6–10 intents: 3 checkpoints
• 11–15 intents: 3–4 checkpoints (favor 4 if hard intents present)
• 16–20 intents: 4 checkpoints
• > 20 intents: ceil(total_count / 5) checkpoints

Edge case: only one intent in the queue. Single batch, single intent. Still issue the checkpoint gate after completion before reporting overall completion. The user always sees an explicit confirmation point.

Edge case: all queue intents are hard. All batches are singletons. target_checkpoints calculation degenerates harmlessly; the loop just produces one batch per hard intent.

3.2 Present the plan

Block format (not a table — for ≤4 batches a table is visual overkill):

Plan to detail [N] intents in [K] batches:

Batch 1 (singleton — hard intent flagged in section 4): get_available_slots
Batch 2: validate_customer_address, confirm_appointment, transfer_to_human
Batch 3: general_inquiry, reschedule_existing

Confirm or override? You can:
- Accept the plan as-is
- Reorder batches (e.g., "do batch 2 first")
- Regroup intents (e.g., "merge batch 2 and 3" or "split batch 2")
- Start with a specific intent ("start with confirm_appointment")

3.3 Override handling

If the user overrides the plan, accept the override and log it to section 7.3:

[ISO timestamp]  Skill 2  detailing  Batching plan overridden by user. Original plan:  batches per algorithm. Final plan: .

If the user's override puts a hard intent in a non-singleton batch, push back once:

> Intent ` was flagged as a hard intent in section 4 (slot count, conditional branching, transition complexity, or validation complexity). Singleton batching is the default to keep focus. Are you sure you want to group it with `?

If the user confirms, proceed with the override. Skill 2 doesn't refuse overrides — the user has the final say.

---

4. Per-intent four-step interview

For each intent in a batch, walk the four steps in order. The interview shape varies by Response Type, especially in step 3.

4.1 Step 1 — Slot detailing

Section 4 declares slot names, ParameterTypeIds, required flags, and collection orders. Step 1 elaborates each slot.

Per slot, capture:

| Field | Meaning | When | |---|---|---| | Description | User-facing description used by the LLM at runtime to phrase the slot collection question. Often Hebrew. | All slots | | OptionList (with Value + Label per option) | Static list of choices | ENUM (PT=19) with known choices | | OptionList: [] + note | Options come from upstream API response | ENUM (PT=19) dynamically populated (typically downstream of an RT=2 intent declared in 4.5.4) | | Validation guidance for v1 fallback | Format/range constraints to embed in validationPrompt | NUMBER/DATE/EMAIL stored as STRING (PT=1) per Skill 1 v1 fallback |

Example slot detailing (Hebrew bot, RT=3 confirm_appointment intent):

Slot: address
- Description: כתובת מלאה: רחוב, מספר בית, עיר. למשל: רחוב הרצל 14 רמת גן.
- Type: STRING (ParameterTypeId 1)
- Required: true
- Collection order: 1
- OptionList: [empty for STRING]

Slot: time_slot
- Description: בחירת זמן מבין הזמנים הזמינים שהוצגו לך
- Type: ENUM (ParameterTypeId 19)
- Required: true
- Collection order: 2
- OptionList: [] (dynamically populated from upstream get_available_slots response — see section 4.5.4)

Iron rule (check 4 — fires during step 1, blocking): if section 4 declared a slot with a type that mismatches its purpose (e.g., STRING for "phone"), do NOT silently fix. Raise:

> Slot ` is declared as in section 4 but the description suggests it should be ` (e.g., PHONE, ParameterTypeId 10). This is a structural change. Pause Skill 2, invoke Skill 1 patch mode to fix the slot type, then return.

The user must either accept the type as-is (with appropriate v1-fallback validation in step 2) or pause and patch via Skill 1.

4.2 Step 2 — validationPrompt authoring

The validationPrompt is the bot's primary lever for shaping how it collects slots. Conversation Routines style is mandatory per Doc 1 §14.3.2:

• ALL-CAPS section headers (e.g., ADDRESS COLLECTION, IRON RULES)
• Numbered steps for the collection sequence
• Explicit IF/ELSE for branching
• IRON RULE blocks for non-negotiables

Free prose is forbidden. See conversation-routines-style-guide.md for templates and worked examples.

Authoring procedure:

1. Draft an initial prompt from:

• The slot list and types (from step 1)
• The collection order (from section 4)
• The intent's purpose (from section 4 description)
• Any bot-level constraints in section 2.1 persona (e.g., language posture)

1. Ask the user about edge cases before finalizing:

> For this intent, I want to nail down edge cases. What should the bot do if: > - The user gives a partial answer (e.g., street name without house number for an address)? > - The user gives an off-topic answer? > - The user refuses to provide the slot? > - [For v1-fallback slots] The user provides the value in an unexpected format?

1. Incorporate edge cases into the prompt as IF branches and IRON RULE blocks.

1. Show the draft to the user. They confirm or edit.

1. Verify before moving on:

• Every slot in the intent appears in the prompt
• Every v1-fallback slot has explicit format/range guidance
• At least one IRON RULE block exists for the most critical constraint
• Prompt language matches the bot's primary language (Hebrew text for Hebrew bots, etc.)
• Every Mustache reference resolves (see section 5 — Mustache resolvability mechanics)

If any of these fail at end-of-step, return to authoring; do not advance to step 3.

4.3 Step 3 — RT-specific configuration

The Configuration shape and required language fields differ by Response Type. Section 4 declares the RT for each intent — read it and branch.

RT=1 (Layer Transfer)

Required language fields:

| Field | Meaning | Example (Hebrew) | |---|---|---| | announcement | What the bot says before transferring | "אני מעבירה אותך לנציג, רגע אחד" | | intentLoadingAnnouncement | Latency-cover utterance between announcement and the actual transfer | "המתן בבקשה" |

Layer ID is structural (declared in section 4). If marked `, leave as-is — Skill 3 will emit the fail-loud sentinel -999`. Do not invent a layer.

RT=2 (API Call)

Required language fields:

| Field | Meaning | |---|---| | apiResponseAnnouncement | What the bot says when the API succeeds. Almost always uses Mustache references against section 4.5.4 dotted paths declared by the user. | | fail_output | What the bot says when the API fails. Default pattern (graceful): "I couldn't reach the system right now. Let me transfer you to a human." Skill 2 drafts this default; user confirms or rewrites. | | function_output | LLM guidance for interpreting the API response in subsequent turns. Skill 2 drafts based on the response shape declared in section 4.5.4. | | intentLoadingAnnouncement AND IntentLoadingAnnouncement | Same content, both populated. This is the case-bug pair per Doc 1 §16 — preserve both, identical content. | | silence_sentence | What the bot says during the API wait | | silence_ending_sentence | What the bot says after silence loops are exhausted | | silence_instructions | Additional LLM guidance for silence handling (often empty) |

Iron rule (check 11 — fires during step 3, blocking): every RT=2 intent must populate all six apisilence fields above (silencesentence, silenceendingsentence, silence_instructions, plus the durations and loops which are structural in section 4). Per Doc 1 §14.3.6, an RT=2 intent without complete silence behavior produces dead air at runtime when the API takes 8+ seconds.

Iron rule (check 10 — fires during step 3, blocking): apiResponseAnnouncement, failoutput, functionoutput must all be non-empty. The fail_output graceful default qualifies as non-empty.

Mustache references in apiResponseAnnouncement: must resolve against section 4.5.4 dotted paths declared for THIS intent, OR against slots collected by THIS intent or upstream intents (per section 5 mechanics). Verify at write-time.

RT=3 (Continue)

Required language fields:

| Field | Meaning | Example (Hebrew) | |---|---|---| | announcement | What the bot says after slot collection completes | "מעולה. רשמתי לך תור ב-{{available_slots.0.display}} בכתובת {{address}}. נשלח לך SMS עם פרטים." |

The announcement typically uses Mustache references against the intent's own collected slots and/or upstream API response paths.

RT=4 (Dial-Out)

Required language fields:

| Field | Meaning | |---|---| | announcement | Spoken before initiating the dial | | intentLoadingAnnouncement | Spoken while dialing |

Other RT=4 fields (Phone destination, NEXTVOID, etc.) are structural — declared in section 4 by Skill 1.

4.4 Step 4 — Post-execution intentInstructions

This is the second Conversation Routines block per intent. It defines what the bot does after this intent has fired and slots have been collected.

Critical distinction (per Doc 1 §14.3.10, §14.3.12):

• validationPrompt is pre-execution — slot collection
• intentInstructions (per-intent) is post-execution — what to do next

Skill 2 writes intentInstructions to cover:

• Confirmation language (e.g., POST-EXECUTION: address validated. Proceed to slot fetch.)
• Conditional next-intent routing if the intent's outcome varies (RT=2 with conditional success/

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: VoicenterTeam
• Source: VoicenterTeam/claude-marketplace
• License: MIT

Install and usage instructions live in the source repository linked above.