Matchmaking System Optimization Agent Skill

SKILL.md — matchmaking-system-optimization (Skill Registry)

> Skill registry documentation for matchmaking-system-optimization v2.0.0. > This document describes how skills are registered, resolved, executed, and > validated, including the canonical input/output JSON schemas, the tool > catalogue, the chain-of-thought router, the lifecycle hooks and the quality > gates. It is the single source of truth for integrating with the framework > (whether you drive it from Python, Claude Code markdown skills, or an LLM).

---

1. Overview

matchmaking-system-optimization is a modular skill-registry harness for the Game Matchmaking & Player-Skill Balancing domain. It combines:

• A skill registry (src.skill.SkillRegistry) — resolve + execute skills.
• A tool registry (src.tools.ToolRegistry) — typed, schema-validated tools.
• A chain-of-thought router (src.router.CoTRouter) — plan the skill pipeline.
• Lifecycle hooks (src.hooks.HookRegistry) — observe/mutate run state.
• Quality gates U1–U6 (universal) + G1–G4 (domain) with auto-fix.
• Graceful degradation (Levels 0–4) with explicit LIMITATION banners.
• Type-safe config (config.Settings) from env + YAML + defaults.
• A knowledge base (SECOND-KNOWLEDGE-BRAIN.md) updated by a crawl pipeline.

The framework is LLM-agnostic and offline-capable: deterministic Python skills + tools produce complete, schema-valid runs; an LLM runner can be injected to enrich any skill while keeping the same contracts and gates.

---

2. Directory layout

config/         Settings (env + YAML + feature flags)
src/            Framework: agent, skill, router, hooks, tools, skills, schemas
src/tools/      Typed tool implementations (web, knowledge, matchmaking math)
src/skills/     Real Python skill handlers (5) + registry factory
skills/         Markdown skill definitions (prompt payload for Claude Code)
scripts/        setup, seed_knowledge, run_crawl, validate_project
references/     domain-knowledge, prompt-templates, sources (RAG grounding)
assets/         JSON schemas + architecture diagram
tools/          Crawl pipeline + structural validators (legacy, still used)
tests/          test-scenarios.md + pytest suites + TEST_RESULTS.md
logs/           Structured rotating JSON logs

---

3. Skill lifecycle: register → resolve → execute → validate

3.1 Registration

Skills are registered into a SkillRegistry. Two registration paths:

