SKILL.md

name

architect-migrate-from-competitor

description

Use when the user wants to move a voice agent onto ElevenLabs Conversational AI from another platform — Retell AI, Vapi, or Bland — or hands over an export from one of them to work from. Fires on "migrate my Retell agent", "convert this Vapi assistant", "move from Bland to ElevenLabs", "port my agent to ElevenLabs", "here is my agent JSON", or when the user pastes a JSON blob containing response_engine, squadId, transportConfigurations, or pathway. Not for unrelated database, codebase, or framework moves.

Migrate a voice agent from another platform to ElevenLabs

What this skill is for

The user has an agent built on Retell, Vapi, or Bland and wants it running on ElevenLabs. This skill owns the parts of that job specific to importing: identifying the export, handling credentials inside it, mapping foreign constructs onto ElevenLabs ones, naming what genuinely has no equivalent, and sequencing the work.

It does not re-teach ElevenLabs authoring. This plugin has ~30 skills that own that, and they are more detailed and better maintained than a summary here would be. Your job is to translate and to route.

What counts as finished: an agent that demonstrably runs. Not an optimal one — a conversion that starts, resolves its variables, calls a tool successfully and reaches an end. Aim to get there in one pass and one round of fixes, which means the checking in step 5 is part of the work rather than something offered afterwards. The finish line is a run, never a re-read of your own config, and "I converted everything" is not a status report.

Assume an authenticated EL workspace with $API_KEY set, as every skill in this plugin does.

What to delegate, and to whom

Route each step rather than reimplementing it. Most migrations touch six or seven of these; read one when you reach its step, not up front.

Step	Skill
Read the target agent's current state	architect-explore-agent
Choose the model	architect-llm-selection
Port prompt text and first message	architect-edit-string-fields
Build the workflow graph, nodes, edges	architect-edit-workflows
Author step-by-step logic as procedures	architect-structured-procedures, architect-manage-procedures
Recreate tools	architect-create-webhook-tool, architect-create-client-tool, code-tools
Fix a tool that misbehaves	architect-edit-existing-tool, architect-troubleshoot-tool-errors
Post-call fields and evaluation criteria	architect-post-call-data
Remaining config, turn-taking, latency	architect-update-config-safely, architect-turn-taking-latency
Auth, guardrails, retention	architect-secure-for-production
Stage and ramp the rollout	architect-branches-versions-merge, architect-schedule-launch
Mock tools before any test run	architect-mock-all-tools
The smoke run that proves it works (step 5)	architect-create-simulation-test
Parity tests, CI	-llm-test, -tool-test, architect-get-agent-ci-green
Score the agent — only once asked, see step 6	agent-review, then agent-simplification
Check it once real calls exist (step 6)	architect-review-live-calls

Do not create the agent through architect-generate-agent. Its own documentation warns that its flow regenerates the prompt instead of installing the one you just converted. Create the shell directly with POST /v1/convai/agents/create, then install the converted content.

Reading a sibling skill is not the same as routing to it, and the difference costs you at write time. The temptation is to skim the two or three you think you need and hand-roll the rest, which is faster right up to the first rejected payload — a real migration reimplemented tool creation, post-call data, model selection and all testing inline, and hit its schema surprises while writing to the live workspace rather than while reading. Each of these skills owns field-level detail this one deliberately does not restate. Before you report, account to yourself for which skill covered each step: a step you cannot attribute is a step you improvised. That accounting is for you, not for the report — a customer has no use for a list of internal skill names.

Step 1 — identify the platform

Dispatch on a field that is always present, not on one that merely often is:

Signature	Platform	Read next
response_engine.type	Retell	reference/retell.md
squadId, members[], transportConfigurations, model.toolIds	Vapi	reference/vapi.md
pathway, nodes[].type with a Default node, or a Persona payload	Bland	reference/bland.md

Ask the user which platform it came from if the blob is ambiguous. Never guess from prose in the prompt text.

Step 1b — audit the export before converting it

Cheap, mechanical, and it routinely finds live bugs in the source agent. A migration is the first time anyone reads the whole graph at once, so do this before deciding what to build:

