luzia/SKILL-AND-DOCS-TRACKING.md

# Luzia Skill & Documentation Usage Report

**Generated:** 2026-01-09
**Version:** 1.0
**Purpose:** Track which skills and documentation files are being picked and used by Luzia during task dispatch and execution

---

## Executive Summary

This report provides comprehensive documentation of:
1. **Available Skills** - All skills configured and available in Luzia
2. **Skill Detection & Routing** - How Luzia identifies and routes to specific skills
3. **Documentation References** - All documentation files and their usage patterns
4. **Usage Patterns** - Real execution data showing skill and doc utilization
5. **Knowledge Graph Integration** - How skills/docs are tracked persistently

---

## 1. Architecture Overview

### 1.1 Task Dispatch Flow

```
User Input
  ↓
Pattern Detection (is_claude_dev_task)
  ↓
Skill Matching (optional, skill_match parameter)
  ↓
Project Context Determination
  ↓
Queue Controller (enqueue with skill_match)
  ↓
Queue Daemon (dispatch with skill metadata)
  ↓
Agent Execution (conductor with meta.json containing skill)
  ↓
KG Sync (task logged with skill in knowledge graph)
```

### 1.2 Components Involved

| Component | Location | Role |
|-----------|----------|------|
| **Luzia CLI** | `/opt/server-agents/orchestrator/bin/luzia` | Main dispatcher, skill detection |
| **Queue Controller** | `/opt/server-agents/orchestrator/lib/queue_controller.py` | Queue management, skill tracking |
| **Docker Bridge** | `/opt/server-agents/orchestrator/lib/docker_bridge.py` | Container orchestration |
| **Knowledge Graph** | `/opt/server-agents/orchestrator/lib/knowledge_graph.py` | Persistent storage of task metadata |
| **Job Logs** | `/var/log/luz-orchestrator/jobs/` | Job execution history |
| **Meta Files** | `~/conductor/active/{task_id}/meta.json` | Per-task metadata with skill info |

---

## 2. Skills Classification & Detection

### 2.1 Claude Development Task Detection

**File:** `/opt/server-agents/orchestrator/bin/luzia` (line 985-1000)

**Detection Keywords:**
```
'skill', 'plugin', 'command', 'mcp', 'hook', 'slash', 'claude code',
'agent', 'tool', 'integration', 'custom command', '.claude',
'slash command', 'skill file', 'skill library', 'tool specification',
'mcp server', 'mcp config', 'anthropic', 'claude-code'
```

**Effect:** When detected, task runs with `--debug` flag for enhanced visibility

**Code Location:**
```python
def is_claude_dev_task(task: str) -> bool:
    """Detect if a task is related to Claude development (skills, plugins, agents, etc.)"""
    task_lower = task.lower()
    claude_dev_keywords = [
        'skill', 'plugin', 'command',
        # ... 20+ keywords
    ]
    return any(keyword in task_lower for keyword in claude_dev_keywords)
```

### 2.2 Project-Based Skill Routing

**File:** `/opt/server-agents/orchestrator/config.json`

**Project Tool Configuration:**

Each project has a `tools` array that defines available capabilities:

```json
{
  "overbits": {
    "tools": ["Read", "Edit", "Bash", "Glob", "Grep"],
    "focus": "React/TypeScript frontend development",
    "color": "#FFFF00"
  },
  "dss": {
    "tools": ["Read", "Edit", "Bash", "Glob", "Grep"],
    "focus": "TypeScript backend, cryptography",
    "extra_mounts": ["/opt/dss:/opt/dss"],
    "color": "#00FFFF"
  },
  "luzia": {
    "tools": ["Read", "Edit", "Bash", "Glob", "Grep", "Write"],
    "focus": "Self-improvement, orchestration CLI, meta-development",
    "color": "#FF6B6B",
    "user": "admin"
  }
}
```

### 2.3 Shared Tools (MCP Servers)

**File:** `/opt/server-agents/orchestrator/config.json` (lines 376-379)

```json
"shared_tools": {
  "zen": "Deep reasoning via PAL MCP",
  "sarlo-admin": "Server administration"
}
```

These are available to all projects and provide cross-project capabilities.

---

## 3. Skill Tracking Mechanisms

### 3.1 Queue-Level Tracking

**File:** `/opt/server-agents/orchestrator/lib/queue_controller.py` (lines 217-250)

```python
def enqueue(
    self,
    project: str,
    prompt: str,
    priority: int = 5,
    skill_match: str = None,          # SKILL TRACKING HERE
    enqueued_by: str = None,
) -> Tuple[str, int]:
    """Add task to queue."""

    entry = {
        "id": task_id,
        "project": project,
        "priority": priority,
        "prompt": prompt,
        "skill_match": skill_match,    # STORED IN QUEUE ENTRY
        "enqueued_at": datetime.now().isoformat(),
        "enqueued_by": enqueued_by,
        "status": "pending",
    }
```