• Python handlers (authoritative for execution): src/skills/*.py extend

BaseSkill and are wired in src/skills/registry.py::build_default_skill_registry, which wraps them in a DocumentedSkill carrying their markdown doc.

• Markdown skills (skills/*.md) are loaded by MarkdownSkill and act as

the human/LLM-facing prompt payload; main.md is the harness entry point.

from src.harness import build_agent
agent = build_agent()          # registry + tools + router + hooks wired
print(agent.registry.names()) # ['sub-gather-requirements', ... 'sub-advisor', 'matchmaking-system-optimization']

3.2 Resolution

SkillRegistry.get(name) resolves by name; CoTRouter.plan(query) produces a RoutingDecision (ordered pipeline + intent + chain-of-thought reasoning).

3.3 Execution

Skill.execute(ctx, inputs):

1. validate input against input_schema (JSON Draft-07 subset);
2. call run(ctx, inputs) → domain output;
3. validate output against output_schema;
4. append an artefact to the ContextWindow;
5. run check_gate(output) → domain quality gate;
6. emit step_pre/step_post hooks;
7. return a typed SkillResult.

A failed-but-recoverable skill escalates DegradationState; a hard schema violation is reported in the SkillResult.error and the harness continues with an explicit limitation.

3.4 Validation

All schemas live in src/schemas.py (Draft-07 subset: type, properties, required, items, enum, minimum/maximum, minItems/maxItems, minLength, additionalProperties). External JSON-Schema files in assets/*.schema.json mirror the runtime schemas for tooling/consumers.

---

4. Registered skills

| Step | Skill name | Description | Input schema | Output schema | Gate | |------|------------|-------------|--------------|---------------|------| | 1 | sub-gather-requirements | Clarify object, scope, timeframe, inputs, audience, language | {query, language?} | requirements | object confirmed | | 2 | sub-evidence-collector | Aggregate authoritative real-time + reference data | requirements | evidence_bundle | currentdata + authoritativedocs present | | 3 | sub-core-analysis | Rating + match quality + queue + smurf + scenarios | {object, scope?, current_data?, authoritative_docs?} | core_analysis | all 5 components present | | 4 | sub-knowledge-updater | Surface KB citations; flag crawl gaps | {object, scope?, rating_system?} | knowledge_evidence | coverage set | | 5 | sub-advisor | Risk-disclosed conclusion + evidence chain + remediation | {object, match_quality?, ...} | conclusion | verdict ∈ declared set + disclosure present |

The matchmaking-system-optimization (main) entry is registered as documentation-only and drives the Claude Code markdown harness.

---

5. Canonical JSON schemas

5.1 Requirements

{
  "type": "object",
  "required": ["object","scope","timeframe","available_inputs","target_audience","language","analysis_type"],
  "properties": {
    "object": {"type":"string","minLength":1},
    "scope": {"type":"string"},
    "timeframe": {"type":"string"},
    "available_inputs": {"type":"array","items":{"type":"string"}},
    "target_audience": {"type":"string"},
    "language": {"type":"string","enum":["en","vi"]},
    "analysis_type": {"type":"string","enum":["combined","rating","quality","queue","abuse"]}
  }
}

5.2 Evidence bundle

{
  "type":"object","required":["current_data","authoritative_docs","recent_news","reference_benchmarks"],
  "properties": {
    "current_data": {"type":"array","items":{"type":"object"}},
    "authoritative_docs": {"type":"array","items":{"type":"object"}},
    "recent_news": {"type":"array","items":{"type":"object"}},
    "reference_benchmarks": {"type":"array","items":{"type":"object"}}
  }
}

5.3 Core analysis

{
  "type":"object","required":["rating_system","match_quality","queue_tuning","smurf_detection","scenarios"],
  "properties": {
    "rating_system": {"type":"object"},
    "match_quality": {"type":"object"},
    "queue_tuning": {"type":"object"},
    "smurf_detection": {"type":"object"},
    "scenarios": {"type":"object","required":["best","base","worst"]}
  }
}

5.4 Knowledge evidence

{
  "type":"object","required":["citations","gaps","coverage"],
  "properties": {
    "citations": {"type":"array","minItems":1,"items":{"type":"object"}},
    "gaps": {"type":"array","items":{"type":"string"}},
    "coverage": {"type":"string","enum":["Strong","Moderate","Weak"]}
  }
}

5.5 Conclusion

{
  "type":"object","required":["verdict","scenarios","key_risks","evidence_chain","remediation","disclosure"],
  "properties": {
    "verdict": {"type":"string","enum":["Optimal Matchmaking","Conditional (queue-time)","Low Match Quality","Inconclusive"]},
    "scenarios": {"type":"object","required":["best","base","worst"]},
    "key_risks": {"type":"array","minItems":1,"items":{"type":"object"}},
    "evidence_chain": {"type":"array","items":{"type":"object"}},
    "remediation": {"type":"array","items":{"type":"string"}},
    "disclosure": {"type":"string","minLength":1}
  }
}

5.6 Tool result

{
  "type":"object","required":["ok","data"],
  "properties": {
    "ok": {"type":"boolean"},
    "data": {"type":"object"},
    "error": {"type":"string"},
    "source": {"type":"string"},
    "degradation_level": {"type":"integer","minimum":0,"maximum":4}
  }
}

Full machine-readable schemas: assets/skill-registry.schema.json, assets/tool.schema.json, assets/output-report.schema.json.

---

6. Tool catalogue

| Tool | Purpose | Key inputs | |------|---------|-----------| | web_search | Web search with offline-fallback index | query, limit? | | web_fetch | Fetch+clean URL; KB fallback | url, max_chars? | | knowledge_query | Query SECOND-KNOWLEDGE-BRAIN.md | keywords, limit? | | elo | Elo expected score + rating update | ratings[a,b], result, k_factor? | | glicko2 | Glicko-2 rating/RD/volatility update | player, opponents[] | | match_quality | Skill/latency/premade quality score | skill_spread, latency_ms, premade_imbalance?, weights? | | queue_widening | Wait-time band widening + backfill | wait_seconds, base_band?, max_band?, queue_size? | | smurf_detection | Smurf risk score (age/velocity/winrate/kd) | account_age_days, games_played, win_rate?, ... |

Every tool declares input_schema + output_schema, retries transient failures (retryable, max_retries), and returns the uniform ToolResult.

---

7. Chain-of-thought router

CoTRouter.plan(query) → RoutingDecision{pipeline, intent, reasoning, options}. Intent is classified by keywords (standard, compare, risk, degraded, explain). The default pipeline is the 5 skills above. An optional llm_decider callback lets a model replace the planner with the same contract.

---

8. Lifecycle hooks

Events: run_start, step_pre, step_post, gate_pre, gate_post, degradation, run_end, error, context_budget. Hooks receive the run state dict and never raise the harness (errors are logged + swallowed). Built-ins: structured logging, context-budget compression, gate audit.

from src.hooks import HookRegistry, default_hooks
hooks = default_hooks()
hooks.on("step_post", lambda state: print("step done", state["skill"]))

---

9. Quality gates

Universal: U1 ≥3 sources/≥1 academic · U2 disclosure before recommendation · U3 tiers stated · U4 language match · U5 declared template · U6 traceability. Domain: G1 rating+uncertainty · G2 match quality scored · G3 queue/wait tradeoff · G4 smurf/abuse detection. Each gate has an Auto-Fix; after 2 failed retries a limitation is emitted.

---

10. Graceful degradation

Levels 0–4 (FULL → PARTIAL → KNOWLEDGEONLY → MISSINGINPUT → UNAVAILABLE). Escalation is centralised in src.degradation.DegradationState; a ⚠️ LIMITATION banner is prepended to the report at Level ≥ 1. The harness never fabricates data — missing inputs are flagged DATA UNAVAILABLE.

---

11. Configuration

Resolved by config.Settings in priority order: MSO_ env vars → config/default.yaml → built-in defaults. Feature flags live in config.FeatureFlags. See config/.env.example.

---

12. Programmatic usage

from src.harness import build_agent

agent = build_agent()
result = agent.run(
    "Analyze the LoL matchmaking system: rating, queue and smurf detection",
    seed_inputs={"regions": ["NA", "EU"], "premades": 2},
)
print(result.ok, result.language, result.decision["intent"])
print(result.steps[-1]["output"]["verdict"])
print(result.report)

CLI smoke run: python scripts/validate_project.py (8-File Contract + framework + e2e).

---

13. Claude Code (markdown) usage

Invoke /matchmaking-system-optimization [query]. The markdown skills/main.md runs the same 6-step harness (requirements → evidence → core → knowledge → advisor → quality gate) and shares the schemas, gates and verdict set above.

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/matchmaking-system-optimization-agent-skill
• License: MIT

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