Arpg Mmo Gear Progression Agent Skill

SKILL.md — Skill Registry & Architecture Documentation

> arpg-mmo-gear-progression v2.0.0 — ARPG/MMO Gear Progression & Build Economics Analysis Harness

---

Overview

This document defines the skill registry system, including how skills are registered, resolved, executed, and validated. It serves as the canonical reference for the skill architecture used throughout this project.

---

Skill Registry System

Registration

All skills must be registered in config/skill_registry.yaml with the following metadata:

skills:
  - name: main
    display_name: arpg-mmo-gear-progression
    version: 2.0.0
    description: Optimal Gear Progression Path in ARPG/MMO — ARPG/MMO Gear Progression & Build Economics analysis & decision-support harness
    path: skills/main.md
    type: harness
    triggers:
      - "gear progression"
      - "build optimization"
      - "ARPG build"
      - "MMO economy"
      - "itemization"
      - "stat priority"
    sub_skills:
      - sub-gather-requirements
      - sub-evidence-collector
      - sub-core-analysis
      - sub-knowledge-updater
      - sub-advisor
    dependencies:
      - SECOND-KNOWLEDGE-BRAIN.md
      - config/knowledge_config.yaml
    tools_required:
      - WebSearch
      - WebFetch
      - Read
      - Write
      - Skill
    quality_gates:
      - U1: "≥3 sources cited, ≥1 academic/authoritative"
      - U2: "Safety/risk/limitation disclosure present"
      - U3: "Evidence hierarchy stated per source"
      - U4: "Language matches user preference"
      - U5: "Output uses declared template"
      - U6: "Every claim traceable to source or flagged"
      - G1: "Game-specific build simulated"
      - G2: "Stat priorities quantified"
      - G3: "Acquisition cost calculated"
      - G4: "Verdict category matches analysis"
    output_template: references/templates/output_template.md

Skill Types

| Type | Description | Example | |------|-------------|---------| | harness | Main orchestrator that coordinates sub-skills | main.md | | sub-skill | Specialized component for a specific task | sub-core-analysis.md | | utility | Helper skill for cross-cutting concerns | (future) sub-_validator.md | | standalone | Independent skill that can be used alone | (future) patch-note-analyzer.md |

Skill Resolution

When a user query is received, the skill resolver:

1. Extract keywords from the user query using NLP
2. Match against trigger patterns in the registry
3. Calculate relevance score using:

• Exact phrase match: 1.0
• Keyword overlap: 0.7 × (matchedkeywords / totalkeywords)
• Semantic similarity: 0.3 (using embeddings)

1. Select top-scoring skill above threshold (default 0.6)
2. Check dependencies are available
3. Verify tool access for required tools
4. Load and execute the selected skill

Skill Execution Flow

USER QUERY
    │
    ▼
[SKILL RESOLVER]
    │
    ├─► Extract keywords
    ├─► Match triggers
    ├─► Calculate scores
    └─► Select skill
    │
    ▼
[DEPENDENCY CHECK]
    │
    ├─► Validate dependencies present
    ├─► Check tool access
    └─► Load skill file
    │
    ▼
[SKILL EXECUTION]
    │
    ├─► Parse frontmatter
    ├─► Initialize context
    ├─► Execute workflow steps
    ├─► Run quality gates
    └─► Format output
    │
    ▼
[OUTPUT VALIDATION]
    │
    ├─► Validate against schema
    ├─► Check quality gates
    ├─► Apply auto-fix if needed
    └─► Return to user

---

Input/Output JSON Schemas

Input Schema

All skills accept a standardized input structure:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "SkillInput",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The user's natural language query"
    },
    "context": {
      "type": "object",
      "description": "Additional context provided by the system",
      "properties": {
        "language": {
          "type": "string",
          "enum": ["en", "vi"],
          "default": "en"
        },
        "user_id": {
          "type": "string",
          "description": "Optional user identifier for personalization"
        },
        "session_id": {
          "type": "string",
          "description": "Session identifier for context tracking"
        },
        "available_tools": {
          "type": "array",
          "items": {"type": "string"},
          "description": "List of available tool names"
        },
        "token_budget": {
          "type": "integer",
          "description": "Maximum tokens for this execution"
        }
      }
    },
    "attachments": {
      "type": "array",
      "description": "File attachments or additional data",
      "items": {
        "type": "object",
        "properties": {
          "type": {"type": "string"},
          "content": {"type": "string"},
          "metadata": {"type": "object"}
        }
      }
    }
  },
  "required": ["query"]
}

Output Schema

