SKILL Registry Documentation

Overview

The skill registry provides dynamic skill loading, execution tracking, and dependency management for the game-account-phishing-protection harness. Skills are registered with full schema validation, executed through hooks, and monitored with production-grade metrics.

Implementation note (v3.0.0): The registry, router, quality gates and orchestrator described below are implemented as real, runnable, tested code in the core/ package (SkillRegistry, ChainOfThoughtRouter, QualityGateEngine, SecurityAnalyzer, HarnessOrchestrator). The tools/ handlers perform real HTTP I/O with graceful degradation to the knowledge base. See scripts/validate_project.py and tests/test_core.py.

Skill Registration

Registration Schema

Each skill is registered with the following schema:

{
  "name": "skill-name",
  "version": "1.0.0",
  "description": "One-line description of when this skill triggers",
  "author": "game-account-phishing-protection",
  "tags": ["domain", "keywords"],
  "input_schema": {
    "type": "object",
    "properties": { ... },
    "required": ["field1", "field2"]
  },
  "output_schema": {
    "type": "object",
    "properties": { ... },
    "required": ["result_field"]
  },
  "dependencies": ["other-skill-name"],
  "tools": ["WebSearch", "KnowledgeQuery"],
  "hooks": ["pre_execution", "post_execution"],
  "file_path": "path/to/skill.md",
  "enabled": true,
  "metadata": {
    "execution_count": 0,
    "avg_time_ms": 0,
    "success_rate": 1.0
  }
}

Registered Skills

1. main.md

• Name: game-account-phishing-protection
• Description: Main harness orchestrator for Game Account Security & Anti-Phishing analysis
• Input: User query about account security
• Output: Comprehensive security report with verdict
• Tools: WebSearch, WebFetch, KnowledgeQuery, Skill (sub-skill invocation)
• Hooks: pre_execution, post_execution, on_error, on_quality_gate_fail, on_degradation
• Dependencies: All sub-skills (executed in sequence)

2. sub-gather-requirements.md

• Name: sub-gather-requirements
• Description: Clarify analysis scope, constraints, timeframe, inputs, audience, language
• Input: Raw user message
• Output: Structured requirements object
• Tools: Conversation only (no external tools)
• Hooks: pre_execution (validation)
• Quality Gate: At least one object of analysis confirmed

3. sub-evidence-collector.md

• Name: sub-evidence-collector
• Description: Fetch authoritative real-time and reference data for the analysis object
• Input: Requirements from Step 1
• Output: Evidence bundle with sources and dates
• Tools: WebSearch, WebFetch, Read (knowledge base)
• Hooks: on_error (fallback to knowledge base)
• Quality Gate: Current data + 1 authoritative doc retrieved

4. sub-core-analysis.md

• Name: sub-core-analysis
• Description: Advise gamers on protecting accounts via MFA, credential hygiene, recovery hardening, behavioral training
• Input: Accounts, current security, value, breach history, language
• Output: Security assessment with MFA, hygiene, recovery, training, scenarios
• Tools: Read (knowledge base), WebFetch (NIST, APWG), Reasoning
• Hooks: on_degradation (if inputs incomplete)
• Quality Gate: Phishing-resistant MFA recommended + hygiene + recovery + training present

5. sub-knowledge-updater.md

• Name: sub-knowledge-updater
• Description: Query SECOND-KNOWLEDGE-BRAIN.md for academic evidence with tier labels
• Input: Topic keywords from analysis
• Output: 3-5 knowledge-base citations with tiers + flagged gaps
• Tools: Read (knowledge base), WebSearch (gap-fill, max 2 queries)
• Hooks: on_error (queue for crawl pipeline)
• Quality Gate: At least 1 academic/authoritative source surfaced

6. sub-advisor.md

• Name: sub-advisor
• Description: Synthesize all prior analysis into risk-disclosed conclusion with evidence chain
• Input: Core analysis scorecard + evidence bundle + knowledge evidence
• Output: Verdict + scenarios + risks + evidence chain + remediation + disclosure
• Tools: Reasoning / synthesis, Skill (sub-knowledge-updater optional)
• Hooks: on_quality_gate_fail (auto-fix verdict)
• Quality Gate: Verdict is one of: Strong Security / Conditional (MFA upgrade) / High Compromise Risk / Inconclusive

Skill Resolution

Resolution Process

1. Direct Name Lookup: Search for skill by exact name match
2. Alias Resolution: Check registered aliases for skill
3. Category Search: Search by tags/metadata if name not found
4. Fallback: Return null if no match found

Resolution API

class SkillRegistry:
    def resolve(self, name: str) -> Optional[SkillRegistration]:
        """Resolve skill by name with alias support."""
        # 1. Direct lookup
        if name in self.skills:
            return self.skills[name]

        # 2. Alias lookup
        for skill in self.skills.values():
            if name in skill.metadata.get('aliases', []):
                return skill

        # 3. Tag/category search
        matches = [s for s in self.skills.values()
                   if name.lower() in ' '.join(s.tags).lower()]
        if matches:
            return matches[0]  # Return first match

        return None

