Technical report

User skills before the model: routing, triggers, and execution in voxyn

How registered skills short-circuit the neural parser, why deterministic matching wins for known behaviors, and how YAML, action lists, and Python handlers share one HAL surface.

Project voxyn Year 2025 Scope SkillRegistry, Skill, NeuralPipeline.process_text

Abstract

General-purpose NLU is the wrong tool when the user has already named a behavior (“start patrol”, “wave hello”). voxyn registers skills with trigger phrases; SkillRegistry.match returns the first enabled skill whose trigger appears in the utterance. That runs before the intent parser, so latency and variance drop for curated routines. Skills can execute declarative YAML action lists, inline Python, or registered callables. All paths receive a SkillContext with the HAL, so the same safety and driver stack applies as for NLU-generated intents. This note describes that routing policy and the implementation in voxyn/skills/ and voxyn/core/pipeline.py—not skill authoring UX or packaging.

Keywords: skill routing, trigger matching, robotics middleware, extensibility, YAML, Python

1. Ordering in the pipeline

In NeuralPipeline.process_text, the text string is offered to SkillRegistry.match(text) first. Only if no skill matches does the flow load the NLU parser. That ordering is deliberate: it makes user-defined behavior authoritative over the small language model’s interpretation for overlapping phrases.

Figure 1. Control flow: skills are consulted before any LLM call.

2. Matching semantics

Each Skill stores a list of triggers. Skill.matches lowercases the input and checks whether any trigger substring appears in the text. That is simple substring containment, not embedding similarity—predictable and cheap. The registry returns the first matching skill in registration order, so more specific skills should be registered before broad ones (documented in code as an operational convention).

Figure 2. Illustrative trigger matching (implementation uses in on lowercased strings).

3. Execution backends

A skill may define handler (Python callable), python_code (inline), or actions (YAML list of HAL intents). The _run_actions path walks each action and calls context.hal.execute, same entry point as validated NLU output. Async handlers are awaited.

SkillContext(intent=..., hal=self.hal, config=..., raw_text=text)

Listing skills via SkillRegistry.list_skills exposes metadata for dashboards and APIs; clear exists for tests.

4. Scope and limitations

This note does not cover discovery of skills from disk, versioning, or sandboxing of inline Python. Overlapping triggers between two skills remain an operator concern; future work could add priority fields or explicit disambiguation.

References

[1] voxyn codebase. https://github.com/voxyn-io/voxyn — see voxyn/skills/registry.py, voxyn/skills/base.py, voxyn/core/pipeline.py.