Pro Gamer Eye Hand Training Agent Skill

SKILL.md — Skill Registry Documentation

Overview

The pro-gamer-eye-hand-training system uses a centralized skill registry pattern for managing skill lifecycle, discovery, execution, and validation. This document defines how skills are registered, resolved, executed, and validated using JSON schemas for type safety.

---

Architecture Pattern

1. Skill Registry Pattern

Instead of hardcoded skill invocations, the system uses a dynamic registry that:

• Discovers skills by scanning configuration
• Resolves dependencies between skills
• Validates inputs/outputs against JSON schemas
• Executes skills with proper hooks and error handling
• Provides observability through event logging

config/skill_registry.json (central definition)
         ↓
    SkillRegistry (runtime manager)
         ↓
    HookRegistry (lifecycle management)
         ↓
    SkillExecution (with validation + error handling)

---

2. Registry File Structure

Location: config/skill_registry.json

{
  "version": "1.0.0",
  "registry": {
    "core_skills": { ... },
    "tool_registrations": { ... },
    "execution_policies": { ... }
  },
  "hooks": { ... }
}

Core Skills Section

Each skill registration includes:

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | ✓ | Unique skill identifier | | entry_point | path | ✓ | Path to skill markdown file | | type | enum | ✓ | harness, collector, analyzer, knowledge, synthesizer | | priority | integer | ✓ | Execution order (higher first) | | dependencies | array | ✓ | List of skill IDs this skill depends on | | provides | array | ✓ | Capabilities this skill provides | | triggers | array | ✗ | Phrases that trigger this skill (main harness only) | | input_schema | JSON Schema | ✓ | Schema for input validation | | output_schema | JSON Schema | ✓ | Schema for output validation |

Tool Registrations Section

Each tool registration includes:

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | ✓ | Tool identifier | | description | string | ✓ | What the tool does | | schema | object | ✓ | Input and output schemas | | rate_limit | object | ✓ | Rate limiting configuration | | fallback | string/null | ✓ | Fallback tool identifier or null |

---

3. Skill Resolution Process

Step 1: Discovery

def discover_skills(registry_path: str) -> Dict[str, Skill]:
    """Load and parse skill registry"""
    with open(registry_path) as f:
        config = json.load(f)
    return config["registry"]["core_skills"]

Step 2: Dependency Resolution

def resolve_dependencies(
    skill_id: str,
    skills: Dict[str, Skill],
    resolved: Set[str] = None
) -> List[str]:
    """Topologically sort skills by dependency"""
    if resolved is None:
        resolved = set()

    skill = skills[skill_id]
    for dep in skill["dependencies"]:
        if dep not in resolved:
            resolve_dependencies(dep, skills, resolved)

    resolved.add(skill_id)
    return list(resolved)

Step 3: Execution Order

Based on priority field (higher priority executes first):

Main Harness (priority 0)
    ↓
Sub-Gather-Requirements (priority 1)
    ↓
Sub-Evidence-Collector (priority 2)
    ↓
Sub-Core-Analysis (priority 3)
    ↓
Sub-Knowledge-Updater (priority 4)
    ↓
Sub-Advisor (priority 5)

---

4. Skill Execution with Validation

Input Validation

Before skill execution, validate inputs against input_schema:

def validate_input(skill_id: str, data: Dict) -> bool:
    """Validate input against skill's JSON schema"""
    skill = registry["core_skills"][skill_id]
    schema = skill["input_schema"]

    # Use jsonschema for validation
    from jsonschema import validate, ValidationError

    try:
        validate(instance=data, schema=schema)
        return True
    except ValidationError as e:
        logger.error(f"Input validation failed for {skill_id}: {e.message}")
        return False

Output Validation

After skill execution, validate outputs against output_schema:

def validate_output(skill_id: str, data: Dict) -> bool:
    """Validate output against skill's JSON schema"""
    skill = registry["core_skills"][skill_id]
    schema = skill["output_schema"]

    try:
        validate(instance=data, schema=schema)
        return True
    except ValidationError as e:
        logger.error(f"Output validation failed for {skill_id}: {e.message}")
        return False

---

5. Skill Type Definitions

Harness (Type: harness)

Main orchestrator skill. Coordinates other skills and implements quality gates.

Example: pro-gamer-eye-hand-training

{
  "type": "harness",
  "priority": 0,
  "dependencies": [],
  "provides": ["analysis", "training_design", "performance_science"],
  "triggers": ["eye-hand training", "gamer training", "reaction training"]
}

Collector (Type: collector)

Gathers inputs and requirements from the user.

Example: sub-gather-requirements

{
  "type": "collector",
  "priority": 1,
  "dependencies": [],
  "provides": ["requirements", "scope", "constraints"],
  "input_schema": {
    "type": "object",
    "properties": {
      "user_message": {"type": "string"},
      "language": {"type": "string", "enum": ["en", "vi", "auto"]}
    },
    "required": ["user_message"]
  }
}