• Dangling edges — a condition with no destination. These are silent dead ends on paths that look wired in the editor, and they land on happy paths as often as error paths.
• Orphaned nodes — nothing routes in, or nothing routes out. A whole feature that has never run.
• Variables read but never assigned — spoken in a prompt, written nowhere. The caller hears a literal placeholder or a blank. Scan code-node bodies, not just template syntax. A variable read as dv.account_ref inside a JavaScript node is invisible to a {{...}} search, so an export with a dozen code nodes will under-report badly on the exact check that matters most. Rank what you find by how many tools bind it: a variable bound on every tool that nothing supplies fails every tool call at conversation start.
• One identifier, two different definitions. Check whether any two tool entries share an id or a name while disagreeing on url or method. This is not tidiness — one export reused a single tool id across a main-flow tool and a component tool pointing at different environments, so the agent read from one and wrote to the other. Report it: an agent whose write paths leave the environment its name claims is a finding the owner will want, and it decides how you key the id map in step 4.
• Response paths that cannot resolve — an assignment reading a field the API does not return, or a path whose shape is wrong for the response (array indexing and object prefixes are the usual offenders). These carry across silently and break the same way on the new platform.
• Branch conditions with a null target and no else path.

Do the audit in full. Do not report it in full.

This is the part that decides whether a migration feels like arriving somewhere or like being handed a bill. Run every check above at full depth — the accuracy is the point, and nothing else in this skill finds these. Then write the findings to a file, and bring two things back to the user:

1. What their agent does — the intents it handles, the tools it calls, the shape it is in. A dozen lines, and a diagram of the source graph where one helps. Name the phases using the source's own node names so they can check you. This is the only evidence they have that you understood their agent before you started rewriting it, and it is the cheapest trust available in the whole job.
2. Only what you cannot proceed correctly without. The test is mechanical: would a wrong guess here break the migration? A variable that every tool binds and nothing supplies, a voice that does not port, an environment that two halves of the graph disagree about. On a real 123-node export that list was two items. It is normally one to three.

Everything else goes in the file with a one-line pointer. Not because it does not matter — it is the most valuable thing in this step — but because of when it arrives. A defect ledger delivered before anything runs reads as "here is how much work you have bought," and the findings are almost all pre-existing bugs in an agent that has been in production for months. Lead with a wall of red and a first-time user concludes the platform is the problem, closes the tab, and stays where they are.

So do not open with a count of defects. When nothing blocks the conversion, say that first — it is usually true and it is the single most useful sentence you can write.

Separate the three registers, in the file and in anything you say aloud. They read completely differently and mixing them is what makes a short list feel long:

• Blocks the conversion — needs an answer now. This is the only category that goes inline.
• Already broken in the source — live today, reproduced faithfully. Say so explicitly. "Your current agent reads a placeholder to the caller here" is a gift; the same fact in an undifferentiated list is an accusation.
• Does not port — the genuine gaps, from reference/<platform>.md.

Never silently fix a defect and never silently carry one across. Logging it in the file is not silence; it is where the mapping log and gap list already live, from step 4.

Check the source's claims against its own endpoints

Everything above reads the export. Some of the worst defects are not in it — a prompt asserts a fact, the backend it calls disagrees, and no amount of reading the JSON can tell you. Say a prompt instructs the agent to offer same-day slots up to 5 p.m. while the scheduling endpoint refuses anything after 4:30. Both halves look right on their own, and the agent offers a slot its own tool then rejects.

So where the export hands you an endpoint, verify the facts the prompt states about it. This means calling a third party's production API, so it is fenced:

• Ask the user first, naming the endpoints. They may not own that backend, and it may be someone else's live system.
• Read-only endpoints only — a lookup, an availability check, a status query. Never one that books, pays, cancels, sends, or writes, whatever its name suggests.
• Synthetic values only. A probe is not the place for a real name, number, or booking reference.
• Skip it if the endpoint needs a credential you recovered from the export. Using that credential to explore is a wider use than its owner authorised.

What you learn joins the findings. A prompt fact the backend contradicts is a caller-visible bug in the source agent, and it is the kind nobody has reported, because it only shows up on the calls that hit it.

Step 2 — credentials, before anything else touches the export

Exports embed live credentials: bearer tokens, Basic auth headers, API keys in tool headers, and sometimes a secret inside a webhook URL's query string. Handle these first, because every later step copies fields around.

1. Scan every tool for header values, URLs with embedded userinfo or query secrets, and any field whose name contains auth, token, key, secret, or bearer.

