# Matchmaking System Optimization Agent Skill

> A Claude skill from dungnotnull/matchmaking-system-optimization-agent-skill.

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-matchmaking-system-optimization-agent-skill-matchmaking-system-optimization-agent-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dungnotnull](https://agentstack.voostack.com/s/dungnotnull)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** https://github.com/dungnotnull/matchmaking-system-optimization-agent-skill

## Install

```sh
agentstack add skill-dungnotnull-matchmaking-system-optimization-agent-skill-matchmaking-system-optimization-agent-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

```python
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` | current_data + authoritative_docs 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
```json
{
  "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
```json
{
  "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
```json
{
  "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
```json
{
  "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
```json
{
  "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
```json
{
  "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.

```python
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 → KNOWLEDGE_ONLY → MISSING_INPUT → 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

```python
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](https://github.com/dungnotnull)
- **Source:** [dungnotnull/matchmaking-system-optimization-agent-skill](https://github.com/dungnotnull/matchmaking-system-optimization-agent-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dungnotnull-matchmaking-system-optimization-agent-skill-matchmaking-system-optimization-agent-skill
- Seller: https://agentstack.voostack.com/s/dungnotnull
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.