Esports Fairness Scoring

SKILL REGISTRY — esports-fairness-scoring

Overview

The esports-fairness-scoring skill implements a production-grade multi-agent harness for comprehensive esports tournament fairness and integrity analysis. It orchestrates specialized sub-skills through a chain-of-thought routing system with lifecycle hooks, quality gates, and graceful degradation.

Skill Registration

Main Harness Entry Point

Name: esports-fairness-scoring File: skills/main.md Type: Main harness orchestrator Inputs: User query + optional context materials Outputs: Structured fairness analysis report with verdict

Sub-Skills Registry

| Skill Name | File | Category | Purpose | Dependencies | |------------|------|----------|---------|--------------| | sub-gather-requirements | skills/sub-gather-requirements.md | sub | Clarify analysis scope and constraints | None | | sub-evidence-collector | skills/sub-evidence-collector.md | sub | Fetch authoritative real-time and reference data | sub-gather-requirements | | sub-core-analysis | skills/sub-core-analysis.md | sub | Analyze and score fairness dimensions | sub-evidence-collector | | sub-knowledge-updater | skills/sub-knowledge-updater.md | sub | Query knowledge base for academic evidence | None | | sub-advisor | skills/sub-advisor.md | sub | Synthesize into risk-disclosed conclusion | All prior sub-skills |

Skill Resolution

Resolution Order

1. Intent Classification: Router analyzes user query
2. Path Selection: Choose execution path based on intent
3. Dependency Resolution: Ensure prerequisites met
4. Execution Orchestration: Execute skills in required order
5. Result Aggregation: Combine outputs into final report

Execution Modes

Sequential (Default): Skills execute one after another, passing outputs forward

Parallel: Independent skills execute concurrently (when dependencies allow)

Conditional: Skills execute based on branch conditions (targeted assessment mode)

Skill Execution

Lifecycle Hooks

Each skill execution triggers hooks at defined lifecycle points:

before_execution:

• validate_inputs: Verify input schema compliance
• check_dependencies: Ensure prerequisite data available
• authorize: Verify permission for requested operation
• initialize: Set up execution context

after_execution:

• log_results: Record execution outcome
• collect_metrics: Track token usage, time
• `emit_events**: Notify completion to event bus
• cleanup: Release resources

on_error:

• identify_failure: Categorize error type
• attempt_recovery: Execute recovery strategy
• escalate_if_needed: Determine if human intervention required
• notify_stakeholders: Alert on critical failures

onqualitygate_failure:

• attempt_auto_fix: Execute gate-specific fix
• retry_if_allowed: Re-execute if retry budget available
• `degrade_gracefully': Fall back to lower fidelity mode
• flag_limitation: Record limitation for disclosure

Execution Context

Each skill receives:

{
  "skill_name": "sub-core-analysis",
  "execution_id": "uuid",
  "timestamp": "ISO-8601",
  "inputs": {
    "from_previous_skills": {},
    "from_user": {}
  },
  "config": {
    "timeout_seconds": 120,
    "max_retries": 2,
    "quality_gates": ["G1", "G2", "G3", "G4"]
  },
  "metadata": {
    "trace_id": "uuid",
    "language": "en",
    "degradation_level": 0
  }
}

Return Schema

Each skill must return:

{
  "status": "success|error|degraded",
  "output": {
    "skill_specific_data": {}
  },
  "metadata": {
    "execution_time_seconds": 0.0,
    "tokens_used": 0,
    "quality_gates_passed": [],
    "quality_gates_failed": [],
    "degradation_events": 0
  },
  "errors": []
}

Tool Definitions

Available Tools

| Tool | Schema | Handler | Usage | |------|--------|---------|-------| | WebSearch | schemas/web-search-input.json | Native Claude tool | Fetch live domain news and developments | | WebFetch | schemas/web-fetch-input.json | Native Claude tool | Scrape authoritative documents and standards | | Read | schemas/read-input.json | Native Claude tool | Read files (knowledge base, configs) | | Write | schemas/write-input.json | Native Claude tool | Append to knowledge base | | Bash | schemas/bash-input.json | Native Claude tool | Execute scripts (crawl pipeline) | | Skill | schemas/skill-input.json | Native Claude tool | Invoke sub-skills |

Tool Invocation Schema

WebSearch:

{
  "query": "string (required, max 500 chars)",
  "allowed_domains": ["array of strings (optional)"],
  "blocked_domains": ["array of strings (optional)"],
  "recency_filter": "oneDay|oneWeek|oneMonth|oneYear|noLimit (optional)"
}

WebFetch:

{
  "url": "string (required, valid URL)",
  "prompt": "string (required, extraction instructions)"
}