2. For each real credential found, create an ElevenLabs secret and reference it — never paste the literal value into a tool definition:

   POST /v1/convai/secrets
   {"type": "new", "name": "billing_api_token", "value": "<the value from the export>"}
   

   The response carries a secret_id. Reference it in the tool's request_headers as {"secret_id": "<that id>"}. Rotation is PATCH /v1/convai/secrets/{secret_id} with a body of {"type": "update", "name": ..., "value": ...} — note the id is in the path, not the collection endpoint you created against.

   Secrets are workspace-scoped, so check what else uses one before you touch it. GET /v1/convai/secrets/{secret_id}/dependencies/{resource_type} lists the resources depending on a secret. Rotating or deleting a secret that other agents reference breaks them, and a migration is exactly the context where someone tidies up a credential that looked unused.

3. Tell the user which credentials you found and that they are now live in a third system, so they can decide whether to rotate at the origin. A credential sitting in an export file has usually been shared more widely than its owner realises.

4. A value that is already a {{template}} reference is not a credential — do not resolve it to a literal, which is how an agent ends up authenticating as the wrong principal for the rest of a call. But do not carry the template across as a string either. ElevenLabs substitutes nothing in a header string — a header given as text is sent exactly as written, so "Basic {{vault_token}}" transmits those literal characters and the request is simply unauthenticated. It is a credential reference that does nothing, and it fails on every call rather than visibly at build time. Use the typed forms:

   • a dynamic variable — {"variable_name": "vault_token"}
   • a workspace secret — {"secret_id": "<id>"}
   • an environment variable — {"env_var_label": "<label>"}

   A locator supplies the whole header value, so it cannot be composed with a literal prefix. That sounds like a problem for Basic <token> and is not: put the scheme word inside the secret. Create the secret with value Basic <token> and reference it with {"secret_id": ...}. The header is then complete on its own, and the credential never appears in the agent config. If you find yourself wanting "Basic {{vault_token}}", that is the sign to make a secret holding the whole header value.

5. Watch for one variable that plays two roles. A single name is often both a static seed credential used by early calls and a per-user token that a later tool overwrites mid-call. They need different treatment and it is easy to see only one of them:

   The test is mechanical: does any tool write that variable during the call? Look for a response assignment on any tool whose target is the variable name — not just on the tool you are holding, since the tool that issues a token is rarely the tool that uses it. Then:

   • Nothing writes it → static. Its value lives in the agent's variable defaults, so a {"variable_name": ...} locator would leave a live credential sitting in agent config in plaintext. Make a secret holding the complete header value and reference it with {"secret_id": ...}.
   • Some tool writes it → swapped. Use {"variable_name": ...}. A secret cannot change mid-call, and the locator leaks nothing because the value only ever exists at runtime.

   Because the locator supplies the whole header, a swapped variable has to hold the whole header value too. If the endpoint issuing that token returns a bare token, the assignment writing it cannot add the scheme word — so either have that endpoint return the complete value, or confirm the receiving API accepts a bare token. That is a short, concrete question for the customer, and it is worth asking before you build rather than after the first unauthenticated call.

   Handling only the swap leaves a placeholder in the agent's variable defaults, which invites someone to paste a live credential into agent config in plaintext. Say explicitly which of the two you have done.

Do not write the raw export, or any redacted copy containing real values, into a repo or a log.

Step 3 — pick the shape

One decision to state and one to ask. What gets shipped has a sensible default and should not be put to the user at all; what shape it takes is worth their judgement, and this is the moment for it — after the audit, before anything is built.

The deliverable is a default, not a question

The rebuild ships. A faithful port gets built quietly alongside it as an oracle. State that in one line and move on. Do not open someone's migration by asking them to choose a migration philosophy — they came to get their agent working, and the trade only means something to a person who already knows what fidelity costs.

• The rebuild is the agent. The source is the specification, not the blueprint: pick the shape that fits, fix what the audit found, hand them something callable.
• The faithful port is built and then not mentioned again. It mirrors the source construct for construct, it is never deployed, and it is one converter pass now that the audit exists. It is the oracle — what parity tests are written against, and what agent-simplification wants before it will touch anything. One line in the report's file list is the whole of its visibility.

Two things change this, and both come from the user rather than from your reading of the export. If they ask how they can tell the new agent matches, the port stops being silent — that is its purpose and it is already built. If they say plainly that they are done with the source platform, skip it.

