OVOSSkill¶

In a nutshell

A "skill" is an add-on that teaches your voice assistant to do one new thing, like telling the weather or setting a timer. Every skill is built on top of a shared starter kit called OVOSSkill, which quietly handles the housekeeping: starting up, listening for commands, speaking replies, remembering settings, and shutting down. The reference below covers that starter kit and its methods. New to all this? Start with Skill Classes or the Glossary.

Module: ovos_workshop.skills.ovos.OVOSSkill

OVOSSkill is the base class that all OVOS skills inherit from. It handles startup, intent registration, resource loading, settings, event management, GUI, and shutdown.

Constructor, lifecycle, and startup/shutdown sequence

The constructor signature, the lifecycle methods to override (initialize(), stop(), shutdown(), etc.), and the full startup/shutdown sequence are documented once, on Skill Classes. The sections below cover OVOSSkill's remaining surface: properties, speaking, user input, scheduling, SkillApi, and the bus events it handles.

Key Properties¶

Session-aware (read from current Session)¶

Property	Type	Description
`lang`	`str`	BCP-47 language of the current request
`core_lang`	`str`	Default configured language
`secondary_langs`	`list`	Configured secondary languages
`native_langs`	`list`	`core_lang` + `secondary_langs`
`location`	`dict`	Location preferences
`location_pretty`	`str`	City name
`location_timezone`	`str`	Timezone code
`system_unit`	`str`	`"metric"` or `"imperial"`
`date_format`	`str`	`"DMY"`, `"MDY"`, or `"YMD"`
`time_format`	`str`	`"half"` or `"full"`

Infrastructure¶

Property	Type	Description
`settings`	`JsonStorage`	Persistent skill settings
`bus`	`MessageBusClient`	messagebus connection
`gui`	`SkillGUI`	GUI interface
`enclosure`	`EnclosureAPI`	Mark 1 faceplate interface (⚠️ being removed from the base class like `self.gui`, moves to `ovos-mark1-utils`, faceplate becomes a GUI plugin)
`file_system`	`FileSystemAccess`	Managed local file access
`resources`	`SkillResources`	Resource files for `self.lang`
`dialog_renderer`	`MustacheDialogRenderer`	Render dialog templates
`event_scheduler`	`EventSchedulerInterface`	Schedule future bus events
`intent_service`	`IntentServiceInterface`	Register/manage intents
`intent_layers`	`IntentLayers`	Manage intent layer sets
`audio_service`	`OCPInterface`	Control audio/OCP playback
`translator`	`OVOSLangTranslation`	Language translation (lazy init)
`lang_detector`	`OVOSLangDetection`	Language detection (lazy init)
`is_fully_initialized`	`bool`	True after `_startup` completes
`reload_skill`	`bool`	Set to `False` to prevent hot-reload

Speaking¶

self.speak("Hello world")
self.speak_dialog("my.dialog.file")            # uses locale/lang/dialog/my.dialog.file
self.speak_dialog("my.dialog", data={"name": "Alice"})  # Mustache templating

self.speak("Anything else?", expect_response=True)  # speak, then listen for a reply

Both speak() and speak_dialog() accept expect_response=False. Set it to True and OVOS re-opens the microphone as soon as the prompt finishes speaking, so the user's next utterance is captured without a wake word. This is the basis of a follow-up question. (To capture and return that reply inside your handler, use get_response instead. See Getting User Input below and the Skill Cookbook.)

Playing audio files¶

self.play_audio(self.find_resource("chime.mp3", "snd"))

play_audio(filename, instant=False, wait=False) queues (or, with instant=True, immediately plays) an audio file through ovos-audio. filename must be a path to a real file on disk or a URI. play_audio does not search skill resource directories for you, so resolve the path yourself first, typically with self.find_resource(name, "snd") (looking up <skill>/snd/<name> or a locale-specific variant). Pass wait=True to block until playback finishes or a 30-second default timeout elapses, or wait=<seconds> for a custom timeout.

Getting User Input¶

get_response, ask_yesno, and ask_selection ask the user a question and capture the reply. See Asking the User for Responses for the full reference, including the validator, on_fail, and num_retries options.

Intent Registration¶

# Padatious (intent file)
self.register_intent_file("my.intent", self.handler)

# Adapt (vocab-based)
from ovos_workshop.intents import IntentBuilder
intent = IntentBuilder("MyIntent").require("Keyword").build()
self.register_intent(intent, self.handler)

# Vocabulary keywords
self.register_vocabulary("hello", "HelloKeyword")
self.register_entity_file("food.entity")

Context Management¶

self.set_context("MyContext", "value")
self.remove_context("MyContext")

