Game Lore Theorycrafting Mystery Agent Skill

SKILL.md — Skill Registry Documentation

This document is the canonical registry reference for the game-lore-theorycrafting-mystery harness. It explains how skills are registered, resolved, executed, and validated, including the input/output JSON schemas that every skill declares.

> Runtime manifests are emitted by python -m scripts.dump_manifests into > assets/schemas/*.manifest.json. Treat those JSON files as the > machine-readable contract and this document as the human-readable guide.

---

1. Architecture Overview

The harness uses a modular skill-registry pattern with a chain-of-thought router, specialized sub-agents, lifecycle hooks, and richly typed tools.

USER QUERY
   │
   ▼
[ChainOfThoughtRouter] ── Route{skill_names, analysis_type, cot}
   │
   ▼
[HarnessRunner] ── builds AgentContext(ContextManager, HookBus, ToolRegistry)
   │
   ├─ Step 1: sub-gather-requirements      (intake)
   ├─ Step 2: sub-evidence-collector       (data librarian)
   ├─ Step 3: sub-core-analysis       ┐ parallel
   ├─ Step 4: sub-knowledge-updater  ┘ (when feature flag enabled)
   ├─ Step 5: sub-advisor                 (synthesis)
   └─ Step 6: Quality Gate Review + Final Report

Components

| Component | Module | Responsibility | |-----------|--------|----------------| | SkillRegistry | lore_agent.registry | Register, resolve, validate, execute skills | | ChainOfThoughtRouter | lore_agent.router | Decide ordered skills + CoT rationale (rule + LLM fallback) | | BaseAgent / sub-agents | lore_agent.skills_impl | Skill executors that bridge LLM ↔ structured JSON | | ToolRegistry | lore_agent.tools | Schema-validated, executable tools | | HookBus | lore_agent.hooks | Lifecycle / state-sync / event-emission hooks | | ContextManager | lore_agent.context | Token-budget tracking, compression/summary modes | | HarnessRunner | lore_agent.runner | End-to-end orchestration + quality gates |

---

2. Registration

A skill is a Skill dataclass registered with SkillRegistry.register:

from lore_agent.registry import Skill, SkillRegistry
from lore_agent.skills_impl import GatherRequirementsAgent

registry = SkillRegistry()
agent = GatherRequirementsAgent(llm_client)
registry.register(Skill(
    name="sub-gather-requirements",
    description="Intake specialist",
    run=agent.run,                 # Callable[[AgentContext, dict], dict]
    input_schema={...},            # JSON-schema (subset)
    output_schema={...},
    tools=["language_detect"],
    step="1",
    tags=["intake"],
))

Invariants:

• name is globally unique — re-registering raises SkillError.
• run must return a dict.
• Schemas use a dependency-free JSON-schema subset (type, required,

properties, enum, items, additionalProperties).

---

3. Resolution

Two resolution paths:

1. By name — registry.get("sub-advisor") → Skill (raises

SkillResolutionError if missing).

1. By route — registry.resolve_route(route) resolves an ordered list of

Skill objects from a Route produced by the router.

The router emits a Route (skill_names, analysis_type, cot, source). The rule router is deterministic and always available; an optional LLM router can override it, falling back to the rule router on LLM failure (graceful fallback).

---

4. Execution

registry.execute(name, context, inputs) performs, in order:

1. Input validation — _validate_against_schema(inputs, input_schema).
2. Hook emit — BEFORE_SKILL.
3. Run — skill.run(context, inputs) → dict.
4. Output validation — _validate_against_schema(output, output_schema).
5. Hook emit — AFTER_SKILL.
6. Context record — context.record_output(...) updates token budget.

Validation failures raise SkillError with a precise where pointer such as skill[sub-core-analysis].output.hypotheses[0].canon.

---

5. Validation Schemas (per skill)

sub-gather-requirements

Input

{
  "type": "object",
  "required": ["query"],
  "properties": {"query": {"type": "string"}, "language": {"type": "string"}},
  "additionalProperties": true
}

Output

{
  "type": "object",
  "required": ["object", "analysis_type", "language"],
  "properties": {
    "object": {"type": "string"},
    "scope": {"type": "string"},
    "timeframe": {"type": "string"},
    "available_inputs": {"type": "array"},
    "target_audience": {"type": "string"},
    "language": {"type": "string"},
    "analysis_type": {"type": "string"}
  },
  "additionalProperties": true
}

sub-evidence-collector

Input — required: ["object"], properties: {object, scope}. Output — required: ["access_limitations"], properties: {current_data, authoritative_docs, recent_news, reference_benchmarks, access_limitations}. Each item array element should include source, date, tier.

sub-core-analysis

Input — required: ["object"], properties: {object, cipher_candidates}. Output — required: ["theory_synthesis", "confidence"], properties: {mystery_sources, methodology, hypotheses[], canon[], speculation[], datamined[], theory_synthesis, evidence_trail, community_corroboration, confidence, scenarios{best,base,worst}, limitations}. Each hypothesis: {id, label, statement, evidence[], canon: bool}.

sub-knowledge-updater

Input — required: ["keywords"], properties: {keywords[], object}. Output — required: ["evidence_coverage"], properties: {citations[], knowledge_gaps[], gap_fill_finds[], evidence_coverage}. Each citation: {authors, year, title, venue, doi_or_url, tier, subcategory, relevance, key_finding, application}.

sub-advisor

Input — properties: {object}, additionalProperties: true. Output — required: ["conclusion", "disclosure"], properties: {conclusion (enum of 5 verdicts), confidence_distribution[], scenarios{}, key_risks[], evidence_chain[], remediation[], disclosure}.

---

6. Tool Registry

Tools are Tool objects with input_schema, output_schema, and a handler(context, inputs) -> dict. The runner exposes the ToolRegistry on ctx.state["tools"] so sub-agents can call tools.execute("web_search", {...}).

| Tool | Purpose | Destructive | |------|---------|-------------| | web_search | Search web/curated sources, tier-labeled | no | | web_fetch | Fetch URL text, graceful offline | no | | knowledge_query | Query brain for ranked citations + gaps | no | | knowledge_append | Append dedup entry to brain | yes | | cipher_decode | Decode caesar/atbash/base64/binary/hex/morse/vigenere/reverse | no | | language_detect | Pre-Flight vi/en detection | no |

Full schemas are emitted to assets/schemas/tools.manifest.json.

---

7. Hooks

HookBus supports BEFORE_RUN, AFTER_RUN, BEFORE_SKILL, AFTER_SKILL, ON_ERROR, ON_BUDGET, ON_TOOL_CALL, ON_LANGUAGE_DETECTED, ON_DEGRADATION. Hooks receive a HookContext and are isolated: a faulty hook is logged and (unless strict=True) does not crash the run.

from lore_agent.hooks import HookBus, HookContext, HookEvent

bus = HookBus()
@bus.on(HookEvent.AFTER_SKILL)
def log_skill(ctx: HookContext) -> None:
    print("completed", ctx.skill_name)

---

8. Context & Token Budget

ContextManager enforces the budget declared in config.settings.ContextSettings:

| Budget | Default | |--------|---------| | Max context | 180,000 tokens | | Steps 1-2 | 30,000 | | Steps 3-5 | 120,000 | | Step 6 | 30,000 | | Summary-only threshold | ≤ 20% remaining | | Compression threshold | ≤ 50% remaining |

record_step(step, output) estimates tokens (chars / chars_per_token), updates cumulative + per-step consumption, and auto-activates compression and summary-only modes.

---

9. Error Handling & Graceful LLM Fallback

• All failures are typed (LLMError, ToolError, SkillError,

BrainFileError, SkillResolutionError, ContextBudgetError).

• LLM calls retry with exponential backoff + jitter; after retries the

sub-agent returns a structured fallback_output instead of crashing (when llm.enable_graceful_fallback is true).

• A provider is auto-selected from env keys; if the chosen provider is

unavailable (missing lib/key), build_llm_client falls back to the deterministic MockLLMClient so the harness is always runnable.

---

10. CLI

python -m scripts.run_agent "decode the Dark Souls Gwyn mystery"
python -m scripts.run_agent --query "..." --language vi --json
python -m scripts.run_agent --list-skills
python -m scripts.run_agent --list-tools
python -m scripts.dump_manifests      # emit assets/schemas/*.manifest.json
python -m scripts.setup_env --init-config
python -m scripts.seed_knowledge_base
python -m scripts.ingest_sources --file sources.json

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/game-lore-theorycrafting-mystery-agent-skill
• License: MIT

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