Findings are simply fixed in the rebuild and reproduced in the port. There is no per-finding question to ask; the report says which ones you fixed.

The shape is the question

This is the one decision worth putting to the user before you build, because it is the one they can actually judge — they know their own call flow.

Four options, in increasing order of cost. Recommend one — with the reason, in a sentence they can disagree with — rather than presenting a menu and waiting:

• A single agent with a prompt. Right for a source that is one big prompt with a few tools, and right more often than the source's node count suggests.
• An agent with procedures. Right for step-by-step logic — verification sequences, intake, scripted disclosures — where the order matters but the graph does not branch much.
• An agent with a workflow. Right when the source genuinely has distinct states with different tools, models, or voices per state.
• A mix. Common and often correct: a prompt or a small workflow for the spine, procedures for the sequences that hang off it. Do not treat the three above as exclusive.

Do not mirror the source's topology out of loyalty. Competitor editors encourage many small nodes, and every node you carry over multiplies the configuration surface that can go wrong. Say what the shape buys in terms of their agent — "your three queue components run the same algorithm, so they become one paragraph and three procedures" — not in terms of node counts, which mean nothing to them. Every real reduction comes from that kind of semantic merge; a mechanical conversion is roughly node-count-neutral, which is exactly why the port is not the thing that ships.

Step 3b — get the shapes right before anything is watching

Discovering the API's shape rules by being rejected by it is slow, and it burns the patience of whoever is watching — a customer on a call, or someone who just uploaded their own export and is waiting. It is avoidable: nearly every rejection below is a known shape rule, and the rest can be learned somewhere harmless.

Three habits, in order of how much they save:

1. Build every payload locally first, then write. Do not alternate authoring and API calls node-by-node. Compose the whole set — tools, nodes, edges — check it against the rules in this skill and reference/expressions.md, and only then start writing. A shape mistake made once in a local draft is one fix; the same mistake discovered on call forty is forty.
2. Do any genuine schema discovery somewhere disposable. If you truly do not know whether a field is accepted, find out on a scratch agent rather than on the one being migrated. Ask which workspace to use for it — a workspace holding production agents is not disposable, and tools and knowledge-base documents are workspace-global, so a probe that creates one is not confined to your scratch agent. Delete only what you created in this session, by id you captured at create time. Never learn on the customer's agent, and never learn on a branch they are reading.
3. Re-read a rejection before changing anything. The messages below name a symptom, not the field at fault, so the instinct to bisect the payload is wrong and expensive. One of these cost a real migration fourteen identical failures.

Rejection	What it actually means
Input should be a valid dictionary or object to extract fields from	An expression was passed as a string. Conditions are structured objects — see reference/expressions.md.
Input should be a valid dictionary	A path_params_schema was passed as an array. It is an object keyed by parameter name.
Can only set one of: description, dynamic_variable, is_system_provided, constant_value, or is_omitted	A property declares two or more value sources. Exactly one.
Must set one of: description, dynamic_variable, ...	A property declares none. Most often an array's items schema, which needs its own source.
Invalid URL format	A {{...}} source interpolation survived in a tool URL. Static host, single-brace path placeholder, path_params_schema.
Duplicate edge found between X and Y	An edge already exists for that node pair. Edges are keyed on the unordered pair, so the reverse transition becomes that edge's backward_condition.
Input should be 'generate_immediately', 'wait_for_user' or 'auto'	entry_behavior got something outside its enum.
Input should be 'auto', 'force' or 'off'	pre_tool_speech was given filler text. It is an enum, and it cannot carry a line — use forced_tool_name on an override_agent node instead.

And one that never rejects at all, so no message will tell you: expression: {} is accepted and silently becomes boolean_literal false, so the edge never fires.

And two on the test payloads, which is where people are still guessing after everything else has gone in clean: success_conditions is a list of strings, and simulation_scenario is a plain string — not the nested simulated_user_config object its name suggests. Both reject, and both only bite at step 5, so they read as a broken smoke run rather than as two schema rules.

If something does go wrong in front of the customer, say what you are checking rather than narrating surprise. "That field takes an object, fixing" is fine. A string of "oh, that didn't work" is what makes a routine schema rule look like a broken migration.

Step 4 — build in dependency order, and keep the id map

Read reference/traps.md before you author anything here, and reference/expressions.md before the first condition. They are short and they are the failure list for exactly this step: every item in them is a thing that is accepted by the API and wrong at runtime, so nothing later in this skill will catch it for you. Read them now rather than after a rejection, because these do not reject.

