Skip to content

Registry — API

The skill descriptor registry — described architecturally in ADR-0004 — exposes a small set of helpers for registering, looking up, and enumerating SkillDescriptor records.

mirai_shared_skills._registry

Catalog metadata registry consumed by the Skill Discovery foundational skill.

The registry is intentionally an in-process structure: every shared skill declares a small descriptor that lists the human-readable name used by the semantic router, the categorisation (standard for read-only or raw for state-mutating), and the dotted import path of its implementation. The discovery skill queries this registry instead of crawling the package, which keeps look-ups deterministic and side-effect free.

SkillCategory module-attribute 

SkillCategory = Literal['standard', 'raw']

__all__ module-attribute 

__all__ = [
    "SkillCategory",
    "SkillDescriptor",
    "all_descriptors",
    "bootstrap",
    "find",
    "get",
    "register",
]

SkillDescriptor dataclass 

SkillDescriptor(
    name: str,
    description: str,
    instructions: str,
    category: SkillCategory,
    import_path: str,
    tools: tuple[str, ...] = tuple(),
    references: tuple[str, ...] = tuple(),
)

Static metadata describing a shared skill catalog entry.

category instance-attribute 

category: SkillCategory

description instance-attribute 

description: str

import_path instance-attribute 

import_path: str

instructions instance-attribute 

instructions: str

name instance-attribute 

name: str

references class-attribute instance-attribute 

references: tuple[str, ...] = field(default_factory=tuple)

tools class-attribute instance-attribute 

tools: tuple[str, ...] = field(default_factory=tuple)

all_descriptors 

all_descriptors() -> Mapping[str, SkillDescriptor]

Return an immutable view of every registered descriptor.

Source code in mirai_shared_skills/_registry.py 
42
43
44
def all_descriptors() -> Mapping[str, SkillDescriptor]:
    """Return an immutable view of every registered descriptor."""
    return dict(_CATALOG)

bootstrap 

bootstrap(descriptors: Iterable[SkillDescriptor]) -> None

Bulk-register descriptors. Used by the package __init__.

Source code in mirai_shared_skills/_registry.py 
65
66
67
68
def bootstrap(descriptors: Iterable[SkillDescriptor]) -> None:
    """Bulk-register descriptors. Used by the package `__init__`."""
    for descriptor in descriptors:
        register(descriptor)

find 

find(query: str) -> list[SkillDescriptor]

Case-insensitive substring search over name + description.

Source code in mirai_shared_skills/_registry.py 
47
48
49
50
51
52
53
54
55
56
57
def find(query: str) -> list[SkillDescriptor]:
    """Case-insensitive substring search over name + description."""
    needle = query.strip().lower()
    if not needle:
        return list(_CATALOG.values())
    matches: list[SkillDescriptor] = []
    for descriptor in _CATALOG.values():
        haystack = f"{descriptor.name} {descriptor.description}".lower()
        if needle in haystack:
            matches.append(descriptor)
    return matches

get 

get(name: str) -> SkillDescriptor

Retrieve a descriptor by exact name. Raises KeyError when absent.

Source code in mirai_shared_skills/_registry.py 
60
61
62
def get(name: str) -> SkillDescriptor:
    """Retrieve a descriptor by exact name. Raises `KeyError` when absent."""
    return _CATALOG[name]

register 

register(descriptor: SkillDescriptor) -> SkillDescriptor

Register a skill descriptor. Re-registration with the same name overwrites.

Source code in mirai_shared_skills/_registry.py 
36
37
38
39
def register(descriptor: SkillDescriptor) -> SkillDescriptor:
    """Register a skill descriptor. Re-registration with the same name overwrites."""
    _CATALOG[descriptor.name] = descriptor
    return descriptor