feat: yesno/selection agent plugins

.github/workflows/build_tests.yml

@@ -12,3 +12,4 @@ jobs:
     secrets: inherit
     with:
       test_path: 'test/unittests'
+      install_extras: 'test'

README.md

@@ -1,3 +1,62 @@
 # OVOS Workshop
-OVOS Workshop contains skill base classes and supporting tools to build skills
-and applications for OpenVoiceOS systems.
+
+Base classes, decorators, and helpers for building skills and applications for OpenVoiceOS.
+
+## Install
+
+```bash
+pip install ovos-workshop
+```
+
+Runtime dependencies include `ovos-yes-no-plugin` and `ovos-option-matcher-fuzzy-plugin`, which back the `ask_yesno` and `ask_selection` skill methods.
+
+## Quick Start
+
+```python
+from ovos_workshop.skills.ovos import OVOSSkill
+from ovos_workshop.decorators import intent_handler
+
+
+class HelloWorldSkill(OVOSSkill):
+
+    @intent_handler("hello.intent")
+    def handle_hello(self, message):
+        self.speak_dialog("hello.response")
+
+
+def create_skill():
+    return HelloWorldSkill()
+```
+
+Register in `pyproject.toml`:
+
+```toml
+[project.entry-points."opm.skills"]
+hello-world-skill = "hello_world_skill:HelloWorldSkill"
+```
+
+## Configuration
+
+Key settings a skill can accept in its `settings.json`:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `ask_yesno_plugin` | `ovos-solver-yes-no-plugin` | YesNoEngine plugin used by `ask_yesno()` |
+| `ask_selection_plugin` | `ovos-option-matcher-fuzzy-plugin` | OptionMatcherEngine plugin used by `ask_selection()` |
+
+Both keys can also be set system-wide under the `skills` block in `mycroft.conf`.
+
+## Documentation
+
+Full reference is in [`docs/`](docs/index.md):
+
+- [Skill classes](docs/skill-classes.md)
+- [OVOSSkill base class](docs/ovos-skill.md)
+- [ask_yesno / ask_selection plugin system](docs/skill-interaction.md)
+- [Decorators](docs/decorators.md)
+- [Settings](docs/settings.md)
+- [Resource files](docs/resource-files.md)
+
+## License
+
+Apache 2.0

docs/index.md

@@ -68,6 +68,7 @@ OVOSSkill                             ovos_workshop/skills/ovos.py
 | [app.md](app.md) | `OVOSAbstractApplication` | Skill-like app that runs without the intent service |
 | [game-skill.md](game-skill.md) | `OVOSGameSkill`, `ConversationalGameSkill` | OCP-integrated game loop with converse and auto-save |
 | [auto-translatable.md](auto-translatable.md) | `UniversalSkill`, `UniversalFallback` | Auto-translate input/output for any language |
+| [skill-interaction.md](skill-interaction.md) | `OVOSSkill.ask_yesno`, `OVOSSkill.ask_selection` | Pluggable yes/no and option-selection engines |
 | [skill-api.md](skill-api.md) | `SkillApi`, `skill_api_method` | Inter-skill RPC over the MessageBus |
 | [filesystem.md](filesystem.md) | `FileSystemAccess` | Sandboxed, XDG-compliant file storage for skills |
 | [resource-files.md](resource-files.md) | `SkillResources` | Locale, dialog, vocab, regex, and other resource files |

docs/ovos-skill.md

@@ -120,6 +120,8 @@ choice = self.ask_selection(["A", "B", "C"], "Pick one")
 
 `get_response` suspends the converse channel for this skill until the user responds or a timeout is hit. Raise `AbortQuestion` to cancel gracefully.
 
+`ask_yesno` and `ask_selection` are backed by pluggable engine plugins. The active plugin can be set per-skill via `settings.json` (`ask_yesno_plugin`, `ask_selection_plugin`) or system-wide in `mycroft.conf` under the `skills` block. Defaults are `ovos-solver-yes-no-plugin` and `ovos-option-matcher-fuzzy-plugin`, both installed as runtime dependencies. See [skill-interaction.md](skill-interaction.md) for full configuration reference.
+
 ## Intent Registration
 
 ```python