For the payload shapes themselves, read ../../reference/ — not a sample config you found in the working repo. A complete agent and a complete webhook tool live there, every field populated. The sample you would otherwise grep for may be stale, may be someone's scratch file, and outside ElevenLabs does not exist at all, which is how a skill passes internally and fails in the field.

Most of the order here is forced by what references what. Getting it wrong does not produce a clear error; it produces a graph with references to things that do not exist yet.

1. Create the agent shell. Everything else needs its id. Do not use architect-generate-agent (see above).
2. Create every tool, and record the id each one comes back with. This is the step people skip the bookkeeping on, and it is unrecoverable later: a workflow's tool node references a tool by id, not by name, and so does additional_tool_ids on an override_agent node. You cannot build any node that calls a tool until its id exists.
3. Create procedures through the branch-scoped flow that architect-manage-procedures owns. Passing them in the agent-create payload returns 200 and silently drops them.
4. Build nodes, then edges. Edges reference node ids, so the nodes have to exist. Order only the conditional edges — the unconditional one is moved last for you.
5. Then the rest of the config — model, privacy, turn-taking — and only then step 5.

Key the id map by something that is genuinely unique, which is neither the name nor the id alone. Exports break both keys, and each failure is silent:

• Same name, different tools. Routine. Once you have renamed one to satisfy uniqueness, a name-keyed map cannot tell them apart and quietly points several nodes at one tool.
• Same id, different definitions. Worse, and the case step 1b tells you to look for. An id-keyed map collapses the two, and half the graph then calls the wrong host — which nothing rejects, because both hosts answer.

So key on the definition: the source id together with the fields that decide where a call lands, url and method at minimum. Two entries are the same tool only when those agree. When they do not, create two ElevenLabs tools and record in the mapping log why one source tool became two — that split is exactly the kind of thing a reader will otherwise assume was a mistake.

Leave a coverage proof, for the rebuild and the port alike

Two local files. They are the difference between output someone can audit and output they have to take on trust, and they cost almost nothing because you are making each of these decisions anyway:

• A mapping log — one entry per source behaviour: what it was, where it landed, and why. In a faithful port this is the fix log. In a rebuild it is the only thing that answers "did you drop something?", which is the rebuild's one genuine weakness against a port.
• A gap list — every construct you could not map and what you did instead. This is also what the user needs in order to sign off on the approximations, rather than discovering them later.

Write both to a scratch directory, never into a repo, and never let either hold a credential value or a verbatim copy of the export.

Then check your own output, not your intentions

Run a mechanical pass over what you actually emitted. Re-derive the things that are cheap to re-derive: every edge's endpoints exist, every tool id referenced was really created, every node is reachable, every variable a tool binds is assigned somewhere.

This is not ceremony. On one real migration that pass caught a bug in the converter its own author had just written: where a node pair carried an edge in only one direction, the edge was emitted reversed and unconditional, silently orphaning five nodes and one whole lookup path. Re-reading the code would not have found it, and every validator in the chain accepted the payload. Report the check's result alongside the payload; a clean result you can point at is worth more than an assurance.

Model choice

Do not carry the source model across by name, and do not use any static table of compliant models. GET /v1/convai/llm/list returns the models available to that workspace, filtered by the deployment's data residency and the workspace's compliance entitlements. Call it, then hand the choice to architect-llm-selection, which owns the region, HIPAA/PCI/ZRM and latency tradeoffs.

Step 5 — prove it runs, before you tell anyone it is done

This is a step, not a formality at the end, and it is the difference between a migration that looks finished and one that works. Every failure mode in reference/traps.md is silent: nothing rejects your payload, the agent exists, the graph renders, and it is broken on the first real call. A migration reported as complete without this has not been checked — it has been hoped about.

The bar for "working" is five things, and all of them are observable:

1. Every tool was created — no payload was rejected and quietly skipped.
2. The agent starts and delivers its first message.
3. Every dynamic variable a tool binds is actually supplied at conversation start.
4. At least one tool call executes and comes back successful.
5. At least one path reaches a terminal node.

Nothing there is about quality. A first migration should be judged on whether it runs at all; tuning comes after, and confusing the two is how a broken agent gets shipped with a confident summary.

Mock the tools for the first run, or you will transact against production