All skills produce a standardized output structure:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "SkillOutput",
  "type": "object",
  "properties": {
    "result": {
      "type": "string",
      "description": "Primary output content (markdown formatted)"
    },
    "metadata": {
      "type": "object",
      "properties": {
        "skill_name": {"type": "string"},
        "skill_version": {"type": "string"},
        "execution_time_ms": {"type": "number"},
        "tokens_used": {"type": "integer"},
        "quality_gates_passed": {
          "type": "array",
          "items": {"type": "string"}
        },
        "quality_gates_failed": {
          "type": "array",
          "items": {"type": "string"}
        },
        "sources_cited": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url": {"type": "string"},
              "title": {"type": "string"},
              "tier": {"type": "string", "enum": ["T1", "T2", "T3", "T4"]}
            }
          }
        }
      }
    },
    "artifacts": {
      "type": "array",
      "description": "Generated files or structured data",
      "items": {
        "type": "object",
        "properties": {
          "type": {"type": "string"},
          "path": {"type": "string"},
          "description": {"type": "string"}
        }
      }
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {"type": "string"},
          "message": {"type": "string"},
          "severity": {"type": "string", "enum": ["error", "warning", "info"]},
          "recoverable": {"type": "boolean"}
        }
      }
    }
  },
  "required": ["result", "metadata"]
}

---

Validation Rules

Skill File Validation

All skill files must pass the following validation checks:

1. Frontmatter Validation

• Required fields: name, description
• Optional fields: version, author, compatibility
• Valid YAML syntax

1. Section Validation

• Required sections: ## Role & Persona, ## Workflow
• Recommended sections: ## Tools, ## Output Format, ## Quality Gates
• Proper heading hierarchy (no skipped levels)

1. Link Validation

• All internal links reference existing files
• External links are HTTPS (where applicable)
• No broken references to other skills

1. Content Quality

• No placeholder text ("TODO", "TBD", etc.)
• Clear instructions with specific examples
• Proper markdown formatting
• Code blocks with language specifiers

Runtime Validation

During skill execution, the following validations occur:

1. Pre-execution Checks

• All required tools are available
• Dependencies are accessible
• Token budget is sufficient
• User permissions are adequate

1. Mid-execution Checks

• Quality gate satisfaction at each step
• Data validation from external sources
• Error recovery triggers

1. Post-execution Checks

• Output schema validation
• Quality gate passage
• Evidence citation completeness
• Language preference adherence

---

Dependency Management

Dependency Types

| Type | Description | Resolution | |------|-------------|------------| | file | Local file dependency | Path resolution relative to skill | | skill | Other skill dependency | Recursive skill loading | | package | Python package dependency | Import and availability check | | api | External API dependency | Health check and authentication | | config | Configuration file dependency | Config loader with validation |

Dependency Resolution

def resolve_dependencies(skill_metadata: dict) -> dict:
    """
    Resolve all dependencies for a skill.
    
    Returns:
        dict with keys:
        - resolved: List of successfully resolved dependencies
        - missing: List of missing dependencies
        - warnings: List of non-critical issues
    """
    result = {"resolved": [], "missing": [], "warnings": []}
    
    for dep in skill_metadata.get("dependencies", []):
        dep_type = dep.get("type", "file")
        dep_spec = dep.get("spec")
        
        if dep_type == "file":
            if Path(dep_spec).exists():
                result["resolved"].append(dep)
            else:
                result["missing"].append(dep)
        
        elif dep_type == "skill":
            if skill_available(dep_spec):
                result["resolved"].append(dep)
            else:
                result["missing"].append(dep)
        
        # ... other dependency types
    
    return result

---

Sub-Skill Communication

Sub-skills communicate through typed interfaces defined in Pydantic models:

Requirements Object

class Requirements(BaseModel):
    object_of_analysis: str
    scope: str
    timeframe: str
    available_inputs: List[str]
    target_audience: str
    language: str
    analysis_type: str

Evidence Bundle

class EvidenceBundle(BaseModel):
    current_data: Dict[str, Any]
    authoritative_docs: List[EvidenceCitation]
    recent_news: List[EvidenceCitation]
    reference_benchmarks: Dict[str, Any]
    collection_metadata: Dict[str, Any]

Analysis Scorecard

class AnalysisScorecard(BaseModel):
    game: str
    build_config: BuildConfig
    stat_priorities: List[StatPriority]
    acquisition_paths: List[AcquisitionPath]
    progression_milestones: List[ProgressionMilestone]
    tradeoffs: List[Tradeoff]
    scenarios: List[Scenario]
    analysis_metadata: Dict[str, Any]

Knowledge Result

class KnowledgeResult(BaseModel):
    citations: List[AcademicReference]
    coverage_rating: str
    gaps_identified: List[str]
    recommendations: List[str]

Advisor Output

class AdvisorOutput(BaseModel):
    verdict_category: VerdictCategory
    confidence_level: str
    key_findings: List[str]
    scenarios: List[Scenario]
    risks_identified: List[RiskAssessment]
    evidence_chain: List[EvidenceCitation]
    remediation_options: List[str]
    mandatory_disclosure: str

---

Error Handling & Recovery

Error Categories