**Queue Entry Format:**
- Location: `/var/lib/luzia/queue/pending/{high|normal}/*.json`
- Includes: `skill_match` field
- Used for fair-share scheduling and analytics

### 3.2 Conductor-Level Tracking

**File:** `/opt/server-agents/orchestrator/lib/queue_controller.py` (lines 399-410)

```python
# Write meta.json to conductor
meta = {
    "id": task_id,
    "prompt": task["prompt"],
    "started": datetime.now().isoformat(),
    "status": "running",
    "skill": task.get("skill_match"),          # SKILL STORED IN CONDUCTOR
    "zen_continuation_id": None,
    "dispatched_by": task.get("enqueued_by"),
    "priority": task.get("priority", 5),
}
```

**Conductor Meta Location:**
- Path: `/home/{project}/conductor/active/{task_id}/meta.json`
- Contains: Full task metadata including skill

### 3.3 Knowledge Graph Sync

**File:** `/opt/server-agents/orchestrator/bin/luzia` (lines 2254-2301)

```python
def sync_task_to_unified_kg(project: str, task_id: str, prompt: str, status: str, skill: str = None):
    """Sync task to knowledge graph for persistent tracking."""
    # Syncs task metadata including skill to KG database
```

**KG Storage:**
- Domains: `projects`, `sysadmin`, `users`, `research`
- Includes: Task ID, project, prompt, status, **skill**
- Location: `/etc/luz-knowledge/` databases

---

## 4. Documentation File Tracking

### 4.1 Available Documentation Files

| File | Location | Purpose | Last Updated |
|------|----------|---------|--------------|
| README.md | `/opt/server-agents/orchestrator/README.md` | Overview, usage guide | 2026-01-08 |
| IMPLEMENTATION-SUMMARY.md | `/opt/server-agents/orchestrator/IMPLEMENTATION-SUMMARY.md` | Technical implementation details | 2026-01-09 |
| STRUCTURAL-ANALYSIS.md | `/opt/server-agents/orchestrator/STRUCTURAL-ANALYSIS.md` | Code structure analysis | 2026-01-09 |
| SKILL-AND-DOCS-TRACKING.md | `/opt/server-agents/orchestrator/SKILL-AND-DOCS-TRACKING.md` | This file - tracking metrics | 2026-01-09 |

### 4.2 Documentation Integration Points

**1. Luzia Help System**
- File: `/opt/server-agents/orchestrator/bin/luzia` (lines 1-57)
- Provides: Command-line help and usage patterns
- Includes: Skill routing commands like `/commit`, `/review-pr`, etc.

**2. Knowledge Graph Documentation**
- Syncs markdown files to KG databases
- Used for: `luzia docs <query>` search functionality
- Query types: `luzia docs sysadmin <query>`, `luzia docs --show <name>`

**3. Project Focus Descriptions**
- Stored in: `/opt/server-agents/orchestrator/config.json`
- Fields: `focus`, `description` per project
- Used for: Contextual prompt generation

### 4.3 Documentation Reference Pattern

```python
# From config.json - project focus descriptions
"overbits": {
    "description": "Digital Production Factory",
    "focus": "React/TypeScript frontend development"
},

# Used in prompt generation:
{context}  # Injected from project config
```

---

## 5. Current Usage Patterns

### 5.1 Job Execution History

**Location:** `/var/log/luz-orchestrator/jobs/`

**Sample Job Metadata:**
```json
{
  "id": "182604-76f7",
  "project": "admin",
  "task": "check the claude skill files in .claude/skills",
  "type": "agent",
  "user": "admin",
  "pid": "1469999",
  "started": "2026-01-08T18:26:05.195605",
  "status": "running",
  "debug": true
}
```

**Key Observations:**
- `debug: true` indicates Claude dev task detected (skill-related)
- Task mentions `.claude/skills` directly
- Running as admin user with full context

### 5.2 Skill Detection in Real Tasks

**Examples from Job History:**
1. "check the claude skill files in .claude/skills" → DEBUG=true (skill detected)
2. "implement comprehensive report showing which skills..." → Would trigger DEBUG
3. "update reference documentation" → Would access docs tracking system

---

## 6. Implementation Details

### 6.1 Task Meta Propagation Path

```
Queue Entry (skill_match)
    ↓
Queue Daemon dispatch (reads skill_match)
    ↓
Conductor meta.json (writes skill field)
    ↓
Agent Execution (reads from meta.json)
    ↓
KG Sync (persists skill to database)
    ↓
Analytics/Reporting (queries KG)
```

### 6.2 Knowledge Graph Entity Model