Tool mocking defaults to off. A simulation with default settings calls the customer's real endpoints — so on the agent you just migrated, a smoke test books the appointment, charges the card, and mutates the cart, for real. Nothing warns you.

So run it in two passes:

• Pass 1 — everything mocked. This is the cheap, side-effect-free run that proves the graph is alive: first message fires, variables resolve, edges route, a terminal node is reached. It catches the conversation-start binding trap outright — a variable a tool needs but nothing supplies fails the run with a missing_dynamic_variables error naming it, which is exactly the check that is impossible to pass by reading.
• Pass 2 — read-only tools live, everything that mutates still mocked. One real lookup is what proves auth actually works, and auth is the thing most likely to be silently wrong after a migration. Do not unmask a tool that books, pays, cancels, sends, or writes.

Mocking everything is not the same as defining mocks, and the difference will waste your first run. When no mock matches a call the default is to raise, not to fall through to the real tool. That default is the right one — an unmatched call is visible instead of quietly hitting production — but it means "mock all" with no mock bodies makes every tool call fail, and you learn nothing about the graph. Give each tool one mock with no parameter conditions, which makes it always match, and a mock_result holding the minimal successful response shape that tool's consumers read. Where a response assignment pulls a field out, the mock has to contain that field or the variable silently stays unset and you are debugging the mock instead of the migration. A mock can also be marked as an error deliberately, which is how you exercise a failure path once the happy one works.

architect-mock-all-tools owns the mocking setup and architect-create-simulation-test owns building the run; route to them rather than hand-rolling. The current endpoints are POST /v1/convai/agent-testing/create and POST /v1/convai/agents/{agent_id}/run-tests — simulate-conversation still exists but is deprecated.

Report what the run showed, not that you ran one

Give the five items above with their actual outcome, and name anything you could not verify. "Smoke test passed" is not a result; "first message fired, three edges traversed, fetch_profile returned 200, checkout still mocked and untested" is.

Two rounds is the budget for fixing. If a third would be needed, the failure is probably not a conversion defect, and grinding on it is how a one-hour job becomes four. Stop fixing and work out which of these it is: a success condition that does not match what the agent was asked to do, a mock missing a field its consumer reads, or a real platform behaviour. Then say which, with the measurement, and stop. A behavioural gate that holds two runs in three is a finding, not a bug — non-determinism does not converge under repetition, so report the rate and what would make it absolute rather than re-running until it looks better. Between rounds, re-run only what failed; run the whole suite once at the end.

The closing report

This is the artifact the migration is judged on, and its job is to leave someone confident enough to move. Order matters more than content here — the same facts in the wrong order read as a warning.

1. What it does, and what it became. The phases and tools, and a before/after diagram of the source graph against the new shape. This goes first because it is the only section that says I understood your agent.
2. That it runs. The five checks with their outcomes.
3. Mapped directly · Handled natively by ElevenLabs · Needs you. Three groups, in that order. The middle one matters more than it looks: a construct the source built by hand that this platform does for you is a win, and filed as "difference" it reads as a loss. The third group is the only one that asks anything of them, and it should be short.
4. Decisions and why. Every judgement call you made that they might have made differently — one line each, with the reason and the alternative. A voice chosen as a placeholder, a model held at the source's for comparability, an environment resolved one way. This is what makes the migration reviewable rather than a black box, and it is the section people actually read.
5. Not migrated, on purpose. Everything net dropped: orphaned nodes nothing routed to, edges that led nowhere, tools referenced by nothing, constructs with no equivalent. Say why for each, in a clause. An unexplained absence is the thing that erodes trust later, when they go looking for a feature and cannot find it — and most of these were already dead in the source, which is worth stating plainly.
6. The files, in one line each — the audit findings, the mapping log, the gap list, the port.
7. What to do next, and it is not a review. If they have transcripts or recordings from the source platform, this is the moment they are worth the most: real scenarios replayed against the new agent find in an afternoon what invented ones will not find at all. Invite that. It is a better next step than any score, and it is the one that turns a migration into their agent.

Do not lead with a defect count, do not grade the agent, and do not attach a scorecard. The step 1b findings live in a file with a pointer, and agent-review is step 6's business and gated there.

Before you call it done

These five can only be answered by running something. Do not substitute a re-read of your own config for any of them.

