# Game Lore Theorycrafting Mystery Agent Skill

> A Claude skill from dungnotnull/game-lore-theorycrafting-mystery-agent-skill.

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-game-lore-theorycrafting-mystery-agent-skill-game-lore-theorycrafting-mystery-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/game-lore-theorycrafting-mystery-agent-skill

## Install

```sh
agentstack add skill-dungnotnull-game-lore-theorycrafting-mystery-agent-skill-game-lore-theorycrafting-mystery-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 — 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`:

```python
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).
2. **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**
```json
{
  "type": "object",
  "required": ["query"],
  "properties": {"query": {"type": "string"}, "language": {"type": "string"}},
  "additionalProperties": true
}
```
**Output**
```json
{
  "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.

```python
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

```bash
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](https://github.com/dungnotnull)
- **Source:** [dungnotnull/game-lore-theorycrafting-mystery-agent-skill](https://github.com/dungnotnull/game-lore-theorycrafting-mystery-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:** no
- **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-game-lore-theorycrafting-mystery-agent-skill-game-lore-theorycrafting-mystery-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%.