Skill:

{
  "skill": "string (required, registered skill name)",
  "args": "object (optional, skill-specific arguments)"
}

Input/Output Schemas

Main Harness Input

{
  "user_query": "string (required)",
  "provided_materials": {
    "type": "array of objects (optional)",
    "description": "Optional files or context provided by user"
  },
  "language_preference": "en|vi|auto (optional, default: auto-detect)"
}

Main Harness Output

See assets/schemas/analysis-output-schema.json for complete schema.

Required Top-Level Fields:

• analysis_id: UUID
• timestamp: ISO-8601
• language: "en" or "vi"
• requirements: Object
• evidence_bundle: Object
• scorecard: Object
• verdict: Object
• recommendations: Array
• disclosure: Object
• evidence_chain: Array
• quality_gates: Object

Quality Gates

Universal Gates (U1-U6)

U1: Minimum 3 sources cited, at least 1 academic/authoritative

U2: Risk/limitation disclosure appears BEFORE recommendation

U3: Evidence hierarchy stated per source (Tier 1-4)

U4: Output language matches user preference

U5: Output uses declared template with all sections present

U6: Every claim traced to ≥1 source OR flagged as [analyst judgment]

Domain Gates (G1-G4)

G1: Fairness dimensions scored (format, integrity, rules, incentives)

G2: Integrity risks assessed with signal indicators

G3: Dispute resolution and incentive alignment addressed

G4: Inclusion and accessibility scored

Gate Enforcement

• Apply gates in sequential order
• On failure: execute auto-fix strategy
• Max 2 retries per gate
• After 2 failures: emit limitation, continue with degraded output
• Final output includes gate status + limitations

Graceful Degradation

Degradation Levels

Level 0: Full operation (all sources reachable)

Level 1: Partial degradation (some primary sources substituted)

Level 2: Knowledge base only (historical context)

Level 3: Missing variables (flag as DATA UNAVAILABLE)

Level 4: Critical failure (emit DATA UNAVAILABLE notice)

Degradation Behavior

• Automatic escalation based on data availability
• Explicit limitation banner at levels ≥1
• No data fabrication at any level
• Clear communication of what is/isn't available

Configuration

Environment Variables

# Core
LOG_LEVEL=INFO|DEBUG|WARNING|ERROR|CRITICAL
ENVIRONMENT=development|staging|production

# LLM Settings
LLM_PROVIDER=anthropic|openai|google|azure
LLM_MODEL=claude-sonnet-4-20250514
LLM_TEMPERATURE=0.3
LLM_MAX_TOKENS=8192

# Crawl Pipeline
CRAWL_ENABLED=true|false

# Feature Flags
ENABLE_METRICS=true|false
ENABLE_TRACING=true|false
ENABLE_CACHING=true|false

Config File

See config/settings.py for type-safe configuration management.

Extension Points

Adding Custom Skills

1. Create skill file following SKILL.md template
2. Add to registry in this SKILL.md
3. Implement input/output schemas
4. Define dependencies and tools required
5. Add quality gates if applicable

Adding Custom Hooks

1. Implement hook function in scripts/hooks/
2. Register in configuration
3. Define trigger conditions
4. Specify async/sync execution

Adding Custom Quality Gates

1. Define gate in appropriate skill file
2. Specify check criteria
3. Define auto-fix strategy
4. Set retry limit

Validation

Schema Validation

All inputs and outputs are validated against JSON schemas in assets/schemas/:

• skill-registry-schema.json
• agent-message-schema.json
• analysis-output-schema.json

Validation Commands

# Validate project structure
python tools/validate_project.py

# Validate skill registry
python scripts/validate_skill_registry.py

# Validate configuration
python scripts/validate_config.py

Troubleshooting

Common Issues

Skill not found: Verify skill is registered in SKILL.md

Quality gate failure: Check auto-fix strategy and retry limit

Degradation level 4: All data sources failed, check internet connection and source availability

Language mismatch: Verify language detection in pre-flight step

Schema validation error: Check input/output against schemas

Performance Considerations

• Context window management: Progressive summary when approaching limit
• Token budgeting: Allocate per sub-skill based on complexity
• Caching: Cache deterministic LLM operations
• Parallel execution: Enable for independent sub-skills
• Rate limiting: Respect provider rate limits

Security

• Input validation: All inputs validated against schemas
• Output sanitization: Remove sensitive information before output
• Secret management: Use environment variables for credentials
• Audit logging: Track all skill invocations and modifications

License

MIT License — see LICENSE file

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/esports-fairness-scoring-agent-skill
• License: MIT

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