Game Roleplay Scenario Design Agent Skill

SKILL.md - Skill Registry & Agent Architecture

> Canonical documentation for the modular skill-registry architecture of > game-roleplay-scenario-design (Skill 205). This file is the contract between > the LLM-facing skill markdown (skills/*.md), the programmatic runtime > (src/rpsd/), the declarative manifests (skills/registry.json, > config/tools.json, config/hooks.json), and the JSON Schemas > (assets/schemas/). Read this before extending the harness.

---

1. Design Philosophy

The harness is registry-driven rather than hard-coded. Three layers cooperate:

1. Declarative manifests - machine-readable declarations of skills, tools,

and hooks (JSON, validated against schemas in assets/schemas/).

1. LLM-facing skills - markdown files (skills/*.md) that define persona,

workflow, output format, and quality gates for model-driven execution.

1. Programmatic runtime - src/rpsd/ loads the manifests, resolves routes,

validates I/O against JSON Schemas, fires hooks, invokes tools, and provides offline-safe handlers so the whole pipeline runs and is testable without an LLM or network.

This separation means: (a) adding a skill is a manifest + markdown + schema change, not a core-code change; (b) every skill I/O is schema-validated; (c) the pipeline is reproducible and testable offline; (d) a host runtime (Claude Code) drops in live tool/handler implementations without touching skill logic.

---

2. Directory Layout

game-roleplay-scenario-design/
+- skills/                 # LLM-facing skill markdown + registry manifest
|  +- main.md              # orchestrator
|  +- sub-router.md        # chain-of-thought router
|  +- sub-gather-requirements.md
|  +- sub-evidence-collector.md
|  +- sub-core-analysis.md
|  +- sub-knowledge-updater.md
|  +- sub-advisor.md
|  +- registry.json        # skill manifest (the registry)
+- src/rpsd/               # programmatic runtime package
|  +- registry.py  hooks.py  tools.py  context.py  schemas.py
|  +- handlers.py  jschema.py  config.py  logging.py  errors.py
+- config/                 # type-safe configuration + tool/hook manifests
|  +- default.json  tools.json  hooks.json  settings.py
+- assets/schemas/         # JSON Schemas for skills, tools, hooks, and I/O
+- references/             # domain knowledge + prompt base-templates (RAG grounding)
+- scripts/                # automation: setup, seeding, ingestion, validation, pipeline
+- hooks/                  # hook catalog documentation
+- tools/                  # legacy crawlers/validators (kept; runtime lives in src/rpsd)
+- tests/                  # scenario definitions + unit tests
+- SKILL.md                # THIS FILE

---

3. Skill Registration

3.1 Manifest format

Skills are declared in skills/registry.json, validated against assets/schemas/skill-manifest.schema.json.

{
  "version": "2.0.0",
  "skills": [
    {
      "name": "sub-core-analysis",
      "kind": "sub",                      // "orchestrator" | "router" | "sub"
      "description": "...",
      "file": "skills/sub-core-analysis.md",
      "inputs_schema": "assets/schemas/evidence-bundle.schema.json",
      "outputs_schema": "assets/schemas/scenario-design.schema.json",
      "tools": ["knowledge_query", "read_file", "web_search"],
      "depends_on": ["sub-evidence-collector"],
      "quality_gates": ["G1", "G2", "G3", "G4"],
      "routes_to": []                     // router-only: ordered sub-skill targets
    }
  ]
}

| Field | Required | Meaning | |-------|----------|---------| | name | yes | Unique skill identifier | | kind | yes | orchestrator (one), router (zero/one), sub (many) | | description | yes | One-line summary; also used for routing keywords | | file | yes | Path to the LLM-facing markdown skill | | inputs_schema | yes | Path to the input JSON Schema (empty string = no validation) | | outputs_schema | yes | Path to the output JSON Schema | | tools | no | Tool names this skill may invoke | | depends_on | no | Skills that must run before this one | | quality_gates | no | Gate IDs enforced by/for this skill | | routes_to | no | Router-only: ordered list of sub-skill names to route between |

3.2 Registering at runtime

from rpsd.registry import SkillRegistry, SkillRecord, SkillKind, load_default_registry
from rpsd.handlers import default_handlers

# Default: loads skills/registry.json and attaches offline handlers.
registry = load_default_registry(default_handlers())

# Or build manually:
reg = SkillRegistry()
reg.load(Path("skills/registry.json"))
reg.register_handler("sub-core-analysis", my_handler)

---

4. Skill Resolution

Resolution is the act of selecting which skill(s) to run.

• By name: registry.get("sub-core-analysis").
• By kind: registry.list_skills(SkillKind.SUB).
• Orchestrator: registry.orchestrator() returns the single orchestrator.
• Router: registry.router() returns the router (or None).
• Route resolution: registry.resolve_route(intent) runs the router's

chain-of-thought match: for each routes_to target, the target is included if the intent text contains any keyword derived from the target's name and description. If zero or all match, the full canonical chain is returned (dependency-ordered).

Canonical dependency chain: sub-gather-requirements -> sub-evidence-collector -> sub-core-analysis -> sub-knowledge-updater -> sub-advisor.

---

5. Skill Execution

registry.execute(name, ctx, payload=None) -> SkillExecution runs a skill:

1. Input validation - payload is validated against the skill's

inputs_schema (raises SchemaValidationError on failure).

1. pre_invoke hooks fire; SHORT_CIRCUIT aborts the skill.
2. Handler dispatch:

• If a programmatic handler is registered, it is called with

(ctx, tools) and must return a dict conforming to outputs_schema.

• If no handler is registered, SkillExecution.delegate=True is returned,

signalling the host runtime to drive skills/.md with the model and feed the parsed result back via registry.validate_output(name, result).

1. Output validation - the handler result is validated against

outputs_schema; on success the output is fed against the token budget (ctx.feed(...)).

1. post_invoke hooks fire.
2. Error/degradation - DegradedMode triggers on_degradation; schema /

not-found / tool errors trigger on_error and re-raise.

SkillExecution fields: skill, delegate, output, degradation_level, errors, and ok (no errors).

---

6. Validation

All I/O is validated against JSON Schemas in assets/schemas/. The runtime ships a minimal stdlib-only validator (src/rpsd/jschema.py) implementing the subset used here: type, required, properties, items, enum, minItems, minimum, maximum, additionalProperties.

6.1 I/O schema catalog

| Schema | Used by | Shape | |--------|---------|-------| | requirements-output.schema.json | gather-requirements (out), orchestrator (in) | {object, scope, timeframe, available_inputs[], target_audience, language, analysis_type} | | evidence-bundle.schema.json | evidence-collector (out), core-analysis (in) | {current_data[], authoritative_docs[], recent_news[], reference_benchmarks[], degradation_level, limitation_notice?} | | evidence-item.schema.json | reusable item shape | {title, source, url, accessed, tier, summary?, date?} | | scenario-design.schema.json | core-analysis (out), advisor (in) | {setting, themes[], tone, group, character_arcs[], faction_dynamics[], arc_structure, stakes, consequences, pacing, branching[], safety, best/base/worst_scenario} | | knowledge-result.schema.json | knowledge-updater (out) | {citations[], gaps[], coverage} | | advisor-conclusion.schema.json | advisor (out), orchestrator (out) | {verdict, disclosure, best/base/worst_scenario, key_risks[], evidence_chain[], remediation[], generated_on} | | router-output.schema.json | router (out) | {intent, route[]} | | skill-manifest.schema.json | registry manifest | {version, skills[]} | | tool.schema.json | tool manifest entries | {name, description, input_schema, output_schema, read_only} | | hook.schema.json | hook manifest entries | {name, phase, description, priority?} |

6.2 Closed-set enums (enforced by schema)

• Verdict: Ready-to-Run Scenario | Conditional (needs calibration) |

Underdeveloped | Inconclusive.

• Evidence tier: Tier 1 | Tier 2 | Tier 3 | Tier 4.
• Coverage: Strong | Moderate | Weak.
• Skill kind: orchestrator | router | sub.

6.3 Programmatic validation

from rpsd.jschema import validate, is_valid
errors = validate(instance, schema)   # [] == valid

The schema_validate tool exposes this to skills at runtime.

---

7. Tools

Tools are typed capabilities with input/output JSON Schemas and execution handlers (src/rpsd/tools.py, declared in config/tools.json, validated against tool.schema.json). Each Tool.run(ctx, args) validates args against input_schema, calls the handler, and validates the result against output_schema.

| Tool | Input | Output | Read-only | |------|-------|--------|-----------| | read_file | {path, limit?} | {path, content, bytes} | yes | | knowledge_query | {keywords[], limit?} | {matches[], coverage, keywords} | yes | | web_search | {query} | {query, results[], note} | yes (stub) | | web_fetch | {url} | {url, content, note} | yes (stub) | | schema_validate | {instance, schema} | {valid, errors[]} | yes | | token_estimate | {text} | {tokens, chars} | yes |

web_search and web_fetch are offline-safe stubs: they return a structured degradation notice (Level 2) instead of performing network I/O, so the pipeline is fully testable offline. A host runtime overrides them with live implementations.

Registering a custom tool:

from rpsd.tools import Tool, ToolCatalog, ToolResult
cat = ToolCatalog()
cat.register(Tool("my_tool", "desc", in_schema, out_schema, handler, read_only=False))

---

8. Hooks

Lifecycle hooks (src/rpsd/hooks.py, declared in config/hooks.json, validated against hook.schema.json) fire around every skill execution.

| Phase | Fires | Built-in hook | |-------|-------|---------------| | pre_invoke | before a skill runs | state_sync_pre (emit state snapshot) | | post_invoke | after a skill succeeds | state_sync_post (emit state snapshot) | | on_error | on any skill exception | (host-registered) | | on_degradation | on DegradedMode | degradation_watchdog (cap at L4, append notice) | | on_gate_fail | on a failed quality gate | gate_fail_logger (record on context) |

A hook is (HookContext) -> Optional[HookDecision]. Returning HookDecision.SHORT_CIRCUIT aborts the surrounding skill. The bus guards hook exceptions (logs + emits hook_error); set abort_on_error=True to make any hook failure abort the skill.

---

9. Context & Token Budget

AgentContext (src/rpsd/context.py) flows through every skill and hook. It carries: user_query, language, degradation_level, limitation_notices, gate_results, scratch, logs, a TokenBudget, and the structured outputs of each step (requirements, evidence, scenario, knowledge, conclusion).

TokenBudget(limit, reserved_output, safety_margin) tracks used/remaining. ctx.feed(text) accounts text against the budget (~4 chars/token). ctx.maybe_compact(threshold=0.25) signals the orchestrator to shed low-value scratch when headroom drops. This is the context-window management strategy: keep structured citations, drop raw evidence text under pressure.

---

10. End-to-End Flow

/user query
  |
  v
main.md (orchestrator)
  |- Pre-Flight: language detection -> LANG
  |- Step 0: sub-router -> route[] (chain-of-thought)
  |- Step 1: sub-gather-requirements  -> Requirements (schema-validated)
  |- Step 2: sub-evidence-collector   -> EvidenceBundle (degrades to KB at L2)
  |- Step 3: sub-core-analysis        -> ScenarioDesign (G1-G4)
  |- Step 4: sub-knowledge-updater    -> KnowledgeResult (tiers + gaps)
  |- Step 5: sub-advisor              -> AdvisorConclusion (verdict + disclosure)
  |- Step 6: quality gates U1-U6 + G1-G4 (auto-fix, 2 retries, limitation flags)
  v
final report (declared template, risk-disclosed)

Every arrow is: pre_invoke hooks -> schema-validated execute -> post_invoke hooks, with on_error/on_degradation/on_gate_fail available throughout.

---

11. Operational Commands

# Validate the skill/tool/hook registry against their schemas
python scripts/validate_registry.py --verbose

# Run the offline end-to-end pipeline (programmatic handlers, no LLM/network)
python scripts/run_pipeline.py --query "Design a GTA RP scenario with safety tools" --verbose

# Seed/ingest the knowledge base references
python scripts/seed_knowledge_base.py --check
python scripts/ingest_references.py --check

# Local setup (checks deps, paths, manifest)
python scripts/setup.py --check

# Crawl pipeline (existing) - appends to SECOND-KNOWLEDGE-BRAIN.md
python tools/knowledge_updater.py --dry-run --log-level INFO

# Structured validators
python tools/validate_project.py --verbose
python tools/run_test_scenarios.py --all --verbose
python tools/test_knowledge_updater.py --verbose

---

12. Extending the Harness

To add a new sub-skill:

1. Add a JSON Schema for its output in assets/schemas/.
2. Write skills/sub-.md (frontmatter + Role & Persona + Workflow +

Output Format + Quality Gates).

1. Append an entry to skills/registry.json (name, kind sub, schemas,

tools, dependson, qualitygates).

1. Optionally add a programmatic handler in src/rpsd/handlers.py and register

it via default_handlers().

1. Add a prompt base-template in references/prompt-templates/.
2. Add tests in tests/ and run python scripts/validate_registry.py.

To add a tool: append to config/tools.json, implement a handler in src/rpsd/tools.py, and register it in default_catalog().

To add a hook: append to config/hooks.json, implement it in src/rpsd/hooks.py, and register it in default_bus().

---

13. Configuration

Type-safe configuration lives in src/rpsd/config.py and config/default.json. Settings are loaded from environment variables (prefix RPSD_) and optionally overridden by config/default.json. Key flags:

| Flag / env var | Default | Effect | |----------------|---------|--------| | RPSD_FLAG_ROUTER | true | Enable the chain-of-thought router | | RPSD_FLAG_KNOWLEDGE_CRAWL | true | Enable the knowledge crawl pipeline | | RPSD_FLAG_SAFETY_TOOLS | true | Require safety tools (G4) | | RPSD_FLAG_BRANCHING_AGENCY | true | Require branching agency (G3) | | RPSD_FLAG_STRUCTURED_LOGGING | false | Emit JSON log lines | | RPSD_FLAG_STRICT_SCHEMAS | true | Enforce I/O schema validation | | RPSD_FLAG_GRACEFUL_DEGRADATION | true | Honor degradation levels 0-4 | | RPSD_CONTEXT_WINDOW_TOKENS | 200000 | Model context window size | | RPSD_LLM_MODEL | claude-sonnet | Default model id | | RPSD_LLM_MAX_RETRIES | 3 | LLM call retry budget |

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-roleplay-scenario-design-agent-skill
• License: MIT

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