docs: illustrate reasoner skills and squad migration (#1277)

Co-authored-by: dev-seth-vapi <dev@devseth.com>

Author: dev-seth-vapi

fern/gpt-live/configuration.mdx

@@ -108,7 +108,7 @@ These fields belong to the assistant object. See [Create Assistant](/api-referen
 - Omitting reasoner instructions uses Vapi's default reasoner prompt. Custom instructions replace that prompt entirely. When skills are configured, Vapi adds skill-loading guidance and the content of loaded skills.
 - An explicit empty string stays empty. Updating one prompt doesn't update the other.
 - Personality packs append guidance to the speaker prompt.
-- The speaker also receives the names and descriptions of any reasoner skills.
+- Vapi adds a summary of skill names and descriptions to the speaker prompt. The reasoner manages the catalog, loads skills, and uses their instructions and tools.
 
 ## Reasoner skills
 
@@ -117,7 +117,7 @@ Set `model.reasoner.skills` to an array of skills. See [Reasoner skills](/gpt-li
 | Field | Behavior | Limit |
 | --- | --- | --- |
 | `name` | Unique within the assistant. Start with a lowercase letter; use lowercase letters, digits, hyphens, or underscores. The speaker and reasoner both see it | 64 characters |
-| `description` | Tells the reasoner, and the speaker, when the skill applies | 1,024 characters |
+| `description` | Tells the reasoner when to load the skill; also included in the speaker's skill summary | 1,024 characters |
 | `content` | The full procedure. Only the reasoner sees it, once the skill is loaded | 32,000 characters |
 | `tools` | Optional inline tool definitions, available only while the skill is loaded | 20 tools |
 | `toolIds` | Optional IDs of saved tools, available only while the skill is loaded | 20 tools |

fern/gpt-live/migrate.mdx

@@ -217,11 +217,18 @@ A squad splits a conversation across assistants and hands the caller between the
 
 Take a squad with a front-desk assistant that greets callers and routes them, a scheduling assistant, and a service-information assistant:
 
+<div className="gpt-live-illustration">
+  <img className="gpt-live-art-light" src="../static/images/gpt-live/squad-to-skills-light.svg" alt="A squad becomes one GPT-Live assistant: front-desk greeting and routing move into the speaker prompt, specialists become reasoner skills, and shared tools remain base tools." loading="lazy" />
+  <img className="gpt-live-art-dark" src="../static/images/gpt-live/squad-to-skills-dark.svg" alt="A squad becomes one GPT-Live assistant: front-desk greeting and routing move into the speaker prompt, specialists become reasoner skills, and shared tools remain base tools." loading="lazy" />
+  <img className="gpt-live-art-light-compact" src="../static/images/gpt-live/squad-to-skills-light-compact.svg" alt="A squad becomes one GPT-Live assistant: front-desk greeting and routing move into the speaker prompt, specialists become reasoner skills, and shared tools remain base tools." loading="lazy" />
+  <img className="gpt-live-art-dark-compact" src="../static/images/gpt-live/squad-to-skills-dark-compact.svg" alt="A squad becomes one GPT-Live assistant: front-desk greeting and routing move into the speaker prompt, specialists become reasoner skills, and shared tools remain base tools." loading="lazy" />
+</div>
+
 | In the squad | In one GPT-Live assistant |
 | --- | --- |
 | Front-desk greeting, intake, and routing | Shared speaker behavior, assistant-wide reasoner rules, and delegation triggers |
 | Scheduling assistant | A `schedule-appointment` skill with its procedure and booking tools |
-| Service-information assistant | An `answer-service-questions` skill with its guidance and retrieval tool |
+| Service-information assistant | An `answer-service-questions` skill with its guidance; shared `getServiceInfo` stays a base tool |
 | Handoff conditions | Skill descriptions and the speaker's delegation triggers |
 | Values passed between assistants | What the caller said is in the shared conversation. Values an earlier assistant or tool produced come from your services |
 | Protected actions | Checks in your services: prerequisites, confirmation, duplicate handling |
@@ -287,7 +294,7 @@ In the squad, handoff conditions decided which assistant took over. Now they do
 
 A condition like "hand off to scheduling when the caller wants to book, move, or cancel" becomes the scheduling skill's description and a line in the speaker's triggers.
 
-The speaker also sees skill names and descriptions, so keep them short and suitable for the caller to hear about.
+Write the speaker's triggers in terms of the caller's need. The speaker delegates the work; the reasoner chooses which skills to load.
 
 ### 5. Plan for what doesn't carry over
 

fern/gpt-live/skills.mdx

@@ -11,6 +11,13 @@ A **reasoner skill** groups one procedure with the tools it needs. The reasoner
 
 The examples on this page use an appointment assistant that checks open times, books and cancels appointments, and answers questions about the business.
 
+<div className="gpt-live-illustration">
+  <img className="gpt-live-art-light" src="../static/images/gpt-live/skill-anatomy-light.svg" alt="A scheduling skill contains its procedure and the tools for checking availability, booking, and cancelling." loading="lazy" />
+  <img className="gpt-live-art-dark" src="../static/images/gpt-live/skill-anatomy-dark.svg" alt="A scheduling skill contains its procedure and the tools for checking availability, booking, and cancelling." loading="lazy" />
+  <img className="gpt-live-art-light-compact" src="../static/images/gpt-live/skill-anatomy-light-compact.svg" alt="A scheduling skill contains its procedure and the tools for checking availability, booking, and cancelling." loading="lazy" />
+  <img className="gpt-live-art-dark-compact" src="../static/images/gpt-live/skill-anatomy-dark-compact.svg" alt="A scheduling skill contains its procedure and the tools for checking availability, booking, and cancelling." loading="lazy" />
+</div>
+
 ## When a skill helps
 
 Keep a procedure in the main reasoner prompt when it's short or applies to most requests. Move it into a skill when it's a coherent piece of work with its own rules, and often its own tools.
@@ -37,7 +44,14 @@ Several skills can be active in the same delegation. The reasoner can unload a s
 
 Loading a skill is an extra reasoning step before the skill's tools can be used. Keep the catalog small and the descriptions distinct, so the reasoner picks the right skill the first time. Measure the effect on your calls rather than assuming skills make them faster or slower.
 
-The speaker also sees the skill names and descriptions, which helps it recognize when to delegate. Write descriptions in terms of the caller's need, keep them short, and leave out anything the caller shouldn't hear. Callers don't need to hear skill names, and the speaker prompt can say so.
+The reasoner manages the skill catalog and loading. Vapi also adds each skill's name and description to the speaker prompt to help it delegate. The speaker doesn't load skills or receive their full instructions and tools. Keep descriptions short and focused on the caller's need; callers don't need to hear skill names.
+
+<div className="gpt-live-illustration">
+  <img className="gpt-live-art-light" src="../static/images/gpt-live/skills-architecture-light.svg" alt="The speaker delegates to the reasoner. The reasoner has its own prompt, always-available base tools, and the skill catalog: Scheduling is loaded with instructions and tools, while Service questions is not loaded." loading="lazy" />
+  <img className="gpt-live-art-dark" src="../static/images/gpt-live/skills-architecture-dark.svg" alt="The speaker delegates to the reasoner. The reasoner has its own prompt, always-available base tools, and the skill catalog: Scheduling is loaded with instructions and tools, while Service questions is not loaded." loading="lazy" />
+  <img className="gpt-live-art-light-compact" src="../static/images/gpt-live/skills-architecture-light-compact.svg" alt="The speaker delegates to the reasoner. The reasoner has its own prompt, always-available base tools, and the skill catalog: Scheduling is loaded with instructions and tools, while Service questions is not loaded." loading="lazy" />
+  <img className="gpt-live-art-dark-compact" src="../static/images/gpt-live/skills-architecture-dark-compact.svg" alt="The speaker delegates to the reasoner. The reasoner has its own prompt, always-available base tools, and the skill catalog: Scheduling is loaded with instructions and tools, while Service questions is not loaded." loading="lazy" />
+</div>
 
 ## Example: scheduling and service questions
 
@@ -76,7 +90,7 @@ In the assistant's configuration, skills live in `model.reasoner.skills`. Each s
 
 ## Write descriptions the reasoner can select
 
-The description is how the reasoner, and the speaker, decide a skill is relevant. Describe the caller's need and the work the skill covers:
+A skill's description tells the reasoner when to load it. Describe the caller's need and the work the skill covers:
 
 | Description | Why it works or doesn't |
 | --- | --- |
@@ -87,6 +101,13 @@ The description is how the reasoner, and the speaker, decide a skill is relevant
 
 If two skills could both fit a request, make their descriptions say where one ends and the other begins, or merge them.
 
+<div className="gpt-live-illustration">
+  <img className="gpt-live-art-light" src="../static/images/gpt-live/request-picks-skill-light.svg" alt="A request to book Tuesday at 3 matches the Scheduling skill. Service questions stays unloaded." loading="lazy" />
+  <img className="gpt-live-art-dark" src="../static/images/gpt-live/request-picks-skill-dark.svg" alt="A request to book Tuesday at 3 matches the Scheduling skill. Service questions stays unloaded." loading="lazy" />
+  <img className="gpt-live-art-light-compact" src="../static/images/gpt-live/request-picks-skill-light-compact.svg" alt="A request to book Tuesday at 3 matches the Scheduling skill. Service questions stays unloaded." loading="lazy" />
+  <img className="gpt-live-art-dark-compact" src="../static/images/gpt-live/request-picks-skill-dark-compact.svg" alt="A request to book Tuesday at 3 matches the Scheduling skill. Service questions stays unloaded." loading="lazy" />
+</div>
+
 ## Base tools and skill tools
 
 A tool's placement decides when the reasoner can use it: