Skills — the capability layer

What a skill is#

A skill is one capability of the single consciousness. There is one loop — the consciousness — and a skill plugs into it by doing any subset of these:

File: src/core/skills/base.py

class Skill:
    name: str                        # unique id, e.g. "voice:discord"
    skill_name: Optional[str] = None # config/UI toggle key; None = core, always on

    def __init__(self, config, bus, expression, context=None)
    def initialize(self) -> None                  # one-time setup, no connections
    async def start(self) -> None                 # gated by `enabled`
    async def stop(self) -> None

enabled reads config.skills[skill_name].enabled. The UI is the single source of truth — Bea can never arm a capability by herself. A skill with skill_name = None is core: always on, never shown as a toggle.

SkillRegistry#

The catalog. It has no loop and no scheduler: the consciousness iterates it when it builds a prompt or dispatches a tool.

registry.all()              # every skill
registry.active()           # the ones currently running
registry.toggleable()       # the ones with a config key (what the UI lists)
registry.get(name)          # by `name`
registry.get_by_key(key)    # by `skill_name`
registry.context_sections() # static rules from active skills
registry.dynamic_context(batch)
registry.tools()            # every tool from every active skill

Everything is built in AIVtuberBrain._build_consciousness() and started by Consciousness.start(), which calls start() on each one.

The skills#

Tools by owner#

speak and stay_silent belong to the mind itself (src/core/mind/tools.py), not to a skill. Everything else is armed by whichever skill is active:

Some of those are armed by the skill's own state rather than by its toggle: discord_leave_voice only while she is in a call, the objective_* tools only while there is a plan, recall_donors only once somebody has donated, the game tools only while the mod is connected. So the registry is assembled from the live skills on every read rather than cached — the whole set costs microseconds, and a prompt naming a tool the schema does not carry is a call she invents. unarmed (src/core/mind/operating.py) logs an ERROR when the two disagree.

Written answers go through the unified tools — send_message(platform, channel, text), react, say_nothing — with the destination in the arguments. send_message names, and accepts, only the platforms something can actually deliver to: minecraft is typed into with mc_chat and a donation has no channel to answer in, so neither is a destination. There is no speak on a written channel: answering out loud is impossible by construction, not by a rule in the prompt.

Two shapes of skill#

A platform (Discord, Telegram, Twitch) extends PlatformSkill (src/core/skills/platform.py) instead of Skill. It only owes three things — platform, a way to build an Author, and a way to send text — and inherits perception building, the humanizer delivery and the conversation tools.

Everything else extends Skill directly.

Adding a skill#

1. Create src/core/skills/my_skill/surface.py:

from src.core.skills.base import Skill


class MySkill(Skill):
    name = "my:skill"
    skill_name = "my_skill"   # the config/UI toggle key

    def initialize(self) -> None:
        self.setting = self.config.skills.get("my_skill", {}).get("setting", "default")

    def tools(self):
        if not self.active:
            return []
        return [...]

2. Add it to the tuple in AIVtuberBrain._build_consciousness().
3. Add its block to config.example.json under skills.

It now appears in the dashboard's Skills page and can be toggled at runtime.

If it is a text platform, extend PlatformSkill instead and the roster, person cards and attention priorities work with no extra code — they are all keyed on Author and conversation_key.