TrainAR Docs
Try Free
Skills & Knowledge · Last updated 18 May 2026 · 4 min read

How skill orchestration works

When the engineer says something on the glasses, the AI decides which skill (if any) to call.

When the engineer says something on the glasses, the AI decides which skill (if any) to call. That decision uses one signal above all others: the skill's description field.

The decision loop

For every utterance the engineer makes inside a session:

  1. Transcribe the utterance.
  2. Build the candidate set — every skill (system + platform + tenant) the seat has access to.
  3. Match by description — score each skill's description against the utterance's intent.
  4. Pick the best match — if no skill scores above the threshold, the AI answers conversationally with no tool call.
  5. Fill parameters — extract values from the conversation context per the skill's parameters_schema.
  6. POST to the webhook — and wait up to timeout_ms.
  7. Deliver the response — per the skill's response_target / display_hint / response_scheduling.
  8. Remember the call — keep it in short-term memory for follow-up turns.

Why description is everything

The AI never sees your endpoint, your auth header, or your parameters_schema as the matching signal. It only sees the description. Write it as a when-to-call statement, not a what-it-does statement.

Weak:

Calls the CRM warranty API.

Strong:

Call this when the engineer asks about a customer's warranty status, expiry date, coverage, or whether a repair is covered. Triggered by phrases like "is this still under warranty?", "when does the cover expire?", "who pays for this fix?".

Multi-step orchestration — encoded in the description

If two of your skills naturally chain (pa_identify_model then pa_get_parts_list_for_model), the chaining gets encoded in the skills' descriptions. Each skill says when to call it AND what should come after.

Example from the Parts Arena bundle's pa_show_manual_page description:

TWO-STEP USAGE PATTERN: (1) Call with mode='pick' to get up to 5 ranked candidate sections back as JSON with confidence levels. If the top candidate's confidence is 'high' and clearly relevant, automatically (2) call again with mode='render' and the chosen section. Otherwise, read the candidate options to the engineer and let them choose.

That whole pattern lives in the description text. No separate "chain_hints" or workflow object — the description IS the orchestration spec.

Why the AI might call the wrong skill (or none)

Common failure modes + diagnostics:

Symptom Likely cause Where to check
Skill never called when expected description too vague or too what-not-when Re-write as a clear when-to-call statement with example phrases
Wrong skill called Two skills' descriptions overlap Add negative examples to one ("Do NOT use when…")
Skill called but with wrong arguments parameters_schema too loose Add enum / pattern / description constraints to each property
Skill called twice Bad description that matches every utterance Tighten the trigger phrases; add an Instructions note "Do not call more than once per session unless re-asked"

Use the Session detail page in the Dashboard to see exactly which skills were called and what they returned — that's the primary diagnostic tool for orchestration issues.

Assignment scope is a filter, not a priority

If a skill's assignment_scope is seat and the engineer's seat isn't assigned, the skill isn't even in the candidate set. There's no fallback to "well, we matched another skill less well, let's pick this one anyway" — assignment is a hard filter applied before matching.

How the AI handles "I'm not sure which skill to call"

If no skill scores above the matching threshold, the AI answers conversationally without calling any tool. It uses the engineer's question + the knowledge base + general knowledge to compose a response.

This is by design — better to answer freely than to call the wrong skill. If you notice the AI often defers when it should be calling a skill, your descriptions need sharpening.

Where to next