• A mocked smoke run passed — first message delivered, variables resolved, a terminal node reached.
• One read-only tool executed live and succeeded, so auth is proven rather than assumed.
• No missing_dynamic_variables error, the only real proof that every bound variable is supplied at conversation start.
• Every tool was created, counted against the source's tool list. A payload rejected and skipped leaves a graph routing to nothing.
• The self-check over your emitted output ran and you are reporting its result (step 4) — not the validator's, which passes payloads that are structurally wrong.

Then the report, which is what the migration is actually judged on.

• It leads with what the agent does and that it runs — not a defect count, not a score. The step 1b findings are in a file with a pointer, and agent-review was not handed over unasked.
• It says what was dropped and why, and what you decided and why.
• Only what genuinely blocked the conversion was put to the user as a question. One to three is normal; eleven means you moved the audit into the conversation.
• The mapping log and gap list exist and the user has them.
• Every credential you found is a secret reference and you said so — including any variable carrying both a static seed and a swapped token. You ran the scan rather than reasoning over the tool list.

Then the silent failures — and check them against the files, not against a summary. Re-open reference/traps.md and reference/expressions.md and read what you emitted against them: headers, tool URLs, conditions, transfer nodes, node-scoped attachments. This file used to restate that list, which meant two copies to keep in sync, and they drifted. One instruction is safer than a duplicate.

Parity tests are the one item that is genuinely follow-up rather than part of a working migration. Say so plainly instead of implying the agent is test-covered when it has had one smoke run, and point at the customer's own transcripts, which is where real coverage comes from.

Step 6 — hand off, because "runs" is not "good"

This skill's finish line is deliberately low: a conversion that runs. Say that plainly and name who answers the next question, rather than leaving the user thinking a smoke test was a quality review.

But do not hand a scorecard to someone who has just arrived. agent-review is an operator's tool. Pointed at a fresh migration it returns a page of structural findings that read as a verdict on the decision to switch — and it lands right after the audit and the test results, which is three documents in a row telling a new user their agent is broken. That sequence is how a migration gets abandoned at the last step. So gate it: run it when the user asks, or once they have confirmed the agent does what they need. Not by default, and not in the same breath as the report.

1. agent-review — scores prompt quality and workflow structure, which is the axis this skill defers on purpose. Right for an operator tuning an agent they already trust.
2. agent-simplification — acts on the structural findings. A faithful one-node-per-source-state port is exactly its input, and it proves behaviour is preserved with a ground-truth suite rather than asserting it.
3. architect-review-live-calls — once real traffic exists, finds what is actually failing in production. Nothing before this point can tell you that.

When the review does run, it is scoring the rebuild, so a bad score is a real finding. You already made the structural calls agent-simplification would have made, which means a pile of structural findings says the shape was wrong — not that the review is being unfair to a migration. Do not reach for "it's a migration" to excuse a score you earned.

The exception is if someone points a review at the port. That is supposed to score badly: it mirrors the source's topology because that is what fidelity means, and the findings are a backlog rather than defects. Refactoring them away before anyone has confirmed the new agent matches the old one destroys the only thing the port was for.

Reference files, and when each one is due

Four files matter to any one migration, and three of them are not optional reading. The point of the split is that each is short enough to actually read at the moment it applies, rather than skimmed as a wall up front.

File	Read it	What it holds
reference/<platform>.md	at step 1, once you know the platform	construct-by-construct mapping, the genuine gaps, export shape. Read only yours — you do not need the other two.
reference/traps.md	before step 4, and again while authoring each surface	every way a migrated agent breaks silently, grouped by whether you are authoring tools, nodes, or config
reference/expressions.md	before you write any condition	what can be expressed at all, why a carried-over condition inverts, and the guard builders to emit
../../reference/	before you write the first payload	a complete agent and a complete webhook tool, every field populated, plus the jq recipes for anything they do not show

That last one is the plugin's shared example directory, not this skill's. Go there rather than looking for a sample config in the working repo: the one you find may be stale, may be a scratch file from another session, and in an install outside ElevenLabs does not exist at all. Read it as a field catalogue — it shows where each field lives and what shape it takes. Do not start a migration by copying it, or you ship a maximalist config whose settings nobody chose.

traps.md and expressions.md are ElevenLabs-side, so they apply whichever platform you came from. If you are about to author a condition or a tool and have not read them, you are about to make one of the mistakes in them — they exist because a real migration hit these with the mapping table open.