| Category | Severity | Recovery Strategy | |----------|----------|-------------------| | Tool Unavailable | Error | Graceful degradation, alternate tool | | API Failure | Warning | Cached data, retry with backoff | | Missing Dependency | Error | Halt execution, clear error message | | Validation Failure | Warning | Auto-fix if possible, flag for review | | Token Limit Exceeded | Error | Truncate output, suggest continuation | | Quality Gate Failure | Warning | Auto-fix, retry, manual review if persists |

Error Recovery Flow

ERROR DETECTED
    │
    ▼
[ERROR CLASSIFICATION]
    │
    ├─► Category: Tool/API/Dependency/Validation/QG
    ├─► Severity: Error/Warning/Info
    └─► Recoverable: Yes/No
    │
    ▼
[RECOVERY STRATEGY]
    │
    ├─► If recoverable:
    │   ├─► Try alternate approach
    │   ├─► Use cached/fallback data
    │   ├─► Apply auto-fix
    │   └─► Retry (max 2 attempts)
    │
    └─► If not recoverable:
        ├─► Log error details
        ├─► Generate error response
        └─► Suggest resolution

---

Quality Gate Implementation

Auto-Fix Mechanism

When a quality gate fails, the system attempts automatic fixes:

QUALITY_GATE_AUTO_FIXES = {
    "U1": {  # Source count
        "fix": "search_additional_sources",
        "params": {"min_sources": 3, "min_academic": 1}
    },
    "U2": {  # Disclosure present
        "fix": "prepend_disclosure",
        "params": {"template": "references/templates/disclosure_template.md"}
    },
    "U3": {  # Evidence hierarchy
        "fix": "apply_tier_labels",
        "params": {"label_map": {"T1": "Tier 1", "T2": "Tier 2", "T3": "Tier 3", "T4": "Tier 4"}}
    },
    "U4": {  # Language match
        "fix": "translate_to_preference",
        "params": {"target_language": "user_preference"}
    },
    "U5": {  # Template compliance
        "fix": "reformat_to_template",
        "params": {"template": "references/templates/output_template.md"}
    },
    "G1": {  # Build simulation
        "fix": "generate_build_simulation",
        "params": {"include_stat_blocks": True}
    },
    "G2": {  # Stat priorities
        "fix": "quantify_stat_priorities",
        "params": {"include_breakpoints": True}
    },
    "G3": {  # Acquisition cost
        "fix": "calculate_acquisition_cost",
        "params": {"include_time_currency": True}
    },
    "G4": {  # Verdict match
        "fix": "reconcile_verdict",
        "params": {"force_consistency": True}
    }
}

Retry Logic

def execute_with_retry(skill_func, max_retries=2):
    """
    Execute a skill function with automatic retry on quality gate failure.
    """
    for attempt in range(max_retries + 1):
        result = skill_func()
        
        failed_gates = check_quality_gates(result)
        
        if not failed_gates:
            return result
        
        if attempt  int:
       base_cost = SKILL_TOKEN_COSTS.get(skill_name, 1000)
       input_multiplier = input_size * 0.5
       overhead = 200  # System overhead
       return int(base_cost + input_multiplier + overhead)
   ```

3. **Budget Allocation**
   ```python
   def allocate_budget(total_budget: int, skills: List[str]) -> Dict[str, int]:
       # Allocate 60% to main analysis, 40% to sub-skills
       main_budget = int(total_budget * 0.6)
       sub_budget = int(total_budget * 0.4)
       
       # Distribute sub-budget evenly among sub-skills
       per_skill = sub_budget // len(skills)
       
       return {"main": main_budget, **{s: per_skill for s in skills}}
   ```

### Caching Strategy

```python
class SkillCache:
    """
    Multi-level cache for skill execution results.
    """
    
    def __init__(self):
        self.memory_cache = {}  # L1: In-memory cache
        self.disk_cache = Path(".cache/skills")  # L2: Disk cache
    
    def get(self, key: str, ttl: int = 3600) -> Optional[Any]:
        # Check memory first
        if key in self.memory_cache:
            if time.time() - self.memory_cache[key]["timestamp"]  dict:
    """
    Execute a skill with comprehensive logging.
    """
    execution_id = str(uuid.uuid4())
    
    logger.info(
        "skill_execution_started",
        skill_name=skill_name,
        execution_id=execution_id,
        input_size=len(str(input_data))
    )
    
    try:
        result = _execute_skill_internal(skill_name, input_data)
        
        logger.info(
            "skill_execution_completed",
            skill_name=skill_name,
            execution_id=execution_id,
            duration_ms=result["metadata"]["execution_time_ms"],
            tokens_used=result["metadata"]["tokens_used"],
            quality_gates_passed=result["metadata"]["quality_gates_passed"]
        )
        
        retu

…

## Source & license

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

- **Author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** [dungnotnull/arpg-mmo-gear-progression-agent-skill](https://github.com/dungnotnull/arpg-mmo-gear-progression-agent-skill)
- **License:** MIT

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