Scheduling Events¶

Skills can ask the event_scheduler to call a handler at a future time, once or repeatedly:

import datetime

# once, 60 seconds from now
self.schedule_event(self.handle_timeout, 60, name="my-timeout")

# once, at a specific point in time
self.schedule_event(self.handle_timeout, datetime.datetime.now() + datetime.timedelta(hours=1),
                    name="my-timeout")

# repeating every 30 minutes, starting 30 minutes from now
self.schedule_repeating_event(self.handle_tick, None, 60 * 30, name="my-tick")

# cancel a scheduled event by name
self.cancel_scheduled_event("my-tick")

schedule_event(handler, when, data=None, name=None, context=None): single-shot. when is either a datetime or a number of seconds from now. A naive datetime (no tzinfo) is stamped with the assistant's configured timezone (location.timezone.code), not the OS/process timezone. A device on the stock config is in Lawrence, Kansas until its location is set.
schedule_repeating_event(handler, when, frequency, data=None, name=None, context=None): repeating. frequency is the interval in seconds between calls. when=None fires the first call frequency seconds from now. Pass a datetime/number to control the first firing explicitly.
Both accept an optional name used to reference/cancel the event later with cancel_scheduled_event(name). Re-scheduling schedule_event under a name that already has a pending one-shot replaces it, so a skill that re-creates its schedules on every load does not accumulate duplicates. schedule_repeating_event does not replace an existing repeating schedule of the same name. Cancel it first. update_scheduled_event changes an existing event's payload without touching its fire time; get_scheduled_event_status returns None (not an exception) when nothing is scheduled under that name. A repeating schedule survives skill shutdown/restart. It is tied to the skill id, not the running process.
Scheduled events are persisted by the EventScheduler so they survive an ovos-core restart. They are not tied to the skill instance staying in memory. See Scheduled Events for the misfire policy and replay guarantees behind this.

Public Skill API¶

Decorate a method with @skill_api_method to expose it over the bus. Other skills or tools can call it via SkillApi. The full RPC mechanism — discovery, call protocol, the SkillApi proxy class, and a worked client/server example — is documented on Skill API: Inter-Skill RPC.

RuntimeRequirements¶

Note

RuntimeRequirements is a deprecated mechanism. See Runtime Requirements for what it does.

Override the class property to declare connectivity needs:

from ovos_utils import classproperty
from ovos_utils.process_utils import RuntimeRequirements

@classproperty
def runtime_requirements(self):
    return RuntimeRequirements(
        network_before_load=False,
        internet_before_load=False,
        gui_before_load=False,
        requires_internet=False,
        requires_network=False,
        requires_gui=False,
        no_internet_fallback=False,
        no_network_fallback=False,
        no_gui_fallback=True,
    )

All nine fields default True except gui_before_load, requires_gui, and no_internet_fallback/no_network_fallback (default False), and no_gui_fallback (default True). This is used by SkillManager to defer loading until the required connectivity is available.

System Bus Events Handled (per skill)¶

Event	Description
`mycroft.stop`	Global stop broadcast, cease all activity for the inbound session
`{skill_id}.stop`	Skill-directed stop, cease the stoppable activity for the inbound session
`{skill_id}.stop.ping`	Check if the skill can stop. The base class answers with `{skill_id}.stop.response` carrying whether it can handle the stop
`{skill_id}.converse.get_response`	Feed user response to `get_response`
`mycroft.skill.enable_intent`	Enable a disabled intent (the bus-facing counterpart to calling `self.enable_intent(intent_name)` from Python)
`mycroft.skill.disable_intent`	Disable an active intent (the bus-facing counterpart to calling `self.disable_intent(intent_name)` from Python)
`mycroft.skill.set_cross_context`	Set cross-skill context
`mycroft.skill.remove_cross_context`	Remove cross-skill context
`mycroft.skills.settings.changed`	Remote settings update
`ovos.skills.settings_changed`	Local settings file changed
`question:query`	Common query pipeline request
`ovos.common_query.ping`	Common query service discovery
`question:action.{skill_id}`	Common query callback (this skill's answer was selected)
`question:action`	Common query callback (generic, any skill's answer was selected)
`homescreen.metadata.get`	Homescreen requesting metadata
`{skill_id}.public_api`	Skill API introspection

A skill subscribes to both stop topics (OVOS-STOP-1 §9): {skill_id}.stop, the targeted dispatch that ceases only its own stoppable activity for the inbound session, and mycroft.stop, the universal broadcast that ceases everything for that session. A duplicate arrival on either topic while the skill is already stopping is a no-op. See the Stop Pipeline.