Analyzer (Type: analyzer)

Performs core domain analysis using specialized methods.

Example: sub-core-analysis

{
  "type": "analyzer",
  "priority": 3,
  "dependencies": ["sub_evidence_collector"],
  "provides": ["analysis", "scorecard", "training_design"]
}

Knowledge (Type: knowledge)

Queries knowledge base and provides academic evidence.

Example: sub-knowledge-updater

{
  "type": "knowledge",
  "priority": 4,
  "dependencies": ["sub_core_analysis"],
  "provides": ["academic_evidence", "citations", "knowledge_gaps"]
}

Synthesizer (Type: synthesizer)

Combines all analysis into final recommendation with risk disclosure.

Example: sub-advisor

{
  "type": "synthesizer",
  "priority": 5,
  "dependencies": ["sub_core_analysis", "sub_knowledge_updater"],
  "provides": ["conclusion", "recommendation", "risk_disclosure"]
}

---

6. Execution Policies

Defined in config/skill_registry.json under execution_policies:

{
  "execution_policies": {
    "max_retries": 3,
    "timeout_seconds": 120,
    "degradation_levels": 5,
    "quality_gates": ["U1", "U2", "U3", "U4", "U5", "U6", "G1", "G2", "G3", "G4"],
    "parallel_execution": false,
    "cancellation_on_failure": true
  }
}

Policy Definitions

| Policy | Value | Meaning | |--------|-------|---------| | max_retries | 3 | Maximum retry attempts for failed skills | | timeout_seconds | 120 | Maximum time per skill execution | | degradation_levels | 5 | Graceful degradation levels (0-4) | | quality_gates | array | List of quality gates to validate | | parallel_execution | false | Skills execute sequentially (not in parallel) | | cancellation_on_failure | true | Stop pipeline on critical failures |

---

7. Hooks Configuration

Hooks are defined in the hooks section of skill_registry.json:

{
  "hooks": {
    "pre_execution": [
      "language_detection",
      "requirement_validation",
      "token_budget_check"
    ],
    "post_execution": [
      "quality_gate_validation",
      "evidence_verification",
      "output_formatting"
    ],
    "on_error": [
      "error_classification",
      "fallback_activation",
      "limitation_flagging",
      "error_logging"
    ]
  }
}

Hook Phases

| Phase | Description | Hooks | |-------|-------------|-------| | pre_execution | Before skill execution | Language detection, validation, budget check | | post_execution | After skill execution | Quality gate validation, evidence verification | | on_error | On skill failure | Error classification, fallback, limitation flagging |

---

8. Tool Registration

Tools are registered with schemas and fallback mechanisms:

{
  "web_search": {
    "name": "WebSearch",
    "description": "Search the web for current domain news and research",
    "schema": {
      "input": {
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"]
      },
      "output": {
        "type": "array",
        "items": {"type": "object"}
      }
    },
    "rate_limit": {"requests_per_minute": 10},
    "fallback": "knowledge_base_search"
  }
}

---

9. JSON Schema Examples

Input Schema: sub-gather-requirements

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "user_message": {
      "type": "string",
      "minLength": 3,
      "description": "Raw user input message"
    },
    "language": {
      "type": "string",
      "enum": ["en", "vi", "auto"],
      "default": "auto",
      "description": "Target language for output"
    }
  },
  "required": ["user_message"]
}

Output Schema: sub-gather-requirements

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "object": {
      "type": "string",
      "description": "Object of analysis (e.g., 'professional gamer')"
    },
    "scope": {
      "type": "string",
      "description": "Analysis scope and boundaries"
    },
    "timeframe": {
      "type": "string",
      "description": "Analysis timeframe"
    },
    "available_inputs": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Available input data sources"
    },
    "target_audience": {
      "type": "string",
      "description": "Target audience for the analysis"
    },
    "language": {
      "type": "string",
      "enum": ["en", "vi"],
      "description": "Detected/confimed language"
    },
    "analysis_type": {
      "type": "string",
      "enum": ["combined", "reaction_only", "visual_only", "recovery_only"],
      "default": "combined",
      "description": "Type of analysis to perform"
    }
  },
  "required": ["object", "language"]
}

---

10. Runtime Usage

Loading the Registry

import json
from pathlib import Path

def load_skill_registry(registry_path: str = "config/skill_registry.json"):
    """Load and parse the skill registry"""
    with open(registry_path) as f:
        return json.load(f)

# Usage
registry = load_skill_registry()
skills = registry["registry"]["core_skills"]

Executing a Skill with Validation

