@namch/agent-assistant 1.0.3 → 1.1.0

package/documents/SMART-SKILL-ORCHESTRATION-BLUEPRINT.md

@@ -0,0 +1,1341 @@
+# Smart Skill Orchestration Mechanism — Technical Blueprint
+
+> **Version**: 1.1  
+> **Author**: Senior AI System Architect  
+> **Date**: 2026-01-30  
+> **Status**: Production-Ready Design
+
+---
+
+## Executive Summary
+
+This blueprint addresses the **Scalability Paradox** in AI agent skill management: the tension between maintaining a stable, low-latency static skill library (`matrix-skills/`) and the need for dynamic, on-demand skill discovery via the **find-skills** skill. 
+
+The solution is a **Hybrid Skill Orchestration Layer** (HSOL) that:
+1. Preserves the reliability of matrix-skills as the primary execution tier
+2. Introduces intelligent decision logic for dynamic skill acquisition via find-skills
+3. Enables autonomous skill evolution without manual maintenance burden
+4. Ensures consistency through versioned skill registries and conflict resolution
+
+**Key Integration:** The `find-skills` skill (`{SKILLS_PATH}/find-skills/SKILL.md`) provides the dynamic discovery interface via `npx skills find` and `npx skills add` commands. Browse at https://skills.sh/
+
+---
+
+## Table of Contents
+
+1. [Problem Analysis](#1-problem-analysis)
+2. [First-Principles Architecture](#2-first-principles-architecture)
+3. [Hybrid Synergy Model](#3-hybrid-synergy-model)
+4. [Intelligent Decision Logic](#4-intelligent-decision-logic)
+5. [Autonomous Evolution Framework](#5-autonomous-evolution-framework)
+6. [Consistency & Versioning Strategy](#6-consistency--versioning-strategy)
+7. [Production-Grade Edge Cases](#7-production-grade-edge-cases)
+8. [Implementation Roadmap](#8-implementation-roadmap)
+9. [System Integration](#9-system-integration)
+
+---
+
+## Prerequisites
+
+Before HSOL can function, the **find-skills** skill must exist at `{SKILLS_PATH}/find-skills/SKILL.md`, where **{SKILLS_PATH}** is the skills path for the **tool the user is currently using** (e.g. Cursor: `~/.cursor/skills/`, Copilot: `~/.copilot/skills/`, Antigravity: `~/.gemini/antigravity/skills/`). All verify and install actions apply **only to the current tool**; do not verify or install for all tools unless the user explicitly runs `install --all`.
+
+**Installation (current tool only, skip confirmation when using npx):**
+
+```bash
+# Option 1: Automatic when user installs agent-assistant for a tool
+# User runs: npm run install:cursor (or install:copilot, install:antigravity)
+# The CLI copies skills/ (including find-skills) to that tool's path only.
+
+# Option 2: Manual copy to CURRENT TOOL's path only
+# For Cursor:
+cp -r skills/find-skills ~/.cursor/skills/
+# For Copilot:
+cp -r skills/find-skills ~/.copilot/skills/
+# For Antigravity:
+cp -r skills/find-skills ~/.gemini/antigravity/skills/
+# Do not copy to all tools unless the user explicitly wants that.
+
+# Option 3: Install from Vercel ecosystem (-g -y = global, skip confirmation)
+# Installs to current environment's global path only.
+npx skills add vercel-labs/skills@find-skills -g -y
+```
+
+**Verification (current tool only):**
+```bash
+# Check at the current tool's SKILLS_PATH (resolve from context)
+ls "{SKILLS_PATH}/find-skills/SKILL.md"
+# Examples: ~/.cursor/skills/find-skills/SKILL.md (Cursor)
+#           ~/.copilot/skills/find-skills/SKILL.md (Copilot)
+```
+
+---
+
+## 1. Problem Analysis
+
+### 1.1 Current State Assessment
+
+**Static Layer (`matrix-skills/`):**
+```
+Strengths:
+├── Low latency (< 1ms skill resolution)
+├── Predictable behavior (deterministic mapping)
+├── Offline-capable (no network dependency)
+├── Type-safe (YAML schema validation)
+└── Agent-profile inheritance model
+
+Weaknesses:
+├── Manual update cycle (labor-intensive)
+├── Skill obsolescence risk (stale skills)
+├── Discovery gap (unknown capabilities)
+├── Scaling limit (~310 skills practical ceiling)
+└── No feedback loop for skill quality
+```
+
+**Dynamic Layer (`find-skills` skill):**
+```
+Location: {SKILLS_PATH}/find-skills/SKILL.md
+Browse: https://skills.sh/
+
+Commands:
+├── npx skills find [query]     → Search for skills
+├── npx skills add <pkg> -g -y  → Install globally  
+├── npx skills check            → Check for updates
+└── npx skills update           → Update all skills
+
+Strengths:
+├── Infinite skill pool (community ecosystem)
+├── Real-time discovery (always current)
+├── Domain experts contribute directly
+├── Reduces "Capability Gap" perception
+└── Supports skill versioning/updates
+
+Weaknesses:
+├── Network latency (100-500ms per search)
+├── Availability risk (network dependency)
+├── Quality uncertainty (untested skills)
+├── Integration friction (install + configure)
+└── Security surface (untrusted code)
+
+When to Trigger:
+├── User asks "how do I do X" (might exist as skill)
+├── User says "find a skill for X"
+├── Matrix fitness < 0.75 (capability gap)
+└── Enhancement mode enabled
+```
+
+### 1.2 Core Tensions Identified
+
+| Tension | Static Priority | Dynamic Priority | Resolution Principle |
+|---------|-----------------|------------------|---------------------|
+| **Speed vs Coverage** | Sub-second | Comprehensive | Tiered fallback |
+| **Reliability vs Freshness** | Battle-tested | Cutting-edge | Trust scoring |
+| **Simplicity vs Flexibility** | Fixed profiles | Any request | Context-aware routing |
+| **Security vs Openness** | Vetted skills | Community skills | Sandboxed evaluation |
+
+### 1.3 The Scalability Paradox — Root Cause
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    THE PARADOX CYCLE                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│   [More Skills Needed] ─────────────────────────────────────┐   │
+│          │                                                   │   │
+│          ▼                                                   │   │
+│   [Manual Addition to Matrix]                                │   │
+│          │                                                   │   │
+│          ▼                                                   │   │
+│   [Increased Maintenance Debt] ──────────────────┐          │   │
+│          │                                        │          │   │
+│          ▼                                        ▼          │   │
+│   [Skills Become Stale] ◄──────────── [Update Fatigue]      │   │
+│          │                                                   │   │
+│          ▼                                                   │   │
+│   [Capability Gaps Appear] ──────────────────────────────────┘  │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+
+ROOT CAUSE: No automated feedback loop between:
+  1. Skill usage patterns
+  2. Skill quality metrics
+  3. Skill currency status
+  4. Dynamic discovery results
+```
+
+---
+
+## 2. First-Principles Architecture
+
+### 2.1 Design Axioms
+
+**Axiom 1: Skill Resolution is a Search Problem**
+> Every user request maps to a capability need. Skills are candidates. The system must rank and select the best match.
+
+**Axiom 2: Latency Budget is Finite**
+> User tolerance: < 2 seconds for initial response. Skill resolution must complete within 200ms for perceived instant response.
+
+**Axiom 3: Trust is Earned, Not Assumed**
+> Matrix skills have earned trust through curation. Dynamic skills must prove themselves through evaluation.
+
+**Axiom 4: The System Must Self-Correct**
+> Manual maintenance doesn't scale. The system must learn from usage patterns and self-optimize.
+
+### 2.2 Architectural Layers
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          USER REQUEST                                        │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  LAYER 1: SEMANTIC INTENT CLASSIFIER                                         │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━                                        │
+│  • Extract capability requirements from natural language                     │
+│  • Map to skill domains and categories                                       │
+│  • Generate skill search vector                                              │
+│  • Estimate complexity and specificity                                       │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                    ┌───────────────┼───────────────┐
+                    ▼               │               ▼
+┌──────────────────────────┐       │       ┌──────────────────────────┐
+│  LAYER 2A: MATRIX LOOKUP │       │       │  LAYER 2B: DYNAMIC       │
+│  ━━━━━━━━━━━━━━━━━━━━━━  │       │       │  DISCOVERY (ASYNC)       │
+│  • Profile-based match   │       │       │  ━━━━━━━━━━━━━━━━━━━━━━  │
+│  • Priority scoring      │       │       │  • find-skills query     │
+│  • O(D×S) resolution     │       │       │  • Community search      │
+│  • Immediate return      │       │       │  • Speculative prefetch  │
+│  • LATENCY: < 10ms       │       │       │  • LATENCY: 100-500ms    │
+└──────────────────────────┘       │       └──────────────────────────┘
+                    │               │               │
+                    ▼               ▼               ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  LAYER 3: SKILL FITNESS EVALUATOR                                            │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━                                           │
+│  • Multi-factor scoring (coverage, freshness, trust, specificity)           │
+│  • Gap detection (matrix can't satisfy request)                             │
+│  • Superiority detection (dynamic skill outperforms matrix)                 │
+│  • Recommendation generation                                                 │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  LAYER 4: ORCHESTRATION DECISION ENGINE                                      │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━                                        │
+│  Decision Matrix:                                                            │
+│  ┌─────────────────┬────────────────┬───────────────────────────────────┐   │
+│  │ Matrix Score    │ Dynamic Score  │ Action                            │   │
+│  ├─────────────────┼────────────────┼───────────────────────────────────┤   │
+│  │ HIGH (≥0.8)     │ Any            │ Execute matrix skill              │   │
+│  │ MEDIUM (0.75-0.8)│ HIGH (≥0.9)    │ Suggest dynamic, execute matrix   │   │
+│  │ MEDIUM          │ MEDIUM         │ Execute matrix skill              │   │
+│  │ LOW (<0.75)     │ HIGH (≥0.8)    │ Prompt for dynamic installation   │   │
+│  │ LOW             │ LOW            │ Report capability gap             │   │
+│  │ NONE            │ HIGH           │ Install and execute dynamic       │   │
+│  │ NONE            │ NONE           │ Fallback to general capabilities  │   │
+│  └─────────────────┴────────────────┴───────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  LAYER 5: SKILL EXECUTION & FEEDBACK                                         │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━                                         │
+│  • Execute selected skill                                                    │
+│  • Capture execution metrics (success, latency, output quality)             │
+│  • Feed metrics to Autonomous Evolution system                               │
+│  • Update skill usage statistics                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. Hybrid Synergy Model
+
+### 3.1 Synergy Principles
+
+**Principle 1: Matrix-First, Dynamic-Enhanced**
+> Matrix skills execute immediately. Dynamic discovery runs in parallel as "enhancement check."
+
+**Principle 2: Blocking vs Async Discovery**
+> **Blocking** (matrix fitness &lt; 0.75): Wait for discovery → install → re-inject → **then** execute. Purpose: new skill is **used for the current task** — best completion for this request. **Async** (fitness 0.75–0.8): Do not wait; execute with matrix; when discovery returns only surface recommendation for **next time**. Async does not improve accuracy for the current task.
+
+**Principle 2b: Conditional Discovery (Variant + Fitness)**
+> Dynamic discovery (find-skills, steps 8–10) runs **only** when: (1) command variant is **`hard`** or **`focus`** — **`fast`** skips discovery so fast stays fast; (2) best matrix fitness **&lt; 0.8** — if matrix already has a highly suitable skill (e.g. 9–10), skip discovery. So: fast flow → steps 1–7 + execute; hard/focus + matrix sufficient → same; hard/focus + matrix &lt; 0.8 → full flow including discovery.
+
+**Principle 3: Graduated Trust**
+> Newly discovered skills start in "evaluation mode" with limited scope. Trust increases with successful executions.
+
+### 3.2 Execution Flow
+
+```
+USER REQUEST: "Implement OAuth with Clerk"
+        │
+        ▼
+┌───────────────────────────────────────────────────────────────┐
+│ SEMANTIC INTENT CLASSIFIER                                     │
+│                                                                │
+│ Extracted:                                                     │
+│   • Domain: authentication                                     │
+│   • Specificity: HIGH (Clerk is specific provider)            │
+│   • Capability: OAuth implementation                          │
+│   • Keywords: ["clerk", "oauth", "authentication"]            │
+└───────────────────────────────────────────────────────────────┘
+        │
+        ├──────────────────────────────────────┐
+        │                                      │
+        ▼ (SYNC, <10ms)                       ▼ (ASYNC)
+┌─────────────────────────┐         ┌─────────────────────────┐
+│ MATRIX LOOKUP           │         │ DYNAMIC DISCOVERY       │
+│                         │         │                         │
+│ Candidates:             │         │ Query: "clerk oauth     │
+│ • better-auth (0.75)    │         │         authentication" │
+│ • api-security (0.60)   │         │                         │
+│ • backend-dev (0.55)    │         │ [Searching...]          │
+│                         │         │                         │
+│ Best Match:             │         │                         │
+│ better-auth @ 0.75      │         │                         │
+└─────────────────────────┘         └─────────────────────────┘
+        │                                      │
+        │                                      │ (200-500ms later)
+        │                                      ▼
+        │                           ┌─────────────────────────┐
+        │                           │ DISCOVERY RESULT        │
+        │                           │                         │
+        │                           │ Found: clerk-auth-skill │
+        │                           │ Score: 0.95             │
+        │                           │ Source: vercel-labs     │
+        │                           └─────────────────────────┘
+        │                                      │
+        ▼                                      ▼
+┌───────────────────────────────────────────────────────────────┐
+│ SKILL FITNESS EVALUATOR                                        │
+│                                                                │
+│ Matrix best: better-auth @ 0.75 (generic OAuth)               │
+│ Dynamic best: clerk-auth @ 0.95 (Clerk-specific)              │
+│                                                                │
+│ DECISION: Matrix skill is ADEQUATE but not OPTIMAL            │
+│           Dynamic skill is SUPERIOR for this specific request │
+└───────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌───────────────────────────────────────────────────────────────┐
+│ ORCHESTRATION DECISION                                         │
+│                                                                │
+│ Option A (IMMEDIATE): Execute better-auth now                 │
+│   → User gets working solution in < 1 second                  │
+│                                                                │
+│ Option B (ENHANCED): Suggest clerk-auth installation          │
+│   → "I found a Clerk-specific skill that may give better      │
+│      results. Install with: npx skills add clerk-auth-skill"  │
+│                                                                │
+│ SELECTED: Execute A, Surface B as recommendation              │
+└───────────────────────────────────────────────────────────────┘
+```
+
+### 3.3 Cognitive Load Management
+
+**Problem**: Agent must not be overwhelmed with skill decisions.
+
+**Solution**: Skill Orchestration Layer (SOL) handles all skill logic transparently.
+
+```yaml
+orchestrator_perspective:
+  before_HSOL:
+    - "Which skill do I need?"
+    - "Is there a better skill available?"
+    - "Should I search for skills?"
+    - "How do I install new skills?"
+  
+  after_HSOL:
+    - "Execute task with injected skills"
+    - "(Recommendations surface automatically)"
+```
+
+The agent sees only:
+1. Injected skills (already resolved)
+2. Optional enhancement recommendations (non-blocking)
+3. Capability gap alerts (when no skill can satisfy request)
+
+---
+
+## 4. Intelligent Decision Logic
+
+### 4.1 Skill Fitness Scoring
+
+**Multi-Factor Fitness Model:**
+
+```
+SKILL_FITNESS = (
+    w₁ × SEMANTIC_MATCH +
+    w₂ × SPECIFICITY_SCORE +
+    w₃ × TRUST_LEVEL +
+    w₄ × FRESHNESS_SCORE +
+    w₅ × SUCCESS_RATE
+) / Σwᵢ
+
+where:
+  w₁ = 0.35 (semantic match is primary)
+  w₂ = 0.25 (specificity matters for specialized requests)
+  w₃ = 0.20 (trust prevents quality issues)
+  w₄ = 0.10 (freshness for evolving domains)
+  w₅ = 0.10 (historical success rate)
+```
+
+**Factor Definitions:**
+
+| Factor | Matrix Skill Calculation | Dynamic Skill Calculation |
+|--------|--------------------------|---------------------------|
+| **SEMANTIC_MATCH** | Keyword overlap + domain alignment | Search relevance score |
+| **SPECIFICITY_SCORE** | Generic (0.5) to Specialized (1.0) | Query specificity alignment |
+| **TRUST_LEVEL** | 1.0 (pre-vetted) | 0.3 (new) → 1.0 (proven) |
+| **FRESHNESS_SCORE** | Last update recency | Always 1.0 (community-current) |
+| **SUCCESS_RATE** | Historical execution success | Community rating / reviews |
+
+### 4.2 Self-Correction Heuristics
+
+**Heuristic 1: Gap Detection**
+```python
+def detect_capability_gap(request, matrix_skills):
+    """
+    Detect when matrix cannot adequately serve a request.
+    """
+    best_match = find_best_matrix_skill(request)
+    
+    # Gap conditions:
+    # 1. No skill found at all
+    if best_match is None:
+        return GapType.COMPLETE_GAP
+    
+    # 2. Best match is too generic
+    if best_match.specificity < 0.4 and request.specificity > 0.7:
+        return GapType.SPECIFICITY_GAP
+    
+    # 3. Best match is stale for evolving domain
+    if best_match.last_updated < (now - 180_days) and request.domain in FAST_EVOLVING_DOMAINS:
+        return GapType.FRESHNESS_GAP
+    
+    # 4. Best match has low success rate
+    if best_match.success_rate < 0.6:
+        return GapType.QUALITY_GAP
+    
+    return GapType.NO_GAP
+```
+
+**Heuristic 2: Superiority Detection**
+```python
+def detect_superior_dynamic_skill(matrix_skill, dynamic_skill, request):
+    """
+    Determine if dynamic skill meaningfully outperforms matrix skill.
+    """
+    SUPERIORITY_THRESHOLD = 0.15  # 15% improvement required
+    
+    matrix_fitness = calculate_fitness(matrix_skill, request)
+    dynamic_fitness = calculate_fitness(dynamic_skill, request)
+    
+    fitness_delta = dynamic_fitness - matrix_fitness
+    
+    # Superior if:
+    # 1. Significantly higher fitness
+    if fitness_delta >= SUPERIORITY_THRESHOLD:
+        return SuperiorityResult(
+            is_superior=True,
+            reason="HIGHER_FITNESS",
+            recommendation="Consider installing for better results"
+        )
+    
+    # 2. Domain-specific when matrix is generic
+    if dynamic_skill.specificity > 0.8 and matrix_skill.specificity < 0.5:
+        return SuperiorityResult(
+            is_superior=True,
+            reason="DOMAIN_SPECIFIC",
+            recommendation="Specialized skill available"
+        )
+    
+    return SuperiorityResult(is_superior=False)
+```
+
+**Heuristic 3: Automatic Promotion**
+```python
+def evaluate_skill_for_promotion(dynamic_skill):
+    """
+    Determine if a dynamic skill should be promoted to matrix-skills.
+    """
+    PROMOTION_CRITERIA = {
+        'min_executions': 10,
+        'min_success_rate': 0.85,
+        'min_satisfaction': 0.8,  # User ratings
+        'max_age_days': 90,       # Must be actively used recently
+    }
+    
+    if (
+        dynamic_skill.execution_count >= PROMOTION_CRITERIA['min_executions'] and
+        dynamic_skill.success_rate >= PROMOTION_CRITERIA['min_success_rate'] and
+        dynamic_skill.user_satisfaction >= PROMOTION_CRITERIA['min_satisfaction'] and
+        dynamic_skill.last_used_days_ago <= PROMOTION_CRITERIA['max_age_days']
+    ):
+        return PromotionRecommendation(
+            skill=dynamic_skill,
+            action="ADD_TO_MATRIX",
+            domain=infer_domain(dynamic_skill),
+            priority_score=calculate_priority(dynamic_skill)
+        )
+    
+    return None
+```
+
+### 4.3 Decision Tree
+
+```
+                        ┌─────────────────┐
+                        │ User Request    │
+                        │ Arrives         │
+                        └────────┬────────┘
+                                 │
+                                 ▼
+                    ┌────────────────────────┐
+                    │ Extract Skill          │
+                    │ Requirements           │
+                    └────────────┬───────────┘
+                                 │
+                                 ▼
+              ┌──────────────────────────────────┐
+              │ Matrix Lookup                     │
+              │ (returns best_match, fitness)    │
+              └──────────────────┬───────────────┘
+                                 │
+               ┌─────────────────┼─────────────────┐
+               │                 │                 │
+               ▼                 ▼                 ▼
+        ┌───────────┐     ┌───────────┐     ┌───────────┐
+        │ FITNESS   │     │ FITNESS   │     │ FITNESS   │
+        │ ≥ 0.8     │     │ 0.75-0.8  │     │ < 0.75    │
+        │ (HIGH)    │     │ (MEDIUM)  │     │ (LOW/NONE)│
+        └─────┬─────┘     └─────┬─────┘     └─────┬─────┘
+              │                 │                 │
+              ▼                 ▼                 ▼
+   ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
+   │ EXECUTE          │  │ EXECUTE +        │  │ TRIGGER DYNAMIC  │
+   │ Matrix Skill     │  │ Async Discovery  │  │ Discovery        │
+   │                  │  │ for Enhancement  │  │ (Blocking)       │
+   └──────────────────┘  └────────┬─────────┘  └────────┬─────────┘
+                                  │                     │
+                                  ▼                     ▼
+                       ┌──────────────────┐  ┌──────────────────┐
+                       │ Discovery Found  │  │ Discovery Result │
+                       │ Superior Skill?  │  │                  │
+                       └────────┬─────────┘  └────────┬─────────┘
+                                │                     │
+                      ┌─────────┴─────────┐          │
+                      ▼                   ▼          │
+               ┌───────────┐       ┌───────────┐    │
+               │ YES       │       │ NO        │    │
+               └─────┬─────┘       └─────┬─────┘    │
+                     │                   │          │
+                     ▼                   ▼          ▼
+          ┌──────────────────┐  ┌───────────┐  ┌──────────────────┐
+          │ SURFACE          │  │ Continue  │  │ PROMPT:          │
+          │ Recommendation   │  │ (no       │  │ "No matrix skill.│
+          │ for Future Use   │  │  change)  │  │  Install X?"     │
+          └──────────────────┘  └───────────┘  └──────────────────┘
+```
+
+---
+
+## 5. Autonomous Evolution Framework
+
+### 5.1 Feedback Loop Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        AUTONOMOUS EVOLUTION LOOP                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│ EXECUTION    │ ──▶ │ TELEMETRY    │ ──▶ │ ANALYSIS     │ ──▶ │ ACTION       │
+│ LAYER        │     │ COLLECTOR    │     │ ENGINE       │     │ EXECUTOR     │
+└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
+       ▲                                                              │
+       │                                                              │
+       └──────────────────────────────────────────────────────────────┘
+                              CONTINUOUS IMPROVEMENT
+
+EXECUTION LAYER captures:
+  • Skill used
+  • Execution time
+  • Success/failure
+  • User satisfaction (implicit: continued use, explicit: feedback)
+  • Request characteristics
+
+TELEMETRY COLLECTOR aggregates:
+  • Per-skill metrics
+  • Domain usage patterns
+  • Gap occurrence frequency
+  • Dynamic skill adoption rates
+
+ANALYSIS ENGINE computes:
+  • Skill health scores
+  • Promotion candidates
+  • Deprecation candidates
+  • Domain coverage gaps
+  • Trend detection
+
+ACTION EXECUTOR triggers:
+  • Matrix skill additions (auto-generated PR)
+  • Matrix skill deprecations (flag for review)
+  • Priority score adjustments
+  • Domain file reorganization
+  • Alert on quality degradation
+```
+
+### 5.2 Skill Lifecycle States
+
+```
+                    ┌─────────────────┐
+                    │   DISCOVERED    │
+                    │   (Dynamic)     │
+                    └────────┬────────┘
+                             │
+                    First successful execution
+                             │
+                             ▼
+                    ┌─────────────────┐
+                    │   EVALUATING    │
+                    │   (Probation)   │
+                    └────────┬────────┘
+                             │
+               ┌─────────────┼─────────────┐
+               │             │             │
+        Success > 85%   Abandoned    Failure > 30%
+               │             │             │
+               ▼             ▼             ▼
+      ┌─────────────┐ ┌───────────┐ ┌─────────────┐
+      │  VALIDATED  │ │  DORMANT  │ │  REJECTED   │
+      │  (Trusted)  │ │           │ │             │
+      └──────┬──────┘ └───────────┘ └─────────────┘
+             │
+    High usage + team approval
+             │
+             ▼
+      ┌─────────────┐
+      │  PROMOTED   │
+      │  (Matrix)   │
+      └──────┬──────┘
+             │
+    ┌────────┴────────┐
+    │                 │
+    ▼                 ▼
+┌──────────┐   ┌──────────────┐
+│  ACTIVE  │   │  DEPRECATED  │
+│  (Core)  │   │  (Phase out) │
+└──────────┘   └──────────────┘
+```
+
+### 5.3 Global Installation Protocol
+
+**Challenge**: When a dynamic skill is installed, it must be immediately available across the global environment.
+
+**Solution**: Tiered Installation Model
+
+```yaml
+installation_tiers:
+  
+  tier_1_session_local:
+    scope: "Current session only"
+    persistence: "None (ephemeral)"
+    use_case: "Testing, one-off requests"
+    command: "npx skills add <skill>"
+    effect: |
+      Skill loaded into current agent context.
+      No file system changes.
+      Lost on session end.
+
+  tier_2_user_global:
+    scope: "All sessions for current user"
+    persistence: "User config directory"
+    use_case: "Personal productivity skills"
+    command: "npx skills add <skill> -g"
+    effect: |
+      Skill installed to ~/.{TOOL}/skills/{skill-id}/
+      Automatically loaded in future sessions.
+      User-specific, not shared with team.
+
+  tier_3_project_local:
+    scope: "All users working on project"
+    persistence: "Project repository"
+    use_case: "Project-specific skills"
+    command: "npx skills add <skill> --project"
+    effect: |
+      Skill reference added to project config.
+      Skill fetched on project clone/setup.
+      Version-locked for consistency.
+
+  tier_4_matrix_promoted:
+    scope: "All agents, all projects"
+    persistence: "Matrix skill system"
+    use_case: "Battle-tested, widely useful skills"
+    process: |
+      1. When promotion criteria met (executions, success_rate, recency), skill is auto-promoted
+      2. System adds skill entry to matrix-skills/{domain}.yaml (no promotion queue, no human review)
+      3. Write target: the GLOBAL tool path the main agent already reads from
+         (e.g. ~/.cursor/skills/agent-assistant/matrix-skills/ for Cursor)
+      4. Same files the orchestrator loaded at session start — we update those on disk
+      5. Next resolution cycle (or cache invalidation / hot-reload) picks up the new skill
+         — no tool restart required; available to all agents on next request
+```
+
+### 5.4 Environment Synchronization
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ GLOBAL ENVIRONMENT SYNC                                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  USER INSTALLS NEW SKILL                                        │
+│         │                                                        │
+│         ▼                                                        │
+│  ┌──────────────────────────────────────────┐                   │
+│  │ 1. DOWNLOAD & VALIDATE                    │                   │
+│  │    • Fetch SKILL.md from source           │                   │
+│  │    • Validate schema compliance           │                   │
+│  │    • Check for conflicts with existing    │                   │
+│  └──────────────────┬───────────────────────┘                   │
+│                     │                                            │
+│                     ▼                                            │
+│  ┌──────────────────────────────────────────┐                   │
+│  │ 2. INSTALL TO PATH                        │                   │
+│  │    • ~/.{TOOL}/skills/{skill-id}/SKILL.md │                   │
+│  │    • Update skill manifest                │                   │
+│  └──────────────────┬───────────────────────┘                   │
+│                     │                                            │
+│                     ▼                                            │
+│  ┌──────────────────────────────────────────┐                   │
+│  │ 3. INVALIDATE CACHES                      │                   │
+│  │    • Clear skill resolution cache         │                   │
+│  │    • Signal active sessions to reload     │                   │
+│  └──────────────────┬───────────────────────┘                   │
+│                     │                                            │
+│                     ▼                                            │
+│  ┌──────────────────────────────────────────┐                   │
+│  │ 4. REGISTER IN DYNAMIC SKILL INDEX       │                   │
+│  │    • Add to ~/.{TOOL}/skills/_dynamic.yaml│                   │
+│  │    • Include metadata for resolution      │                   │
+│  └──────────────────┬───────────────────────┘                   │
+│                     │                                            │
+│                     ▼                                            │
+│  ┌──────────────────────────────────────────┐                   │
+│  │ 5. AVAILABLE FOR NEXT RESOLUTION CALL    │                   │
+│  │    • No session restart required          │                   │
+│  │    • Immediate use on next request        │                   │
+│  └──────────────────────────────────────────┘                   │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 6. Consistency & Versioning Strategy
+
+### 6.1 Conflict Detection
+
+**Conflict Types:**
+
+| Conflict Type | Description | Resolution Strategy |
+|--------------|-------------|---------------------|
+| **ID Collision** | Dynamic skill has same ID as matrix skill | Prefix dynamic with `ext-` |
+| **Domain Overlap** | Dynamic skill claims same domain coverage | Matrix takes precedence unless dynamic is superior |
+| **Capability Duplication** | Both skills do the same thing | Fitness scoring determines winner |
+| **Version Incompatibility** | Skill requires newer agent version | Block installation, notify user |
+
+### 6.2 Versioning Model
+
+```yaml
+# Matrix Skill Version Format
+skill_version:
+  format: "MAJOR.MINOR.PATCH"
+  example: "1.2.3"
+  
+  semantics:
+    MAJOR: "Breaking changes to skill interface"
+    MINOR: "New capabilities, backward compatible"
+    PATCH: "Bug fixes, no capability change"
+
+# Dynamic Skill Source Tracking
+dynamic_skill_reference:
+  format: "{source}/{owner}/{repo}@{skill}#{version}"
+  example: "github/vercel-labs/skills@clerk-auth#v1.2.0"
+  
+  components:
+    source: "github | npm | custom"
+    owner: "Repository owner"
+    repo: "Repository name"
+    skill: "Skill ID within repo"
+    version: "Pinned version or 'latest'"
+
+# Lock File for Project Consistency
+# File: ./skills.lock.yaml
+locked_skills:
+  matrix_version: "1.0"
+  dynamic_skills:
+    - id: "clerk-auth"
+      source: "github/vercel-labs/skills@clerk-auth"
+      version: "v1.2.0"
+      installed_at: "2026-01-30T12:00:00Z"
+      checksum: "sha256:abc123..."
+```
+
+### 6.3 Conflict Resolution Protocol
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ CONFLICT RESOLUTION PROTOCOL                                     │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  STEP 1: DETECT CONFLICT TYPE                                   │
+│     ─────────────────────────                                    │
+│     • ID collision check                                         │
+│     • Domain overlap analysis                                    │
+│     • Capability fingerprint comparison                         │
+│                                                                  │
+│  STEP 2: APPLY RESOLUTION RULES                                 │
+│     ─────────────────────────────                                │
+│     Rule 1: Matrix skills ALWAYS take their IDs                 │
+│     Rule 2: Dynamic skills get prefixed if collision            │
+│     Rule 3: Higher fitness wins for capability overlap          │
+│     Rule 4: User explicit preference overrides all              │
+│                                                                  │
+│  STEP 3: DOCUMENT RESOLUTION                                    │
+│     ─────────────────────────                                    │
+│     • Log conflict occurrence                                    │
+│     • Record resolution decision                                 │
+│     • Notify user if dynamic skill was renamed/shadowed         │
+│                                                                  │
+│  STEP 4: VALIDATE CONSISTENCY                                   │
+│     ───────────────────────────                                  │
+│     • Ensure no duplicate IDs in unified index                  │
+│     • Verify all agent profiles can still resolve               │
+│     • Check for orphaned skill references                       │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 6.4 Unified Skill Index
+
+**Runtime Data Structure:**
+
+```yaml
+# Unified Skill Index (in-memory structure)
+unified_skill_index:
+  version: "1.0"
+  generated_at: "2026-01-30T12:00:00Z"
+  
+  # Matrix skills (pre-loaded)
+  matrix_skills:
+    - skill_id: "better-auth"
+      source: "matrix"
+      domain: "backend"
+      priority: 8
+      trust_level: 1.0
+      path: "~/.{TOOL}/skills/agent-assistant/matrix-skills/backend.yaml"
+  
+  # Dynamic skills (user-installed)
+  dynamic_skills:
+    - skill_id: "clerk-auth"
+      source: "github/vercel-labs/skills"
+      domain: "backend"
+      priority: 7  # Starts lower than matrix
+      trust_level: 0.6  # Earned through usage
+      path: "~/.{TOOL}/skills/clerk-auth/SKILL.md"
+      version: "v1.2.0"
+  
+  # Resolution priority (matrix > dynamic by default)
+  resolution_order:
+    - source: "matrix"
+      weight: 1.0
+    - source: "dynamic"
+      weight: 0.9  # Slight preference for matrix
+```
+
+---
+
+## 7. Production-Grade Edge Cases
+
+### 7.1 Network Failure Handling
+
+```yaml
+network_failure_scenarios:
+
+  scenario_1_discovery_timeout:
+    trigger: "find-skills search exceeds 5 second timeout"
+    impact: "Cannot retrieve dynamic skill candidates"
+    resolution:
+      immediate: "Proceed with matrix skills only"
+      notification: "Notify user that discovery was unavailable"
+      retry: "Queue background retry for later"
+    
+  scenario_2_installation_failure:
+    trigger: "Dynamic skill download fails mid-transfer"
+    impact: "Skill partially installed, corrupted state"
+    resolution:
+      immediate: "Rollback partial installation"
+      cleanup: "Remove incomplete skill directory"
+      notification: "Notify user of failure with retry option"
+    
+  scenario_3_intermittent_connectivity:
+    trigger: "Network flaps during skill execution"
+    impact: "Skill that requires network may fail"
+    resolution:
+      detection: "Pre-flight check for network-dependent skills"
+      fallback: "Use local-only skill alternative if available"
+      caching: "Cache skill assets for offline resilience"
+```
+
+### 7.2 Installation Failure Recovery
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ INSTALLATION FAILURE RECOVERY                                    │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  FAILURE TYPES:                                                  │
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │ TYPE: DOWNLOAD_FAILURE                                   │    │
+│  │ Cause: Network error, invalid URL, auth required         │    │
+│  │ State: No files written                                  │    │
+│  │ Recovery: Retry with exponential backoff, then abort    │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │ TYPE: VALIDATION_FAILURE                                 │    │
+│  │ Cause: Invalid SKILL.md schema, missing required fields │    │
+│  │ State: File downloaded but not registered               │    │
+│  │ Recovery: Delete file, report error to user             │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │ TYPE: CONFLICT_FAILURE                                   │    │
+│  │ Cause: ID collision that cannot be auto-resolved        │    │
+│  │ State: Validation passed, conflict detected             │    │
+│  │ Recovery: Prompt user to choose resolution strategy     │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │ TYPE: REGISTRATION_FAILURE                               │    │
+│  │ Cause: Index write failed (disk full, permissions)      │    │
+│  │ State: Skill files exist but not indexed                │    │
+│  │ Recovery: Cleanup files, report system error            │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                  │
+│  RECOVERY PROTOCOL:                                              │
+│                                                                  │
+│  1. Detect failure type                                          │
+│  2. Execute type-specific rollback                               │
+│  3. Log failure for telemetry                                    │
+│  4. Notify user with actionable guidance                        │
+│  5. Offer retry option if transient failure                     │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 7.3 Environment Path Updates
+
+**Challenge**: Newly installed skills must be discoverable without session restart.
+
+**Solution**: Hot-Reload Mechanism
+
+```yaml
+hot_reload_mechanism:
+
+  trigger_events:
+    - skill_installed
+    - skill_updated
+    - skill_removed
+    - config_changed
+  
+  reload_sequence:
+    1. FILE_WATCH:
+       path: "~/.{TOOL}/skills/"
+       events: [create, modify, delete]
+       debounce: 500ms  # Prevent rapid-fire reloads
+    
+    2. INDEX_REBUILD:
+       action: "Rebuild unified skill index"
+       scope: "Changed domain only (incremental)"
+       duration: "< 50ms for single skill change"
+    
+    3. CACHE_INVALIDATE:
+       action: "Clear resolution cache for affected domains"
+       scope: "Targeted, not full cache flush"
+    
+    4. SESSION_NOTIFY:
+       action: "Signal active sessions"
+       method: "File-based IPC via lock file mtime"
+       response: "Sessions poll for changes on next resolution"
+    
+    5. VERIFICATION:
+       action: "Confirm skill accessible"
+       test: "Attempt resolution with new skill ID"
+```
+
+### 7.4 Security Considerations
+
+```yaml
+security_model:
+
+  threat_1_malicious_skill:
+    vector: "Dynamic skill contains harmful instructions"
+    mitigation:
+      - "Skills are Markdown/YAML only (no executable code)"
+      - "Skill content is guidance, not direct execution"
+      - "Agent interprets skill, doesn't run it blindly"
+      - "Community reporting for malicious skills"
+    
+  threat_2_skill_impersonation:
+    vector: "Attacker creates skill with trusted name"
+    mitigation:
+      - "Source verification (GitHub org, npm scope)"
+      - "Checksum validation on download"
+      - "Warning on unofficial sources"
+    
+  threat_3_data_exfiltration:
+    vector: "Skill instructs agent to send data externally"
+    mitigation:
+      - "Network operations require explicit user approval"
+      - "Sandboxed skill evaluation mode for new skills"
+      - "Audit logging of skill-triggered actions"
+    
+  trust_progression:
+    new_skill: 
+      trust_level: 0.3
+      restrictions:
+        - "Cannot suggest network operations"
+        - "Limited to read-only file access patterns"
+        - "User confirmation required for actions"
+    
+    validated_skill:
+      trust_level: 0.7
+      unlock_after: "5 successful executions"
+      restrictions:
+        - "Standard agent capabilities"
+        - "Still logged for audit"
+    
+    promoted_skill:
+      trust_level: 1.0
+      unlock_after: "Matrix inclusion (auto-promote when criteria met)"
+      restrictions:
+        - "None (same as native agent skills)"
+```
+
+---
+
+## 8. Implementation Roadmap
+
+### 8.1 Phase Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                     IMPLEMENTATION PHASES                                    │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  PHASE 1: Foundation                                                         │
+│  ════════════════════                                                        │
+│  • Unified Skill Index data structure                                        │
+│  • Dynamic skill manifest (dynamic_skills.yaml)                              │
+│  • Hot-reload file watcher                                                   │
+│  • Basic conflict detection                                                  │
+│                                                                              │
+│  PHASE 2: Discovery Integration                                              │
+│  ══════════════════════════════                                              │
+│  • find-skills CLI wrapper                                                   │
+│  • Async discovery during matrix resolution                                  │
+│  • Fitness scoring engine                                                    │
+│  • Recommendation surfacing UI                                               │
+│                                                                              │
+│  PHASE 3: Intelligent Decisions                                              │
+│  ══════════════════════════════                                              │
+│  • Gap detection heuristics                                                  │
+│  • Superiority detection                                                     │
+│  • Decision tree implementation                                              │
+│  • User preference persistence                                               │
+│                                                                              │
+│  PHASE 4: Autonomous Evolution                                               │
+│  ═════════════════════════════                                               │
+│  • Telemetry collection                                                      │
+│  • Usage analytics engine                                                    │
+│  • Automatic promotion recommendations                                       │
+│  • Matrix update PR generation                                               │
+│                                                                              │
+│  PHASE 5: Production Hardening                                               │
+│  ═════════════════════════════                                               │
+│  • Network failure resilience                                                │
+│  • Security audit and hardening                                              │
+│  • Performance optimization                                                  │
+│  • Comprehensive testing                                                     │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 8.2 Deliverables Per Phase
+
+| Phase | Key Deliverables |
+|-------|------------------|
+| **Phase 1** | `_dynamic.yaml`, `unified_skill_resolver.ts`, file watcher, conflict detector |
+| **Phase 2** | `discovery_client.ts`, `fitness_scorer.ts`, recommendation UI component |
+| **Phase 3** | `decision_engine.ts`, gap/superiority detectors, preference store |
+| **Phase 4** | `telemetry_collector.ts`, `analytics_engine.ts`, PR generator |
+| **Phase 5** | Resilience tests, security hardening, performance benchmarks |
+
+### 8.3 Success Criteria
+
+```yaml
+success_metrics:
+
+  scalability:
+    metric: "Skills manageable without proportional maintenance increase"
+    target: "Support 500+ skills with same maintenance effort as 100"
+    measurement: "Maintenance hours per skill per month"
+    
+  reliability:
+    metric: "Skill resolution success rate"
+    target: "> 99.9% resolution success"
+    measurement: "Failed resolutions / total resolutions"
+    
+  autonomy:
+    metric: "Skills auto-promoted vs manually added"
+    target: "> 50% of new matrix skills from auto-promotion"
+    measurement: "Auto-promoted skills / total new skills (monthly)"
+    
+  latency:
+    metric: "Skill resolution time"
+    target: "< 50ms for matrix, < 500ms for dynamic discovery"
+    measurement: "P95 resolution latency"
+    
+  user_satisfaction:
+    metric: "Skill relevance ratings"
+    target: "> 4.2/5.0 average rating"
+    measurement: "Post-execution skill relevance survey"
+```
+
+---
+
+## 9. System Integration
+
+### 9.1 Integration with Existing Components
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                   SMART SKILL ORCHESTRATION INTEGRATION                      │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  ORCHESTRATOR                                                                │
+│  ════════════                                                                │
+│  Integration Point: Skill Resolution call                                    │
+│  Change: Call HSOL instead of direct matrix lookup                          │
+│                                                                              │
+│    BEFORE: resolve_skills(agent_profile) → matrix_skills[]                  │
+│    AFTER:  resolve_skills(agent_profile, request) → unified_skills[]        │
+│                                                                              │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│                                                                              │
+│  AGENT FILES                                                                 │
+│  ═══════════                                                                 │
+│  Integration Point: Skills section                                           │
+│  Change: Add dynamic skill awareness                                         │
+│                                                                              │
+│    ## ⚡ Skills                                                              │
+│    > **MATRIX DISCOVERY**: Auto-injected from matrix-skills/                │
+│    > **DYNAMIC ENHANCEMENT**: Additional skills may be suggested            │
+│    > Profile: `{profile}` | Domains: `{domains}`                            │
+│                                                                              │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│                                                                              │
+│  SKILL-DISCOVERY.md                                                          │
+│  ══════════════════                                                          │
+│  Integration Point: Resolution Algorithm                                     │
+│  Change: Add Step 7 (Dynamic Enhancement Check)                             │
+│                                                                              │
+│    Step 6: Return Skill Set (existing)                                      │
+│    Step 7: Async Dynamic Discovery (NEW)                                    │
+│            → Query find-skills with request keywords                        │
+│            → Compare fitness scores                                          │
+│            → Surface recommendations if superior                            │
+│                                                                              │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│                                                                              │
+│  _index.yaml                                                                 │
+│  ═══════════                                                                 │
+│  Integration Point: Skill registry                                           │
+│  Change: Add dynamic skill registry section                                  │
+│                                                                              │
+│    dynamic_registry:                                                         │
+│      enabled: true                                                           │
+│      manifest_path: "_dynamic.yaml"                                         │
+│      discovery_endpoint: "npx skills find"                                  │
+│      cache_ttl: 3600  # seconds                                             │
+│                                                                              │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│                                                                              │
+│  EXECUTION-PROTOCOL.md                                                       │
+│  ═════════════════════                                                       │
+│  Integration Point: Phase execution                                          │
+│  Change: Add skill enhancement checkpoint                                    │
+│                                                                              │
+│    STEP 2.5: SKILL ENHANCEMENT CHECK                                        │
+│    If HSOL recommends superior skill:                                       │
+│      → Surface recommendation to user                                       │
+│      → "A specialized skill for {domain} is available..."                   │
+│      → Continue with current skills unless user installs                    │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 9.2 New Files Required
+
+```
+agent-assistant/
+├── matrix-skills/
+│   ├── _index.yaml          # ← Add dynamic_registry section
+│   ├── _dynamic.yaml        # ← NEW: Dynamic skill manifest
+│   └── {domain}.yaml        # Existing domain files
+│
+├── rules/
+│   ├── SKILL-DISCOVERY.md   # ← Update with HSOL integration
+│   ├── SKILL-ORCHESTRATION.md # ← NEW: HSOL decision logic
+│   └── ...
+│
+├── lib/                     # ← NEW: Shared libraries
+│   ├── skill-resolver/
+│   │   ├── unified-index.ts
+│   │   ├── fitness-scorer.ts
+│   │   ├── discovery-client.ts
+│   │   └── conflict-resolver.ts
+│   │
+│   ├── telemetry/
+│   │   ├── collector.ts
+│   │   └── analytics.ts
+│   │
+│   └── evolution/
+│       ├── promotion-engine.ts
+│       └── pr-generator.ts
+│
+└── documents/
+    └── SMART-SKILL-ORCHESTRATION-BLUEPRINT.md  # This document
+```
+
+### 9.3 Migration Path
+
+```yaml
+migration_strategy:
+
+  stage_1_parallel_operation:
+    description: "Run HSOL alongside existing system"
+    approach:
+      - "HSOL runs in shadow mode"
+      - "Logs recommendations but doesn't affect execution"
+      - "Compare HSOL decisions with actual usage"
+    
+  stage_2_soft_launch:
+    description: "Enable HSOL recommendations"
+    approach:
+      - "HSOL recommendations shown to users"
+      - "Users can opt-in to install recommended skills"
+      - "Track adoption rate and feedback"
+    
+  stage_3_default_enabled:
+    description: "HSOL becomes primary resolver"
+    approach:
+      - "All skill resolution goes through HSOL"
+      - "Matrix-first with dynamic enhancement"
+      - "Automatic promotion pipeline active"
+    
+  rollback_plan:
+    trigger: "Critical failure or regression"
+    action: "Disable HSOL, revert to direct matrix resolution"
+    data_preservation: "All telemetry and dynamic skills preserved"
+```
+
+---
+
+## Appendix A: Glossary
+
+| Term | Definition |
+|------|------------|
+| **HSOL** | Hybrid Skill Orchestration Layer — the core system designed in this blueprint |
+| **Matrix Skills** | Pre-curated skills in `matrix-skills/*.yaml` |
+| **Dynamic Skills** | Skills discovered/installed via `find-skills` CLI |
+| **Skill Fitness** | Computed score representing how well a skill matches a request |
+| **Gap Detection** | Identifying when matrix skills cannot satisfy a request |
+| **Skill Promotion** | Process of elevating a validated dynamic skill to matrix-skills |
+
+---
+
+## Appendix B: Decision Matrix Quick Reference
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│              SKILL SELECTION QUICK REFERENCE                     │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  MATRIX FITNESS │ DYNAMIC FITNESS │ ACTION                      │
+│  ───────────────┼─────────────────┼──────────────────────────   │
+│       ≥ 0.8     │      Any        │ Execute matrix              │
+│       0.75-0.8  │      ≥ 0.9      │ Execute matrix + suggest    │
+│       0.75-0.8  │      < 0.9      │ Execute matrix              │
+│       < 0.75    │      ≥ 0.8      │ Prompt to install dynamic   │
+│       < 0.75    │      < 0.8      │ Report capability gap       │
+│       None      │      ≥ 0.7      │ Install and execute dynamic │
+│       None      │      None       │ Use general capabilities    │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Appendix C: File Templates
+
+### C.1 _dynamic.yaml Template
+
+```yaml
+# Dynamic Skill Manifest
+# Auto-managed by HSOL — updated when agents run npx skills add ... -g -y
+
+version: "1.1"
+last_updated: "2026-01-30T12:00:00Z"
+
+skills: []
+  # Entries added automatically on skill installation
+  # Format:
+  # - skill_id: "clerk-auth"
+  #   source: "github/vercel-labs/skills@clerk-auth"
+  #   version: "v1.2.0"
+  #   installed_at: "2026-01-30T12:00:00Z"
+  #   checksum: "sha256:abc123..."
+  #   trust_level: 0.3
+  #   execution_count: 0
+  #   success_rate: null
+  #   domains: ["backend", "security"]
+```
+
+### C.2 Skill Telemetry Schema
+
+```yaml
+# Skill Execution Telemetry Entry
+telemetry_entry:
+  timestamp: "2026-01-30T12:00:00Z"
+  skill_id: "better-auth"
+  source: "matrix"  # or "dynamic"
+  agent_id: "backend-engineer"
+  request_hash: "sha256:xyz..."  # Anonymized request fingerprint
+  execution_time_ms: 150
+  success: true
+  user_satisfaction: null  # Populated if feedback provided
+  gap_detected: false
+  dynamic_alternative_suggested: null
+```
+
+---
+
+**Document End**
+
+*This blueprint provides the architectural foundation for implementing the Smart Skill Orchestration Mechanism. All recommendations are based on first-principles analysis and production-grade considerations.*