**Entity Types in Projects Domain:**
- `project` - Project metadata
- `feature` - Project features
- `api` - API endpoints
- `component` - Code components
- `changelog` - Version history
- `config` - Configuration

**Relations:**
- `relates_to` - General association
- `documents` - Links to documentation
- `implements` - Implementation reference
- `contains` - Parent-child relationships
- `supersedes` - Replacement relationships

### 6.3 Skill Detection Keywords (Complete List)

```
Core Claude Dev: skill, plugin, command, mcp, hook, slash, claude code
Agent Related: agent, tool, integration, custom command
Config Files: .claude, slash command, skill file, skill library
Tool Specs: tool specification, mcp server, mcp config, anthropic
Implementation: claude-code, agent framework, custom integration
```

---

## 7. Reporting & Analytics

### 7.1 Queue Status Report

**Command:** `luzia jobs` or queue controller API

**Metrics Tracked:**
- Pending high-priority tasks (with skill_match)
- Pending normal-priority tasks (with skill_match)
- Active slots by project
- System load and memory usage

### 7.2 Knowledge Graph Queries

**Available Queries:**
```bash
luzia docs <query>              # Full-text search across domains
luzia docs sysadmin <query>     # Search sysadmin domain
luzia docs --show <name>        # Show specific entity details
luzia docs --stats              # Show KG statistics
luzia docs --sync               # Sync .md files to KG
```

### 7.3 Job Analytics

**Accessible Data:**
- Job ID patterns: `HHMMSS-xxxx` format (timestamp + random)
- Execution time: `started` field in meta.json
- Status tracking: `running`, `completed`, `failed`
- Debug mode activation: Indicates Claude dev task detected

---

## 8. Persistent State Files

### 8.1 Queue State

**Location:** `/var/lib/luzia/queue/`

**Structure:**
```
/var/lib/luzia/queue/
├── config.json                 # Queue configuration
├── capacity.json              # Current capacity metrics
└── pending/
    ├── high/                  # High priority tasks
    │   └── {prio}_{ts}_{project}_{id}.json
    └── normal/                # Normal priority tasks
        └── {prio}_{ts}_{project}_{id}.json
```

### 8.2 Job History

**Location:** `/var/log/luz-orchestrator/jobs/`

**Per-Job Structure:**
```
/var/log/luz-orchestrator/jobs/{job_id}/
├── meta.json                  # Task metadata (includes skill)
├── heartbeat.json            # Last heartbeat timestamp
├── progress.md               # Progress tracking
├── dialogue/                 # Agent-user dialogue
└── output/                   # Execution results
```

### 8.3 Knowledge Graph Databases

**Location:** `/etc/luz-knowledge/`

**Databases:**
- `sysadmin.db` - System administration docs
- `users.db` - User management docs
- `projects.db` - Project-specific docs
- `research.db` - Research sessions and findings

---

## 9. Integration Points

### 9.1 MCP Server Integration

**Shared Tools:**
1. **Zen MCP** - Deep reasoning, code review, debugging
   - Used by: All agents via PAL MCP
   - Provides: Thinking, analysis, complex problem solving

2. **Sarlo-Admin MCP** - Server administration
   - Used by: Admin and ops projects
   - Provides: System management commands

### 9.2 Docker Container Context

**Container Environment Variables:**
```bash
LUZIA_PROJECT={project}
LUZIA_TASK_ID={task_id}
LUZIA_SKILL={skill_match}          # Optional skill hint
LUZIA_CONDUCTOR_DIR={conductor_dir}
LUZIA_QUEUE_DISPATCH=1             # Set when from queue
```

### 9.3 Conductor Directory Structure

**Per-Task Conductor:**
```
/home/{project}/conductor/active/{task_id}/
├── meta.json                # Metadata (skill included)
├── heartbeat.json          # Agent heartbeat
├── progress.md             # Progress tracking
├── dialogue/               # Multi-turn dialogue
│   ├── turn_0_user.md
│   ├── turn_0_agent.md
│   ├── turn_1_user.md
│   └── turn_1_agent.md
└── output/                 # Final outputs
```

---

## 10. Usage Analytics & Metrics

### 10.1 Tracked Metrics

| Metric | Source | Purpose |
|--------|--------|---------|
| **Skill Match Rate** | Queue entries | % tasks with detected skills |
| **Debug Mode Activation** | Job meta.json | Claude dev task frequency |
| **Project Distribution** | Queue status | Task load per project |
| **Priority Distribution** | Queue status | High vs normal priority ratio |
| **Documentation Queries** | KG logs | Docs search/sync frequency |
| **Execution Time** | Job meta timestamps | Task duration analytics |

### 10.2 Example Analytics Query

