# Game Roleplay Scenario Design Agent Skill

> A Claude skill from dungnotnull/game-roleplay-scenario-design-agent-skill.

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-game-roleplay-scenario-design-agent-skill-game-roleplay-scenario-design-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-roleplay-scenario-design-agent-skill

## Install

```sh
agentstack add skill-dungnotnull-game-roleplay-scenario-design-agent-skill-game-roleplay-scenario-design-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 & 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/`).
2. **LLM-facing skills** - markdown files (`skills/*.md`) that define persona,
   workflow, output format, and quality gates for model-driven execution.
3. **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`.

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

```python
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).
2. **`pre_invoke` hooks** fire; `SHORT_CIRCUIT` aborts the skill.
3. **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)`.
4. **Output validation** - the handler result is validated against
   `outputs_schema`; on success the output is fed against the token budget
   (`ctx.feed(...)`).
5. **`post_invoke` hooks** fire.
6. **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

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

```bash
# 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).
3. Append an entry to `skills/registry.json` (name, kind `sub`, schemas,
   tools, depends_on, quality_gates).
4. Optionally add a programmatic handler in `src/rpsd/handlers.py` and register
   it via `default_handlers()`.
5. Add a prompt base-template in `references/prompt-templates/`.
6. 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](https://github.com/dungnotnull)
- **Source:** [dungnotnull/game-roleplay-scenario-design-agent-skill](https://github.com/dungnotnull/game-roleplay-scenario-design-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-roleplay-scenario-design-agent-skill-game-roleplay-scenario-design-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%.