Skill Registry

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: preexecution, postexecution, onerror, onqualitygatefail, 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: onqualitygate_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 | Type | Check | Auto-Fix | Retry Max | |------|------|-------|----------|-----------| | U1 | Universal | ≥3 sources, ≥1 academic | Fetch from KB | 2 | | U2 | Universal | Disclosure before recommendation | Prepend disclosure | 2 | | U3 | Universal | Evidence hierarchy labeled | Annotate tiers | 2 | | U4 | Universal | Language matches preference | Translate output | 2 | | U5 | Universal | Template sections present | Reformat to template | 2 | | U6 | Universal | Claims traced to sources | Flag unsupported | 2 | | G1 | Domain | Phishing-resistant MFA recommended | Add MFA rec | 2 | | G2 | Domain | Credential hygiene + monitoring | Add hygiene | 2 | | G3 | Domain | Recovery hardened | Harden recovery | 2 | | G4 | Domain | Behavioral training present | Add training | 2 |

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

| Event | Description | Context | |-------|-------------|---------| | preexecution | Before skill execution begins | skillname, inputdata, timestamp | | postexecution | After skill execution completes | skillname, outputdata, timestamp | | onerror | When execution raises exception | skillname, error, timestamp | | onqualitygatefail | When quality gate fails | gatename, outputdata, retrycount | | ondegradation | When data availability degrades | degradationlevel, reason | | ontokenlimit | When token budget is exceeded | currenttokens, maxtokens |

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 scenar

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dungnotnull
• Source: dungnotnull/game-account-phishing-protection-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.