Skip to content

Architecture Overview

mirai-shared-skills is a centralized catalog of BaseSkill implementations that compose with mirai-agent-core. It exists because duplicating skill code across client repos is an anti-pattern: every client that needs a Neo4j retriever, a PDF extractor, an HTTP browser, or a database adapter would otherwise reimplement the wiring, the auth handoff, and the security policy from scratch. Centralizing them as a shared package makes the same skill testable, versionable, and (per ADR-0001) categorically signposted as safe-by-default or wrap-before-use.

This page describes the package layout, the contract every skill follows, the in-process descriptor registry, and how a skill's tools flow from agent-core's SemanticRouter back to the agent. For decision rationale, see the ADR index. For the per-ADR module map, see ADR-to-Module Map.

Per-skill data flow

                           ┌───────────────────────────┐
   user turn  ────────────►│  agent-core engine        │
                           │  ─ SemanticRouter         │  picks skills (ADR-0008 in agent-core)
                           │  ─ ephemeral Pydantic AI  │
                           │    Agent                  │
                           └─────────────┬─────────────┘
                                         │ active_skills
                                         ▼
                           ┌───────────────────────────┐
                           │  shared_skills.<Skill>    │
                           │  ─ BaseSkill subclass     │
                           │  ─ get_tools() →          │  Tool objects via
                           │      [tool_from_function] │  ADR-0007
                           └─────────────┬─────────────┘
                                         │ Tool list
                                         ▼
                           ┌───────────────────────────┐
                           │  SecureSkill wrapper      │  enforces policy per
                           │  (downstream client)      │  ADR-0001 + agent-core ADR-0012
                           └─────────────┬─────────────┘
                                         │ filtered Tool list
                                         ▼
                           ┌───────────────────────────┐
                           │  ephemeral Pydantic AI    │  dispatches tool calls
                           │  Agent                    │
                           └─────────────┬─────────────┘
                                         │ tool result envelope
                                         ▼
                                    AG-UI stream  ──► UI / caller

Three substrates feed each other:

Layer Owned by Responsibility
Routing & engine mirai-agent-core Picks active skills per turn, dispatches tool calls, emits AG-UI events.
Skill catalog mirai-shared-skills (this repo) Defines BaseSkill subclasses with get_tools(), ships descriptors via the registry, exposes references for lazy guidance.
Security policy downstream client Wraps each shared skill in SecureSkill with per-tool SecurityLevels. Decisions about which tables are HITL'd belong here, not in the catalog.

Package layout

mirai_shared_skills/
├── __init__.py             # bootstrap([SkillDescriptor, ...]) — registers all 8 skills
├── _registry.py            # SkillCategory, SkillDescriptor, register/get/find/all_descriptors
│
├── discovery/              # find-skills (standard)
│   ├── skill.py            # SkillDiscoverySkill, load_skill_instructions
│   └── references/
│
├── execution/              # execution-debugging (raw — sandbox subprocess)
│   ├── skill.py            # ExecutionDebuggingSkill
│   ├── scripts/
│   └── references/
│
├── auth_gates/             # authentication-gates (standard)
│   ├── skill.py            # AuthenticationGatesSkill, CredentialHandoff
│   └── references/
│
├── browser/                # agent-browser (standard)
│   ├── skill.py            # AgentBrowserSkill
│   └── references/
│
├── pdf_extraction/         # pdf-extraction (standard)
│   └── skill.py            # PdfExtractionSkill
│
├── agentic_rag/            # agentic-rag (standard, uses providers)
│   ├── skill.py            # AgenticRAGSkill, token-budget logic (ADR-0006)
│   ├── models.py           # RAGContextChunk, RetrievalQuery
│   ├── providers/          # Neo4jGraphProvider, AzureSearchProvider, … (ADR-0002)
│   ├── eval/               # deepeval harness ([eval] extra)
│   ├── scripts/            # Cypher templates
│   └── references/
│
├── weather.py              # weather-api (standard)
└── database.py             # database-operations (raw — arbitrary SQL)

Module map

Module Responsibility
mirai_shared_skills._registry SkillCategory, SkillDescriptor, registry helpers (ADR-0004).
mirai_shared_skills.__init__ Calls bootstrap([...]) to register every shipped descriptor at import time.
mirai_shared_skills.discovery SkillDiscoverySkill — queries the registry; loads per-skill references on demand (ADR-0008).
mirai_shared_skills.execution ExecutionDebuggingSkill — sandboxed subprocess execution (canonical raw skill, ADR-0001).
mirai_shared_skills.auth_gates AuthenticationGatesSkill, CredentialHandoff (ADR-0005).
mirai_shared_skills.browser AgentBrowserSkill — headless web fetch.
mirai_shared_skills.pdf_extraction PdfExtractionSkill — PDF text extraction via pypdf.
mirai_shared_skills.agentic_rag AgenticRAGSkill + four provider families (ADR-0002, ADR-0003, ADR-0006).
mirai_shared_skills.weather WeatherSkill — public weather API.
mirai_shared_skills.database RawDatabaseSkill — arbitrary SQL execution (raw skill, ADR-0001).

Every skill module exposes its tools via tool_from_function (ADR-0007), so each tool is a plain async method on the skill class with type hints driving the LLM-visible schema.

Where the design choices live

Architectural decisions are recorded as ADRs — see the ADR index. Each ADR captures the context, decision, and consequences for one substantial choice (skill categorization, provider abstraction, optional extras, descriptor registry, auth handoff, token budgeting, tool construction style, and references-as-files).