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:

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:

{
  "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)

"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)

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)

# 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)

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

# 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:

{
  "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:

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:

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

# 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:

# 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:

# 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:

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

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 ✓