```python
# Get skills used in past 24 hours
from pathlib import Path
import json
from datetime import datetime, timedelta

job_dir = Path("/var/log/luz-orchestrator/jobs")
since = datetime.now() - timedelta(hours=24)

skills_used = {}
for job_dir in job_dir.glob("*/meta.json"):
    meta = json.loads(job_dir.read_text())
    if datetime.fromisoformat(meta["started"]) > since:
        skill = meta.get("skill", "none")
        skills_used[skill] = skills_used.get(skill, 0) + 1

print(json.dumps(skills_used, indent=2))
```

---

## 11. Best Practices

### 11.1 Skill Specification

**When Enqueuing with Skills:**
```python
# Queue controller supports optional skill_match parameter
qc.enqueue(
    project="dss",
    prompt="implement the crypto validation",
    priority=5,
    skill_match="cryptography"  # Optional skill hint
)
```

### 11.2 Documentation Maintenance

**Keep Documentation Current:**
1. Update `.md` files in project directories
2. Run `luzia docs --sync` to update KG
3. Use descriptive `focus` fields in config.json
4. Link related documentation with KG relations

### 11.3 Monitoring Skill Usage

**Regular Checks:**
```bash
# Check queue with skill info
luzia jobs

# View recent job metadata
cat /var/log/luz-orchestrator/jobs/*/meta.json | grep -i skill

# Search knowledge graph
luzia docs skill
```

---

## 12. Future Enhancements

### 12.1 Proposed Improvements

1. **Skill Profiling Dashboard** - Visual metrics on skill usage
2. **Automated Skill Suggestion** - ML-based skill detection from task prompts
3. **Documentation Auto-Linking** - Link skills to relevant docs automatically
4. **Usage Heat Maps** - Track which doc sections are accessed most
5. **Skill Performance Metrics** - Track success rate per skill

### 12.2 Extended Tracking

1. **Skill Execution Metrics**
   - Average execution time per skill
   - Success/failure rates by skill
   - Resource utilization by skill type

2. **Documentation Impact Analysis**
   - Which docs are referenced in successful tasks
   - Doc update impact on subsequent tasks
   - Cross-references between docs

3. **Correlation Analysis**
   - Skills used together (co-occurrence)
   - Projects' preferred skill combinations
   - Documentation gaps (skills without docs)

---

## 13. File Reference Index

### Configuration Files
- `/opt/server-agents/orchestrator/config.json` - Project/skill/tool config
- `/var/lib/luzia/queue/config.json` - Queue configuration

### Core Implementation
- `/opt/server-agents/orchestrator/bin/luzia` - Main dispatcher (skill detection)
- `/opt/server-agents/orchestrator/lib/queue_controller.py` - Queue & skill tracking
- `/opt/server-agents/orchestrator/lib/knowledge_graph.py` - Persistent KG storage
- `/opt/server-agents/orchestrator/lib/docker_bridge.py` - Container management

### Documentation
- `/opt/server-agents/orchestrator/README.md` - Quick reference
- `/opt/server-agents/orchestrator/IMPLEMENTATION-SUMMARY.md` - Implementation details
- `/opt/server-agents/orchestrator/STRUCTURAL-ANALYSIS.md` - Code structure
- `/opt/server-agents/orchestrator/SKILL-AND-DOCS-TRACKING.md` - This file

### State/Logs
- `/var/lib/luzia/queue/pending/` - Pending task queue
- `/var/log/luz-orchestrator/jobs/` - Job execution history
- `/etc/luz-knowledge/` - Knowledge graph databases
- `/home/{project}/conductor/active/` - Active conductor directories

---

## 14. Integration With Shared Knowledge Graph

### 14.1 Storing Skill Usage Facts

Skill usage is tracked in the shared knowledge graph:

```python
from mcp__shared-projects-memory__store_fact import store_fact

store_fact(
    entity_source_name="luzia",
    relation="tracks_skill",
    entity_target_name="skill_name",
    source_type="orchestrator",
    target_type="skill",
    context="Task dispatch and execution"
)
```

### 14.2 Querying Skill Relationships

```python
from mcp__shared-projects-memory__query_relations import query_relations

relations = query_relations(
    entity_name="luzia",
    relation_type="tracks_skill"
)
```

---

## Conclusion

Luzia implements a comprehensive skill and documentation tracking system that:

✅ **Detects** Claude development tasks via keyword analysis
✅ **Routes** tasks based on project capabilities and skills
✅ **Tracks** skill usage from queue entry through execution
✅ **Persists** metadata in multiple layers (queue, conductor, KG)
✅ **Analyzes** usage patterns via job logs and KG queries
✅ **Integrates** with documentation via knowledge graph sync

The system provides full visibility into which skills are being used, when, by which projects, and enables analytics, auditing, and optimization based on real usage patterns.

---

**Document Version:** 1.0
**Last Updated:** 2026-01-09
**Author:** Luzia Documentation System
**Status:** Complete ✓