Architecture Decision Records

ADRs capture the context, decision, and consequences of substantial architectural choices in mirai-shared-skills. They are the canonical source of design rationale; guides and skill pages should link here rather than restate it. Each ADR is dated, attributed, and tagged with its Status and Implementation State. They are immutable once accepted — a superseding decision creates a new ADR rather than editing an existing one.

#	Title	One-line summary
001	Standard vs Raw Skill Categorization	Two-tier SkillCategory taxonomy at the descriptor level — standard skills are safe to attach directly; raw skills must be wrapped in SecureSkill by the downstream client.
002	Pluggable Provider Pattern for Multi-Source Retrieval	AgenticRAGSkill accepts graph, vector, web, and reranker providers as Protocol-typed constructor arguments so backends are swappable without changing skill code.
003	Optional-Dependency Extras for Backend Drivers	Backend SDKs (neo4j, azure-search-documents, cohere, deepeval) live behind [project.optional-dependencies] extras with typed *UnavailableError failure modes.
004	In-Process Skill Descriptor Registry	Module-level descriptor registry populated by an explicit bootstrap([...]) call in __init__.py; zero runtime discovery overhead.
005	Authentication Gates as a Capability Skill	HTTP 401/403 interception is a first-class skill (AuthenticationGatesSkill) with structured CredentialHandoff payloads, composing with agent-core's HITL primitive.
006	Token-Budgeted RAG Context Assembly	AgenticRAGSkill enforces a configurable token budget with a citation safety buffer; estimates use a tokenizer-free chars / 4 heuristic.
007	Functional Tool Construction via tool_from_function	Every shared skill builds its tools from plain async methods via tool_from_function, never by subclassing Pydantic AI's Tool.
008	References-as-Files for Lazy Instructional Payloads	Long-form per-skill guidance lives in references/ directories and is loaded on demand by SkillDiscoverySkill.load_skill_instructions; system prompts stay short.