Skill Execution

Execution Flow

User invokes skill
    ↓
Registry resolves skill
    ↓
Hooks: pre_execution
    ↓
Validate input schema
    ↓
Resolve dependencies (topological sort)
    ↓
Execute dependencies in order
    ↓
Execute skill implementation
    ↓
Tools called (with schema validation)
    ↓
Intermediate results collected
    ↓
Hooks: post_execution
    ↓
Validate output schema
    ↓
Quality gates checked
    ↓
Metrics recorded
    ↓
Return result

Execution with Error Handling

class SkillRegistry:
    def execute(self, name: str, input_data: Dict[str, Any]) -> SkillExecutionResult:
        """Execute skill with full error handling and monitoring."""
        try:
            # Resolve skill
            skill = self.resolve(name)
            if skill is None:
                return SkillExecutionResult(
                    skill_name=name,
                    success=False,
                    output=None,
                    execution_time_ms=0,
                    token_usage=0,
                    errors=["Skill not found"]
                )

            # Pre-execution hooks
            self._emit_hooks('pre_execution', skill=skill, input=input_data)

            # Validate input
            self._validate_input(skill, input_data)

            # Execute dependencies
            for dep in skill.dependencies:
                dep_result = self.execute(dep, input_data)
                if not dep_result.success:
                    return SkillExecutionResult(
                        skill_name=name,
                        success=False,
                        output=None,
                        execution_time_ms=0,
                        token_usage=0,
                        errors=[f"Dependency {dep} failed"]
                    )

            # Execute skill
            start_time = time.time()
            output = self._execute_implementation(skill, input_data)
            execution_time = int((time.time() - start_time) * 1000)

            # Post-execution hooks
            self._emit_hooks('post_execution', skill=skill, output=output)

            # Validate output
            self._validate_output(skill, output)

            # Record metrics
            self._record_metrics(skill, execution_time, success=True)

            return SkillExecutionResult(
                skill_name=name,
                success=True,
                output=output,
                execution_time_ms=execution_time,
                token_usage=output.get('token_usage', 0),
                quality_gates=output.get('quality_gate_results', [])
            )

        except Exception as e:
            # Error hooks
            self._emit_hooks('on_error', skill=skill, error=e)

            # Record metrics
            self._record_metrics(skill, 0, success=False)

            return SkillExecutionResult(
                skill_name=name,
                success=False,
                output=None,
                execution_time_ms=0,
                token_usage=0,
                errors=[str(e)]
            )

Dependency Management

Dependency Graph

Skills can declare dependencies on other skills. The registry builds a dependency graph and executes skills in topological order.

# Example dependency graph
main.md → [sub-gather-requirements, sub-evidence-collector, sub-core-analysis, sub-knowledge-updater, sub-advisor]

sub-advisor → [sub-knowledge-updater]  # Optional dependency
sub-core-analysis → [sub-gather-requirements]

Topological Sort Algorithm

def _topological_sort(skills: Dict[str, SkillRegistration]) -> List[str]:
    """Sort skills by dependency order."""
    visited = set()
    temp_visited = set()
    result = []

    def visit(skill_name: str):
        if skill_name in temp_visited:
            raise ValueError(f"Circular dependency detected: {skill_name}")
        if skill_name in visited:
            return

        temp_visited.add(skill_name)

        skill = skills.get(skill_name)
        if skill:
            for dep in skill.dependencies:
                visit(dep)

        temp_visited.remove(skill_name)
        visited.add(skill_name)
        result.append(skill_name)

    for skill_name in skills:
        visit(skill_name)

    return result

Quality Gates

Gate Definitions

Gate Execution

def _execute_quality_gates(skill: SkillRegistration, output: Dict[str, Any]) -> List[QualityGateResult]:
    """Execute all quality gates with auto-fix."""
    results = []

    for gate in skill.quality_gates:
        for attempt in range(gate.max_retries + 1):
            result = _check_gate(gate, output)

            if result.passed:
                results.append(result)
                break
            elif attempt < gate.max_retries:
                # Attempt auto-fix
                fix_result = _apply_auto_fix(gate, output)
                if fix_result.success:
                    result.auto_fix_attempted = True
                    result.auto_fix_successful = True
                    results.append(result)
                    break
                else:
                    result.retry_count = attempt + 1
            else:
                # Final failure
                results.append(result)

    return results

Input/Output Schemas

Input Schema Example: sub-gather-requirements

{
  "type": "object",
  "properties": {
    "user_message": {
      "type": "string",
      "description": "Raw user input message"
    },
    "language_hint": {
      "type": "string",
      "enum": ["en", "vi"],
      "description": "Detected language preference"
    },
    "context": {
      "type": "object",
      "description": "Additional context from previous interactions"
    }
  },
  "required": ["user_message"]
}

