OMNISKILL v3.0 Architecture

🎯 Design Principles

OMNISKILL is built on six core principles that guide every design decision:

1. Universal Format
   Write once, deploy everywhere.
2. Composability
   Skills compose into bundles; agents compose into pipelines.
3. Separation of Concerns
   Skills = knowledge, Agents = orchestration, Pipelines = workflow.
4. Self-Improvement
   The system uses its own tools to improve itself.
5. Platform Agnostic
   Adapters handle platform differences.
6. Intelligent Routing
   Complexity-based task classification and model selection.

🏗️ Layer Architecture

OMNISKILL uses a layered architecture with a complexity router at the top and SDK/CLI at the bottom:

                    USER REQUEST
                         ↓
         ┌───────────────────────────────┐
         │   COMPLEXITY ROUTER (P0)      │  ← Prompt Library
         │  (Task classification + model  │
         │   selection + routing logic)   │
         └───────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────┐
│          RUNTIME CONTRACTS (v3)              │
│  (Sessions, policy engine, telemetry,       │
│   replay determinism, MCP trust routing)    │
├─────────────────────────────────────────────┤
│                PIPELINES                     │
│  (Multi-agent workflows with branching)      │
├─────────────────────────────────────────────┤
│                AGENTS                        │
│  (Personas with skill bindings & handoffs)   │
├─────────────────────────────────────────────┤
│              SYNAPSES                        │
│  (Cognitive enhancements — how agents think) │
├─────────────────────────────────────────────┤
│               BUNDLES                        │
│  (Domain kits with meta-skill routing)       │
├─────────────────────────────────────────────┤
│               SKILLS                         │  ← Knowledge Sources
│  (Universal instructions + resources)        │     (GitHub, local,
├─────────────────────────────────────────────┤      URLs, APIs)
│              ADAPTERS                        │
│  (Platform-specific transformations)         │
├─────────────────────────────────────────────┤
│     Claude Code │ Copilot │ Cursor │ ...     │
└─────────────────────────────────────────────┘
                         ↓
                    SDK / CLI

🔄 Data Flow

How a user request flows through the system:

1. User request → Complexity Router classifies task
2. Router decision
   • Complexity level: trivial → simple → moderate → complex → expert
   • Model tier: fast/cheap → standard → premium
   • Target: skill, agent, or pipeline
3. Knowledge source lookup (if needed)
   Fetches external docs/data.
4. Agent/Pipeline execution
   Selects skill(s) based on trigger matching.
5. Skill execution
   Provides instructions + resources + knowledge to the AI model.
6. Output
   Formatted per skill's output contract.
7. Handoff
   Passed to next agent in pipeline (if applicable).

🔀 Cross-Cutting Concerns

Prompt Library (prompts/)

Reusable prompt components used throughout the system:

• router.md — Complexity classification prompts
• system.md — Master OMNISKILL system prompt
• shared.md — Common formatting, citations, error handling
• personas/*.md — Persona-specific prompt templates

Knowledge Sources (skills/knowledge-sources/)

External knowledge integration layer:

• File-based search — grep, find, cat (no vector DB required)
• Content normalization — keeps .md, .yaml, .json, .txt
• Sync system — keeps sources up to date
• Config template — templates/source-config.yaml

SDK Access Layer (sdk/omniskill.py)

Programmatic interface to OMNISKILL:

class OmniSkill:
    def list_skills() -> List[Skill]
    def list_bundles() -> List[Bundle]
    def get_skill(name: str) -> Skill
    def route(request: str) -> Route
    def install(platform: str, bundle: str)
    def validate() -> List[Error]
    def sync_sources()
    def health_check() -> Report

Admin Dashboard (scripts/admin.py)

Operational tooling:

• --stats — Framework statistics
• --errors — Validation error report
• --sources — Knowledge source status
• --sync — Trigger source sync
• --report — Full health report

🛡️ Layer 6: Runtime Contracts (v3.0)

New in v3.0 — Layer 6 wraps the entire runtime with enforced contracts. No tool executes without a policy decision, no session transitions without state machine validation, and no completion claim without evidence.

Session Lifecycle

The SessionManager enforces an 8-state lifecycle with strict transition rules. Invalid transitions raise InvalidTransitionError.

created → active → waiting_tool → active
                 → waiting_permission → active
                 → idle → active
                 → error → recovering → active
                 → archived (terminal)

Every event is logged with a correlation ID that links sessions to pipeline traces.

Central Policy Engine

The PolicyEngine gates every tool invocation through 4 checks:

1. Schema Validation
   Tool arguments checked against registered schemas.
2. Permission Rules
   Evaluated in order; first match wins.
3. Trust Tier Precedence
   builtin > verified > community > untrusted
4. Decision Artifact
   Machine-readable PolicyDecision with rationale.

Default action is deny — tools must have an explicit allow rule. Denied decisions are queryable and replayable from the audit log.

Telemetry & Replay

The TelemetryCollector normalizes all events to versioned envelopes:

TelemetryEnvelope:
  envelope_id: tel-xxxxxxxxxxxx
  schema_version: 3.0.0
  event_type: policy_decision | session_start | ...
  correlation_id: corr-xxxxxxxxxxxx
  source: {component, session_id, pipeline_name, step_name}
  payload: {...}
  retention_class: standard | audit

The ReplayHarness captures session snapshots and compares checksums for determinism — timestamps are excluded so structure-only comparison works across environments.

MCP Trust Routing

The MCPConnectorManager routes to MCP servers by capability and trust tier:

• Connectors register with trust tier and capabilities
• Routing selects the highest-trust healthy connector for a capability
• Unhealthy connectors are excluded automatically
• Routing is deterministic (same inputs → same output)

v3 Contract Schemas

Six new schemas define the wire format for all v3 contracts:

Release Gates

The ReleaseGateValidator validates 6 hard gates before any release:

1. SchemaAndContracts
   All v3 schemas present and version 3.x
2. PolicyAndSecurity
   Policy engine and permission schema present
3. ReplayDeterminism
   Telemetry module and replay tests present
4. ContextIntegrity
   Handoff schema enforces pinned_constraints and evidence_links
5. PromptQuality
   Prompt files present, schema validator functional
6. MigrationReadiness
   Migration dry-run passes with zero blockers

All 6 must pass and the weighted score must reach 90+ for a GO recommendation.

✅ Validation Chain

How OMNISKILL ensures quality at every level:

manifest.yaml  →  schema validation  →  SKILL.md section check
     ↓                                        ↓
trigger check  →  uniqueness across repo  →  resource existence
     ↓                                        ↓
composition  →  circular dependency check  →  PASS / FAIL