feat: skills — SKILL.md files loaded on demand (#252) (#302)

* WIP: skills (#252) from engineer run 01ec3c9f; migration renumbered to 0022

* feat: skills — SKILL.md files loaded on demand (#252)

Port OpenCode's MIT-licensed skill mechanism to Python: discover
skills/**/SKILL.md under the workspace and the OpenBot state dir, put only
names/descriptions in the system prompt, add a per-bot load_skill tool that
returns a skill's body + base dir + sibling files, and per-bot enablement
(bot_profiles.skill_names, migration 0022) validated against discoverable
ids via the API. Frontend: GET /tools/skills-backed skill picker in the bot
editor; GET /api/v1/tools/skills lists discovered skills.

Also: busy indicator text 'busy, waiting...' -> 'waiting...' (label +
aria-label, tests updated).

* fix: add skill_names to the remaining Bot test fixtures

Making skill_names required on the Bot type broke three other test
factories (botActivity, BotPage, SaveFeedback) that construct a full Bot;
my local tsc check was blinded by an incremental cache, CI caught it.

Author: regnull

backend/openbot/api/bots.py

@@ -21,7 +21,7 @@
     ScratchpadOut,
     bot_out,
 )
-from openbot.api.tool_validation import known_tool
+from openbot.api.tool_validation import known_skill_names, known_tool
 from openbot.db.models import (
     ACTIVE_RUN_STATUSES,
     OPEN_RUN_STATUSES,
@@ -50,14 +50,20 @@ async def _usage_for(session: AsyncSession, actor_id: str) -> dict[str, int | fl
     return dict(zip(USAGE_FIELDS, row, strict=True))
 
 
-def _validate_tools(services: Services, tool_names: list[str], approval_tools: list[str]) -> None:
+def _validate_tools(services: Services, tool_names: list[str], approval_tools: list[str],
+                    skill_names: list[str] | None = None) -> None:
     if tool_names:
         unknown = [t for t in tool_names if not known_tool(services, t)]
         if unknown:
             raise HTTPException(422, f"unknown tools: {unknown}")
     extra = [t for t in approval_tools if t not in tool_names]
     if extra:
         raise HTTPException(422, f"approval_tools must be a subset of tool_names: {extra}")
+    if skill_names:
+        known = known_skill_names(services)
+        unknown = [s for s in skill_names if s.lower() not in known]
+        if unknown:
+            raise HTTPException(422, f"unknown skills: {unknown}")
 
 
 def _validate_model(provider: str, model: str, model_settings: dict | None = None) -> None:
@@ -92,7 +98,7 @@ async def list_bots(session: AsyncSession = Depends(get_session)):
 @router.post("", response_model=BotOut, status_code=201)
 async def create_bot(body: BotCreate, session: AsyncSession = Depends(get_session),
                      services: Services = Depends(get_services)):
-    _validate_tools(services, body.tool_names, body.approval_tools)
+    _validate_tools(services, body.tool_names, body.approval_tools, body.skill_names)
     _validate_model(body.provider, body.model, body.model_settings)
     if await handle_taken(session, body.handle):
         raise HTTPException(409, "handle already exists")
@@ -136,8 +142,9 @@ async def install_catalog_entry(entry_id: str, body: BotCatalogInstall | None =
     data = {"handle": handle, "name": item.name, "description": item.description, "icon": item.icon,
             "instructions": instructions, "provider": "auto", "model": "", "model_settings": item.model_settings,
             "tool_names": list(item.tool_names), "approval_tools": list(item.approval_tools),
+            "skill_names": list(item.skill_names),
             "memory_enabled": True, "load_repository_instructions": item.load_repository_instructions, "enabled": True}
-    _validate_tools(services, data["tool_names"], data["approval_tools"])
+    _validate_tools(services, data["tool_names"], data["approval_tools"], data["skill_names"])
     actor = Actor(kind="bot", **{k: data.pop(k) for k in ACTOR_FIELDS}, bot=BotProfile(**data))
     session.add(actor)
     try:
@@ -162,7 +169,8 @@ async def update_bot(bot_id: str, body: BotUpdate, session: AsyncSession = Depen
                      services: Services = Depends(get_services)):
     actor = await _get_bot_or_404(session, bot_id)
     data = body.model_dump(exclude_unset=True)
-    _validate_tools(services, data.get("tool_names", actor.bot.tool_names), data.get("approval_tools", actor.bot.approval_tools))
+    _validate_tools(services, data.get("tool_names", actor.bot.tool_names), data.get("approval_tools", actor.bot.approval_tools),
+                    data.get("skill_names", actor.bot.skill_names))
     _validate_model(data.get("provider", actor.bot.provider), data.get("model", actor.bot.model),
                     data.get("model_settings", actor.bot.model_settings))
     if "handle" in data and data["handle"] != actor.handle and await handle_taken(session, data["handle"]):

backend/openbot/api/schemas.py

@@ -70,6 +70,7 @@ class BotCreate(BaseModel):
     tool_names: list[str] = []
     approval_tools: list[str] = []
     memory_enabled: bool = True
+    skill_names: list[str] = []
     load_repository_instructions: bool = False
     enabled: bool = True
 
@@ -103,6 +104,7 @@ class BotUpdate(BaseModel):
     tool_names: list[str] | None = None
     approval_tools: list[str] | None = None
     memory_enabled: bool | None = None
+    skill_names: list[str] | None = None
     load_repository_instructions: bool | None = None
     enabled: bool | None = None
 
@@ -132,6 +134,7 @@ class BotOut(BaseModel):
     tool_names: list[str]
     approval_tools: list[str]
     memory_enabled: bool
+    skill_names: list[str]
     load_repository_instructions: bool
     model_calls: int = 0
     prompt_tokens: int = 0
@@ -430,6 +433,7 @@ def bot_out(actor, *, active: bool = False, usage: dict[str, int | float] | None
                   icon=p.icon or DEFAULT_BOT_ICON, enabled=actor.enabled, active=active,
                   instructions=p.instructions, provider=p.provider, model=p.model, model_settings=p.model_settings,
                   tool_names=p.tool_names, approval_tools=p.approval_tools, memory_enabled=p.memory_enabled,
+                  skill_names=p.skill_names,
                   load_repository_instructions=p.load_repository_instructions,
                   model_calls=int(usage.get("model_calls", 0)), prompt_tokens=int(usage.get("prompt_tokens", 0)),
                   completion_tokens=int(usage.get("completion_tokens", 0)), cache_read_tokens=int(usage.get("cache_read_tokens", 0)),
@@ -519,6 +523,7 @@ class BotCatalogEntryOut(BaseModel):
     tool_names: list[str]
     approval_tools: list[str]
     model_settings: dict[str, Any]
+    skill_names: list[str] = []
     load_repository_instructions: bool = False
 
 

backend/openbot/api/tool_validation.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from openbot.services import Services
+from openbot.skills import discover_skills
 
 
 def known_tool(services: Services, name: str) -> bool:
@@ -10,3 +11,22 @@ def known_tool(services: Services, name: str) -> bool:
     if services.mcp is not None and "__" in name:
         return services.mcp.has(name.split("__", 1)[0])
     return False
+
+
+def known_skill_names(services: Services) -> set[str]:
+    """Skill ids and names discoverable right now (workspace + state dir), case-folded.
+
+    Tolerates a None settings registry the same way known_tool does, so tests and early
+    boot can call it.
+    """
+    settings = getattr(services, "settings", None)
+    if settings is None:
+        return set()
+    roots = [settings.workspace_root]
+    state_dir = getattr(settings, "state_dir", None)
+    if state_dir is not None:
+        roots.append(state_dir)
+    skills = discover_skills(*[root for root in roots if root is not None])
+    folded = {s.id.lower() for s in skills}
+    folded.update(s.name.lower() for s in skills)
+    return folded

backend/openbot/api/tools.py

@@ -2,6 +2,7 @@
 
 from openbot.api.deps import get_services
 from openbot.services import Services
+from openbot.skills import discover_skills
 
 router = APIRouter(prefix="/tools", tags=["tools"])
 
@@ -26,3 +27,19 @@ async def list_tools(services: Services = Depends(get_services)):
         ],
         "errors": reg.load_errors,
     }
+
+
+@router.get("/skills")
+async def list_skills(services: Services = Depends(get_services)):
+    """Discovered skills for the bot editor's per-bot skill picker."""
+    settings = services.settings
+    roots = [settings.workspace_root]
+    state_dir = settings.state_dir
+    if state_dir is not None and state_dir.resolve() != settings.workspace_root.resolve():
+        roots.append(state_dir)
+    return {
+        "skills": [
+            {"id": s.id, "name": s.name, "description": s.description, "path": s.path}
+            for s in discover_skills(*roots)
+        ]
+    }

backend/openbot/bots/catalog.py

@@ -21,6 +21,7 @@ class BotCatalogEntry(BaseModel):
     tool_names: tuple[str, ...] = ()
     approval_tools: tuple[str, ...] = ()
     model_settings: dict = {}
+    skill_names: tuple[str, ...] = ()
     load_repository_instructions: bool = False
 
 

backend/openbot/config.py

@@ -147,6 +147,14 @@ def _apply_root_directory_defaults(self):
             self.secret_key_file = root / ".openbot" / "secret.key"
         return self
 
+    @property
+    def state_dir(self) -> Path | None:
+        """OpenBot's own state directory: skills shipped with the app live in `<root>/.openbot/skills`,
+        where workspace tools refuse to go but skill loading deliberately reads."""
+        if self.root_directory is None:
+            return None
+        return Path(self.root_directory) / ".openbot"
+
     @model_validator(mode="after")
     def _default_log_file(self):
         """Without an explicit LOG_FILE, log beside the database (after the root-directory defaults, which

backend/openbot/db/migrations/versions/0022_bot_skill_names.py

@@ -0,0 +1,20 @@
+"""bot skill_names: which skills a bot may load on demand
+
+Revision ID: 0021
+Revises: 0020
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0022"
+down_revision = "0021"
+branch_labels = depends_on = None
+
+
+def upgrade():
+    op.add_column("bot_profiles", sa.Column("skill_names", sa.JSON(), nullable=False, server_default=sa.text("'[]'")))
+
+
+def downgrade():
+    op.drop_column("bot_profiles", "skill_names")

backend/openbot/db/models.py

@@ -101,6 +101,7 @@ class BotProfile(Base):
     tool_names: Mapped[list] = mapped_column(JSON, default=list, nullable=False)
     approval_tools: Mapped[list] = mapped_column(JSON, default=list, nullable=False)
     memory_enabled: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    skill_names: Mapped[list] = mapped_column(JSON, default=list, nullable=False)
     load_repository_instructions: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
     actor: Mapped[Actor] = relationship(back_populates="bot")
 

backend/openbot/runtime/prompt.py

@@ -7,6 +7,7 @@
 
 from openbot.db.models import Actor, Message
 from openbot.runtime.tool_loading import deferred_tools_section
+from openbot.skills import SkillInfo, skills_section
 from openbot.tools.builtin.scratchpad import scratchpad_section
 from openbot.tools.builtin.todo import todo_list_section
 
@@ -167,6 +168,7 @@ def build_system_prompt(
     scoped: bool = False,
     todos: list[dict] | None = None,
     scratchpad: str | None = None,
+    skills: list[SkillInfo] | None = None,
     deferred_tools: list[str] | None = None,
 ) -> str:
     stable, dynamic = build_system_prompt_parts(
@@ -181,6 +183,7 @@ def build_system_prompt(
         scoped=scoped,
         todos=todos,
         scratchpad=scratchpad,
+        skills=skills,
         deferred_tools=deferred_tools,
     )
     return stable + dynamic
@@ -199,6 +202,7 @@ def build_system_prompt_parts(
     scoped: bool = False,
     todos: list[dict] | None = None,
     scratchpad: str | None = None,
+    skills: list[SkillInfo] | None = None,
     deferred_tools: list[str] | None = None,
 ) -> tuple[str, str]:
     roster = (
@@ -258,6 +262,8 @@ def build_system_prompt_parts(
         dynamic += f"\n\n{scratchpad_section(scratchpad)}"
     if todos:
         dynamic += f"\n\n{todo_list_section(todos)}"
+    if skills:
+        dynamic += f"\n\n{skills_section(skills)}"
     repository_instructions = load_repository_instructions(
         workspace_root, enabled=bot.bot.load_repository_instructions, start_directory=workspace_root
     )

backend/openbot/runtime/runner.py

@@ -62,6 +62,7 @@
     UpstreamPins,
     upstream_of,
 )
+from openbot.skills import enabled_skills
 from openbot.tools.builtin.core import CORE_TOOLS
 from openbot.tools.builtin.scheduling import SCHEDULING_TOOLS
 from openbot.tools.builtin.scratchpad import load_scratchpad
@@ -683,6 +684,13 @@ async def _prepare(self, bot: Actor, thread: Thread, run: Run) -> tuple[str, dic
             else []
         )
         workspace_root = thread_workspace_root(st.workspace_root, thread.working_directory)
+        # Skills the bot has enabled: only ids/names/descriptions go into the prompt;
+        # the load_skill tool fetches the body on demand.
+        skills = (
+            enabled_skills(bot.bot, workspace_root, self.s.settings)
+            if "load_skill" in bot.bot.tool_names
+            else []
+        )
         deferred = set(self.deferred_tool_names(bot))
         stable_prompt, dynamic_prompt = build_system_prompt_parts(
             bot=bot,
@@ -702,6 +710,7 @@ async def _prepare(self, bot: Actor, thread: Thread, run: Run) -> tuple[str, dic
             scoped=scoped,
             todos=todos,
             scratchpad=scratchpad,
+            skills=skills,
             deferred_tools=[n for n in bot.bot.tool_names if n in deferred],
         )
         prompt = SystemMessage(