def execute_skill(skill_id: str, input_data: Dict) -> Dict:
    """Execute a skill with full validation pipeline"""

    # 1. Load registry
    registry = load_skill_registry()
    skill = registry["registry"]["core_skills"][skill_id]

    # 2. Validate input
    if not validate_input(skill_id, input_data, registry):
        raise ValueError(f"Invalid input for skill {skill_id}")

    # 3. Execute skill (via Claude Code Skill tool or direct execution)
    output_data = execute_skill_impl(skill["entry_point"], input_data)

    # 4. Validate output
    if not validate_output(skill_id, output_data, registry):
        raise ValueError(f"Invalid output from skill {skill_id}")

    return output_data

---

11. Extension Guide

Adding a New Skill

1. Create skill markdown file in skills/
2. Add to registry in config/skill_registry.json:

{
  "my_new_skill": {
    "name": "my-new-skill",
    "entry_point": "skills/my-new-skill.md",
    "type": "analyzer",
    "priority": 10,
    "dependencies": ["sub_evidence_collector"],
    "provides": ["new_capability"],
    "input_schema": { ... },
    "output_schema": { ... }
  }
}

1. Update hooks if needed in scripts/hooks.py
2. Add tests in tests/test-scenarios.md

---

12. Validation Utilities

The scripts/validation_utils.py module provides:

def validate_registry(registry_path: str) -> bool:
    """Validate registry structure and schemas"""
    # Checks:
    # - JSON syntax valid
    # - All skills have required fields
    # - JSON schemas are valid
    # - Dependencies resolve correctly
    # - No circular dependencies
    pass

def validate_skill_consistency(registry: Dict) -> List[str]:
    """Check consistency between skills and hooks"""
    # Returns list of inconsistencies
    pass

---

13. Observability

Event Logging

All hook executions are logged with:

{
  "timestamp": "2026-07-28T10:30:00Z",
  "hook": "language_detection",
  "phase": "pre_execution",
  "session_id": "abc123",
  "result": {
    "success": true,
    "data": {"language": "vi"}
  }
}

Retrieving Events

from scripts.hooks import get_registry

registry = get_registry()
events = registry.get_events(session_id="abc123")

---

14. Error Handling

Degradation Levels

| Level | Condition | Behavior | |-------|-----------|----------| | 0 | All sources available | Full analysis | | 1 | Some sources fail | Use fallbacks, flag substitutions | | 2 | Most sources fail | Knowledge base only, add notice | | 3 | Critical inputs missing | Partial analysis, flag gaps | | 4 | Complete failure | Error notice, no analysis |

Fallback Chain

FALLBACK_CHAIN = {
    1: ['alternate_source', 'cached_data'],
    2: ['knowledge_base_only', 'aggregate_sources'],
    3: ['knowledge_base_only', 'limitation_flags'],
    4: ['error_notice']
}

---

15. Quality Gates

Universal Gates (U1-U6)

| Gate | Check | Auto-Fix | |------|-------|----------| | U1 | ≥3 sources, ≥1 academic | Fetch from knowledge base | | U2 | Disclosure before recommendation | Prepend disclosure | | U3 | Evidence tier labels | Annotate sources | | U4 | Language matches preference | Translate output | | U5 | Output format template | Reformat to template | | U6 | Claims traceable to sources | Flag unsupported claims |

Domain Gates (G1-G4)

| Gate | Check | Auto-Fix | |------|-------|----------| | G1 | Baseline assessed | Assess baseline | | G2 | Periodized practice | Add periodization | | G3 | Visual drills present | Add visual drills | | G4 | Recovery management | Add recovery plan |

---

16. Token Optimization

Budget Management

def estimate_token_cost(skill_id: str, input_data: Dict) -> int:
    """Estimate token cost for skill execution"""
    skill = registry["core_skills"][skill_id]

    # Base cost for skill loading
    base_cost = 500

    # Input cost
    input_cost = len(json.dumps(input_data)) // 4

    # Output cost (estimated)
    output_cost = skill.get("estimated_output_tokens", 2000)

    return base_cost + input_cost + output_cost

---

17. Testing

Skill Registry Tests

# Run registry validation
python -m scripts.validation_utils validate config/skill_registry.json

# Test skill execution
python -m scripts.test_skill_execution sub-gather-requirements

---

18. Maintenance

Registry Health Checks

def check_registry_health(registry_path: str) -> Dict:
    """Perform health checks on registry"""
    return {
        "syntax_valid": check_json_syntax(registry_path),
        "all_skills_present": check_skill_files_exist(),
        "dependencies_valid": check_no_circular_deps(),
        "schemas_valid": check_json_schemas(),
        "hooks_registered": check_hook_registration()
    }

---

References

• config/skill_registry.json — Central registry definition
• scripts/hooks.py — Hooks implementation
• scripts/validation_utils.py — Validation utilities
• skills/*.md — Individual skill definitions
• PROJECT-detail.md — Full technical specification

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/pro-gamer-eye-hand-training-agent-skill
• License: MIT

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