Interactive Skills

Interactive skills give Achilles Agents the ability to hold guided dialogues that surface every detail required for an action. They coach the user through missing arguments, highlight acceptable values, and route the final response to the action handler with consistent formatting. Because they understand enumerations, aliases, and validation hints, they can turn a loosely phrased reply into structured data without exposing implementation trivia to the user.

Descriptor Snapshot

Every interactive skill pairs a descriptor with an entrypoint module. Authors place iskill.md plus a matching <skill_name>.mjs/.js in .AchillesSkills/<domain>/<skill_name>/. The descriptor explains the scenario, required inputs, and tone; the module must export specs and action so the subsystem can drive the conversation and perform the final action.

# Assign Distribution Region

Map a shipment to the correct distribution centre using internal identifiers while keeping the
conversation business-friendly.

## Required Inputs

- Distribution region code

## Behaviour

- Presents up to ten sample centres per prompt.
- Accepts user input regardless of letter casing.
- Confirms using the human-friendly label while invoking the action with the technical value.

The author describes how the exchange should feel and what information it cannot proceed without. Conversational hints are lifted directly into prompts so the dialogue stays aligned with the intended experience.

Conversation Flow

When an interactive skill starts, Achilles Agents read the descriptor to understand what the user cares about, what is missing, and how to ask for it. The agent will:

Pre-fill answers from any arguments supplied up-front or inferred from the initial request.
Offer enumerated examples and synonyms when the descriptor defines them, so the user never has to memorise identifiers.
Listen for updates, cancellations, or confirmations in plain language, interpreting intent automatically.
Present a concise summary of the gathered data before triggering the action, mirroring the human-friendly descriptions from the descriptor.

This flow ensures that users always know what is still required and why certain answers may have been rejected. The module’s specs and exported functions drive this conversation; without the module the subsystem will refuse to load the skill.

Quality Guards

Interactive skills are built to keep placeholder data out of downstream systems. They recognise patterns such as your_value, not provided, or bare underscores and politely ask for real answers. Fuzzy matching brings the user back on track when spelling slips, and confirmation narratives highlight any fields that were auto-corrected so the user can make a final decision with confidence.

Together, these safeguards let teams trust the output of interactive skills for high-stakes workflows like incident reporting or customer handoffs.