Output Schema Example: sub-gather-requirements

{
  "type": "object",
  "properties": {
    "object_of_analysis": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Game accounts to analyze"
    },
    "scope": {
      "type": "string",
      "description": "Analysis scope and constraints"
    },
    "timeframe": {
      "type": "string",
      "description": "Analysis timeframe (e.g., 'last 30 days')"
    },
    "available_inputs": {
      "type": "object",
      "description": "Available input data"
    },
    "target_audience": {
      "type": "string",
      "description": "Target audience for output"
    },
    "language": {
      "type": "string",
      "enum": ["en", "vi"],
      "description": "Output language"
    },
    "analysis_type": {
      "type": "string",
      "description": "Type of analysis to perform"
    },
    "validation_passed": {
      "type": "boolean",
      "description": "Whether input validation passed"
    }
  },
  "required": ["object_of_analysis", "language", "validation_passed"]
}

Lifecycle Hooks

Hook Events

Hook Registration

@dataclass
class HookDefinition:
    name: str
    event: HookEvent
    handler: Callable[[HookContext], HookResult]
    priority: int = 0  # Higher = earlier execution
    timeout_ms: int = 10000
    async_execution: bool = False
    enabled: bool = True

Metrics and Monitoring

Execution Metrics

{
    "total_executions": 150,
    "successful_executions": 142,
    "failed_executions": 8,
    "average_execution_time_ms": 2340.5,
    "average_token_usage": 45670.2,
    "total_token_usage": 6850530,
    "last_execution": "2026-07-15T10:45:00Z",
    "quality_gate_pass_rate": 0.95,
    "by_skill": {
        "game-account-phishing-protection": {
            "executions": 50,
            "successes": 48,
            "failures": 2,
            "avg_time_ms": 4500.0
        },
        "sub-gather-requirements": {
            "executions": 50,
            "successes": 50,
            "failures": 0,
            "avg_time_ms": 500.0
        }
    }
}

Tool Metrics

{
    "total_executions": 320,
    "successful_executions": 310,
    "failed_executions": 10,
    "timeout_executions": 2,
    "rate_limited_executions": 0,
    "by_tool": {
        "WebSearch": {
            "executions": 150,
            "successes": 145,
            "failures": 5,
            "avg_time_ms": 2500.0
        },
        "KnowledgeQuery": {
            "executions": 100,
            "successes": 100,
            "failures": 0,
            "avg_time_ms": 200.0
        }
    }
}

Extension Points

Adding a New Skill

1. Create skill file: skills/sub-new-skill.md
2. Define input/output schemas in config/schemas.py
3. Add registration in skill registry
4. Implement quality gates if needed
5. Add hooks for lifecycle events
6. Update documentation

Adding a New Tool

1. Create handler in tools/ directory
2. Define tool schema in tools/__init__.py
3. Register tool in tool manager
4. Add rate limiting if needed
5. Update tool documentation

Adding a New Hook

1. Implement handler in hooks/ directory
2. Register in hooks/__init__.py
3. Define priority and timeout
4. Test with hook-specific scenarios
5. Document in SKILL.md

Configuration

Environment Variables

# LLM Configuration
SKILL_MODEL_NAME="claude-sonnet-4-20250514"
SKILL_TEMPERATURE="0.7"
SKILL_MAX_TOKENS="8192"

# Feature Flags
SKILL_ENABLE_REGISTRY="true"
SKILL_ENABLE_COT="true"
SKILL_ENABLE_PARALLEL="true"
SKILL_ENABLE_CACHING="true"

# Monitoring
SKILL_ENABLE_METRICS="true"
SKILL_LOG_LEVEL="INFO"
SKILL_LOG_OUTPUT="logs/production.log"

Configuration File

from config import SkillConfig, get_config

config = get_config()
# Access configuration
print(config.project_name)  # "game-account-phishing-protection"
print(config.version)  # "2.0.0"
print(config.llm.model_name)  # "claude-sonnet-4-20250514"
print(config.enable_skill_registry)  # True

Troubleshooting

Skill Not Found

Symptom: SkillExecutionResult with error "Skill not found"

Causes:

• Skill not registered in registry
• Typo in skill name
• Skill disabled

Resolution:

• Check skill is registered in config/skill_registry.py
• Verify skill name spelling
• Check enabled: true in registration

Quality Gate Failures

Symptom: Quality gates repeatedly fail with auto-fix not working

Causes:

• Data unavailability
• Schema mismatch
• Missing dependencies

Resolution:

• Check degradation level
• Verify input/output schemas
• Ensure dependencies are executing successfully

Hook Timeouts

Symptom: Hook execution exceeds timeout

Causes:

• Hook handler too slow
• External API delays
• Large data processing

Resolution:

• Increase hook timeout in registration
• Optimize hook handler
• Consider async execution

Version: 3.0.0 Last Updated: 2026-07-28 Maintainer: game-account-phishing-protection development team