重构插件入口与runtime安装流程

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "codex-game-studios",
-  "version": "0.1.1",
-  "description": "A Codex plugin for building game-production workflows step by step, starting with guided game concept brainstorming.",
+  "version": "0.2.0",
+  "description": "A Codex plugin for game-production workflows, project runtime setup, and guided game concept brainstorming.",
   "author": {
     "name": "wxm",
     "email": "18854896936@163.com",
@@ -14,6 +14,7 @@
     "games",
     "game-development",
     "studio-workflow",
+    "runtime-setup",
     "brainstorm",
     "gdd"
   ],
@@ -21,7 +22,7 @@
   "interface": {
     "displayName": "Codex Game Studios",
     "shortDescription": "Game-production workflows for Codex",
-    "longDescription": "Build a Codex game-production plugin step by step. The current workflow starts with /brainstorm, a guided concept ideation process that turns a rough idea into a structured game concept document.",
+    "longDescription": "Codex Game Studios exposes plugin-native skills for initializing game projects, installing bundled director agents, and guiding concept ideation into structured game design documentation.",
     "developerName": "wxm",
     "category": "Coding",
     "capabilities": [
@@ -33,7 +34,9 @@
     "privacyPolicyURL": "https://gitea.wuxianming.ac.cn/wxm/codex-game-studios",
     "termsOfServiceURL": "https://gitea.wuxianming.ac.cn/wxm/codex-game-studios",
     "defaultPrompt": [
-      "Run /brainstorm for my game project."
+      "Use $setup-runtime to initialize this game project.",
+      "Use $brainstorm to shape my game concept.",
+      "Use $using-codex-game-studios to explain the workflow."
     ],
     "brandColor": "#0F766E",
     "composerIcon": "./assets/codex-game-studio.svg",

.gitignore

@@ -1,4 +1,6 @@
 .env
+.env.*
 .DS_Store
 __pycache__/
 *.pyc
+plan.md

README.md

@@ -1,47 +1,47 @@
 # Codex Game Studios
 
-This repository is the minimal starting framework for a Codex plugin.
+Codex Game Studios is a Codex plugin for game-production workflows. It follows
+the normal plugin layout: `.codex-plugin/plugin.json` points to `./skills/`, and
+skills expose the runtime workflows directly. Do not use a global
+`~/.codex/skills/codex-game-studio` bridge as the plugin entry point.
 
-Current state:
+## Current State
 
-- Skills: `/brainstorm`
-- Codex custom agents: `creative-director`, `art-director`, `technical-director`, `producer`
-- Assets: `codex-game-studio.svg`
-- References: `director-gates.md`, `templates/game-concept.md`
-- Standards: `design-docs.md`
-- Commands: `/brainstorm` wrapper document
-- Scripts: `scripts/install_codex_runtime.py` installs bundled custom agents into a target project
+- Skills:
+  - `$using-codex-game-studios` explains the plugin workflow and entry points.
+  - `$setup-runtime` installs bundled director agents into a target game project.
+  - `$brainstorm` guides game concept ideation into `design/gdd/game-concept.md`.
+- Runtime agents: `creative-director`, `art-director`, `technical-director`, `producer`
+- Runtime source: `runtime/agents/`
+- References: `references/studio-docs/director-gates.md`, `references/studio-docs/templates/game-concept.md`
+- Standards: `standards/design-docs.md`
 - Marketplace: `.agents/plugins/marketplace.json`
-- No hooks
-- No rules
-- No MCP servers
-- No app integrations
+- No hooks, rules, MCP servers, or app integrations yet
 
-The director agents are pre-defined Codex custom agents stored in:
+## Runtime Setup
 
-```text
-.codex/agents/
-```
-
-Each custom agent is a standalone TOML file with `name`, `description`, and
-`developer_instructions`, matching the Codex subagents documentation.
-
-To install the bundled custom agents into a game project:
+To install the bundled custom agents into a game project, invoke `$setup-runtime`
+or run the installer directly:
 
 ```bash
-python3 scripts/install_codex_runtime.py /path/to/game-project
+python3 skills/setup-runtime/scripts/install_codex_runtime.py /path/to/game-project
 ```
 
-The current installer only writes custom agents to:
+The installer writes custom agents to:
 
 ```text
 /path/to/game-project/.codex/agents/
 ```
 
-The only required plugin manifest is:
+Each runtime agent is a standalone TOML file with `name`, `description`, and
+`developer_instructions`, matching Codex custom-agent conventions.
 
-```text
-.codex-plugin/plugin.json
+## Packaging Hygiene
+
+Only plugin source files should be packaged. `.git/`, `.env`, `.DS_Store`, local
+caches, and generated artifacts are not part of the plugin runtime. Run the
+validation script before publishing or refreshing an installed cache:
+
+```bash
+python3 scripts/validate_plugin.py
 ```
-
-Add plugin components one at a time so each addition can be reviewed, explained, and adjusted before the next component is introduced.

commands/brainstorm.md

@@ -1,15 +0,0 @@
-# /brainstorm
-
-Run the Brainstorm Codex Game Studio skill workflow.
-
-## Arguments
-
-Pass any text after `/brainstorm` as workflow input.
-
-## Workflow
-
-1. Use `../skills/brainstorm/SKILL.md` as the workflow entry point.
-2. Read `../skills/brainstorm/DETAILS.md` when present for the full procedure.
-3. Apply project guidance from `AGENTS.md` and relevant files in `../standards/` before changing project files.
-4. Use the pre-defined Codex custom agents in `../.codex/agents/<agent-name>.toml` when the skill delegates to a subagent.
-5. Return decisions, changes, blockers, verification, and next steps.

references/studio-docs/director-gates.md

@@ -19,10 +19,11 @@ Spawn `creative-director` via Codex custom-agent delegation using gate
 **CD-PILLARS** from `references/studio-docs/director-gates.md`.
 ```
 
-The matching custom agent must already be defined at
-`.codex/agents/<agent-name>.toml`. Pass the context listed under that gate's
-**Context to pass** field, then handle the verdict using the **Verdict
-handling** rules below.
+The matching custom agent must already be installed in the target project at
+`.codex/agents/<agent-name>.toml`. The plugin source copies for those agents live
+in `runtime/agents/`; run `$setup-runtime` if the target project is missing
+them. Pass the context listed under that gate's **Context to pass** field, then
+handle the verdict using the **Verdict handling** rules below.
 
 Director names are Codex custom agent names. Do not recreate them by pasting
 profile text into a generic default agent.
@@ -86,7 +87,7 @@ Apply the resolved mode:
 # Apply mode check, then:
 Spawn `[agent-name]` via Codex custom-agent delegation:
 - Gate: [GATE-ID] (see references/studio-docs/director-gates.md)
-- Custom agent file: .codex/agents/[agent-name].toml
+- Custom agent file: .codex/agents/[agent-name].toml in the target project
 - Context: [fields listed under that gate]
 - Codex fork_context: false unless full thread context is required
 - Await the verdict before proceeding.
@@ -110,7 +111,7 @@ All gates return one of three verdicts. Skills must handle all three:
 | Verdict | Meaning | Default action |
 |---------|---------|----------------|
 | **APPROVE / READY** | No issues. Proceed. | Continue the workflow |
-| **CONCERNS [list]** | Issues present but not blocking. | Surface to user via `ask the user in chat` — options: `Revise flagged items` / `Accept and proceed` / `Discuss further` |
+| **CONCERNS [list]** | Issues present but not blocking. | Surface to user via a structured prompt when available, or ask directly in chat: `Revise flagged items` / `Accept and proceed` / `Discuss further` |
 | **REJECT / NOT READY [blockers]** | Blocking issues. Do not proceed. | Surface blockers to user. Do not write files or advance stage until resolved. |
 
 **Escalation rule**: When multiple directors are spawned in parallel, apply the
@@ -133,7 +134,7 @@ For phase gates, record in `docs/architecture/architecture.md` or
 
 ## Tier 1 — Creative Director Gates
 
-Agent: `creative-director` | Custom agent file: `.codex/agents/creative-director.toml` | Domain: Vision, pillars, player experience
+Agent: `creative-director` | Target custom agent file: `.codex/agents/creative-director.toml` | Domain: Vision, pillars, player experience
 
 ---
 
@@ -275,7 +276,7 @@ any session that produces player feedback
 
 ## Tier 1 — Technical Director Gates
 
-Agent: `technical-director` | Custom agent file: `.codex/agents/technical-director.toml` | Domain: Architecture, engine risk, performance
+Agent: `technical-director` | Target custom agent file: `.codex/agents/technical-director.toml` | Domain: Architecture, engine risk, performance
 
 ---
 
@@ -421,7 +422,7 @@ or before finalizing any engine-specific implementation approach
 
 ## Tier 1 — Producer Gates
 
-Agent: `producer` | Custom agent file: `.codex/agents/producer.toml` | Domain: Scope, timeline, dependencies, production risk
+Agent: `producer` | Target custom agent file: `.codex/agents/producer.toml` | Domain: Scope, timeline, dependencies, production risk
 
 ---
 
@@ -547,7 +548,7 @@ is invoked
 
 ## Tier 1 — Art Director Gates
 
-Agent: `art-director` | Custom agent file: `.codex/agents/art-director.toml` | Domain: Visual identity, art bible, visual production readiness
+Agent: `art-director` | Target custom agent file: `.codex/agents/art-director.toml` | Domain: Visual identity, art bible, visual production readiness
 
 ---
 

scripts/validate_plugin.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Validate Codex Game Studios plugin structure and package hygiene."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+FORBIDDEN_NAMES = {".DS_Store", ".env", "plan.md"}
+FORBIDDEN_PARTS = {".git", "__pycache__"}
+REQUIRED_SKILLS = {
+    "brainstorm",
+    "setup-runtime",
+    "using-codex-game-studios",
+}
+REQUIRED_RUNTIME_AGENTS = {
+    "art-director.toml",
+    "creative-director.toml",
+    "producer.toml",
+    "technical-director.toml",
+}
+
+
+def fail(message: str) -> None:
+    print(f"ERROR: {message}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def run_git(args: list[str]) -> list[str]:
+    result = subprocess.run(
+        ["git", *args],
+        cwd=ROOT,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or "git command failed")
+    return [line for line in result.stdout.splitlines() if line]
+
+
+def assert_manifest() -> None:
+    manifest_path = ROOT / ".codex-plugin" / "plugin.json"
+    if not manifest_path.is_file():
+        fail("Missing .codex-plugin/plugin.json")
+
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if manifest.get("name") != "codex-game-studios":
+        fail("plugin.json name must be codex-game-studios")
+    if manifest.get("skills") != "./skills/":
+        fail('plugin.json must expose skills via "./skills/"')
+
+    for prompt in manifest.get("interface", {}).get("defaultPrompt", []):
+        if len(prompt) > 128:
+            fail(f"defaultPrompt exceeds 128 chars: {prompt}")
+
+
+def assert_skill(skill_name: str) -> None:
+    skill_dir = ROOT / "skills" / skill_name
+    skill_path = skill_dir / "SKILL.md"
+    agent_path = skill_dir / "agents" / "openai.yaml"
+
+    if not skill_path.is_file():
+        fail(f"Missing skill file: {skill_path.relative_to(ROOT)}")
+    if not agent_path.is_file():
+        fail(f"Missing skill UI metadata: {agent_path.relative_to(ROOT)}")
+
+    text = skill_path.read_text(encoding="utf-8")
+    if not text.startswith("---\n"):
+        fail(f"Missing YAML frontmatter: {skill_path.relative_to(ROOT)}")
+    if f"name: {skill_name}" not in text:
+        fail(f"Skill name mismatch in {skill_path.relative_to(ROOT)}")
+    if "description:" not in text.split("---", 2)[1]:
+        fail(f"Missing skill description in {skill_path.relative_to(ROOT)}")
+
+
+def assert_runtime_agents() -> None:
+    agent_dir = ROOT / "runtime" / "agents"
+    if not agent_dir.is_dir():
+        fail("Missing runtime/agents directory")
+
+    present = {path.name for path in agent_dir.glob("*.toml")}
+    missing = sorted(REQUIRED_RUNTIME_AGENTS - present)
+    if missing:
+        fail(f"Missing runtime agents: {', '.join(missing)}")
+
+
+def assert_package_hygiene() -> None:
+    try:
+        tracked = run_git(["ls-files"])
+        untracked = run_git(["ls-files", "--others", "--exclude-standard"])
+        candidates = tracked + untracked
+    except RuntimeError:
+        candidates = [
+            str(path.relative_to(ROOT))
+            for path in ROOT.rglob("*")
+            if path.is_file() or path.is_dir()
+        ]
+
+    bad: list[str] = []
+    for rel_path in candidates:
+        path = Path(rel_path)
+        if path.name in FORBIDDEN_NAMES or FORBIDDEN_PARTS.intersection(path.parts):
+            bad.append(rel_path)
+
+    if bad:
+        fail("Forbidden package candidates:\n- " + "\n- ".join(sorted(bad)))
+
+
+def main() -> int:
+    assert_manifest()
+    for skill_name in sorted(REQUIRED_SKILLS):
+        assert_skill(skill_name)
+    assert_runtime_agents()
+    assert_package_hygiene()
+    print("Codex Game Studios plugin validation passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

skills/brainstorm/DETAILS.md

@@ -11,9 +11,12 @@ When this skill is invoked:
 
    See `../../references/studio-docs/director-gates.md` for the full check pattern.
 
-   When a gate is active, spawn the named Codex custom agent that is already
-   defined in `../../.codex/agents/<agent-name>.toml`. Do not recreate the
-   director role by pasting profile text into a generic default agent.
+   Director agent source files live in `../../runtime/agents/`. Before running
+   any `full` review-mode gate, verify the target project has the matching
+   `.codex/agents/<agent-name>.toml` files installed. If they are missing, run
+   `$setup-runtime` for the project first. When a gate is active, spawn the
+   named Codex custom agent; do not recreate the director role by pasting
+   profile text into a generic default agent.
 
 2. **Check for existing concept work**:
    - Read `design/gdd/game-concept.md` if it exists (resume, don't restart)
@@ -24,13 +27,17 @@ When this skill is invoked:
    exploration** where the AI acts as a creative facilitator, not a replacement
    for the human's vision.
 
-   **Use `ask the user in chat`** at key decision points throughout brainstorming:
+   **Use a structured decision prompt when available** at key decision points
+   throughout brainstorming. In Codex, use the current user-input mechanism if
+   it is available in the active mode; otherwise ask the same question directly
+   in chat and wait for the user's reply.
    - Constrained taste questions (genre preferences, scope, team size)
    - Concept selection ("Which 2-3 concepts resonate?") after presenting options
    - Direction choices ("Develop further, explore more, or prototype?")
    - Pillar ranking after concepts are refined
    Write full creative analysis in conversation text first, then use
-   `ask the user in chat` to capture the decision with concise labels.
+   the structured prompt or chat question to capture the decision with concise
+   labels.
 
    Professional studio brainstorming principles to follow:
    - Withhold judgment — no idea is bad during exploration
@@ -55,18 +62,19 @@ conversationally (not as a checklist):
 **Taste profile**:
 - What 3 games have you spent the most time with? What kept you coming back?
   *(Ask this as plain text — the user must be able to type specific game names freely.
-  Do NOT put this in an ask the user in chat with preset options.)*
+  Do NOT put this in a structured prompt with preset options.)*
 - Are there genres you love? Genres you avoid? Why?
 - Do you prefer games that challenge you, relax you, tell you stories,
-  or let you express yourself? *(Use `ask the user in chat` for this — constrained choice.)*
+  or let you express yourself? *(Use a structured prompt for this when available — constrained choice.)*
 
 **Practical constraints** (shape the sandbox before brainstorming).
-Bundle these into a single multi-tab `ask the user in chat` with these exact tab labels:
+Bundle these into a single multi-field structured prompt when available:
 - Tab "Experience" — "What kind of experience do you most want players to have?" (Challenge & Mastery / Story & Discovery / Expression & Creativity / Relaxation & Flow)
 - Tab "Timeline" — "What's your realistic development timeline?" (Weeks / Months / 1-2 years / Multi-year)
 - Tab "Dev level" — "Where are you in your dev journey?" (First game / Shipped before / Professional background)
 
-Use exactly these tab names — do not rename or duplicate them.
+If the UI supports grouping fields, use exactly these group names. If not,
+ask the three questions one at a time.
 
 **Synthesize** the answers into a **Creative Brief** — a 3-5 sentence
 summary of the person's emotional goals, taste profile, and constraints.
@@ -104,12 +112,13 @@ For each concept, present:
 - **Why It Could Work** (1 sentence on market/audience fit)
 - **Biggest Risk** (1 sentence on the hardest unanswered question)
 
-Present all three. Then use `ask the user in chat` to capture the selection.
+Present all three. Then use a structured prompt or direct chat question to
+capture the selection.
 
-**CRITICAL**: This MUST be a plain list call — no tabs, no form fields. Use exactly this structure:
+**CRITICAL**: This MUST be a plain list choice, not a multi-field form. Use this structure:
 
 ```
-ask the user in chat(
+structured decision prompt(
   prompt: "Which concept resonates with you? You can pick one, combine elements, or ask for fresh directions.",
   options: [
     "Concept 1 — [Title]",
@@ -121,7 +130,7 @@ ask the user in chat(
 )
 ```
 
-Do NOT use a `tabs` field here. The `tabs` form is for multi-field input only — using it here causes an "Invalid tool parameters" error. This is a plain `prompt` + `options` call.
+Do NOT use a multi-field form here. This is a plain prompt plus options.
 
 Never pressure toward a choice — let them sit with it.
 
@@ -135,7 +144,7 @@ isolation, no amount of content or polish will save the game.
 
 **30-Second Loop** (moment-to-moment):
 
-Ask these as `ask the user in chat` calls — derive the options from the chosen concept, don't hardcode them:
+Ask these as structured prompts when available — derive the options from the chosen concept, don't hardcode them:
 
 1. **Core action feel** — prompt: "What's the primary feel of the core action?" Generate 3-4 options that fit the concept's genre and tone, plus a free-text escape (`I'll describe it`).
 
@@ -184,11 +193,11 @@ Then define **3+ anti-pillars** (what this game is NOT):
   be cool if..." features that don't serve the core vision
 - Frame as: "We will NOT do [thing] because it would compromise [pillar]"
 
-**Pillar confirmation**: After presenting the full pillar set, use `ask the user in chat`:
+**Pillar confirmation**: After presenting the full pillar set, use a structured prompt:
 - Prompt: "Do these pillars feel right for your game?"
 - Options: `[A] Lock these in` / `[B] Rename or reframe one` / `[C] Swap a pillar out` / `[D] Something else`
 
-If the user selects B, C, or D, make the revision, then use `ask the user in chat` again:
+If the user selects B, C, or D, make the revision, then use a structured prompt again:
 - Prompt: "Pillars updated. Ready to lock these in?"
 - Options: `[A] Lock these in` / `[B] Revise another pillar` / `[C] Something else`
 
@@ -207,7 +216,7 @@ Repeat until the user selects [A] Lock these in.
 - **`art-director`** — gate **AD-CONCEPT-VISUAL** (`../../references/studio-docs/director-gates.md`)
   Pass: game concept elevator pitch, full pillar set with design tests, target platform (if known), any reference games or visual touchstones the user mentioned.
 
-Collect both verdicts, then present them together using a two-tab `ask the user in chat`:
+Collect both verdicts, then present them together using a structured prompt:
 - Tab **"Pillars"**: present creative-director feedback. Options mirror the standard CD-PILLARS handling — `Lock in as-is` / `Revise [specific pillar]` / `Discuss further`.
 - Tab **"Visual anchor"**: present the art-director's 2-3 named visual direction options. Options: each named direction (one per option) + `Combine elements across directions` + `Describe my own direction`.
 
@@ -236,12 +245,12 @@ who this game is actually for:
 
 Ground the concept in reality:
 
-- **Target platform**: Use `ask the user in chat` — "What platforms are you targeting for this game?"
+- **Target platform**: Use a structured prompt when available — "What platforms are you targeting for this game?"
   Options: `PC (Steam / Epic)` / `Mobile (iOS / Android)` / `Console` / `Web / Browser` / `Multiple platforms`
   Record the answer — it directly shapes the engine recommendation and will be passed to `/setup-engine`.
   Note platform implications if relevant (e.g., mobile means Unity is strongly preferred; console means Godot has limitations; web means Godot exports cleanly).
 
-- **Engine experience**: Use `ask the user in chat` — "Do you already have an engine you work in?"
+- **Engine experience**: Use a structured prompt when available — "Do you already have an engine you work in?"
   Options: `Godot` / `Unity` / `Unreal Engine 5` / `No preference — help me decide`
   - If they pick an engine → record it as their preference and move on. Do NOT second-guess it.
   - If "No preference" → tell them: "Run `/setup-engine` after this session — it will walk you through the full decision based on your concept and platform target." Do not make a recommendation here.
@@ -290,13 +299,13 @@ Present the assessment to the user. If UNREALISTIC, offer to adjust the MVP defi
    This section is the seed of the art bible — it captures the "everything must
    move" decision before it can be forgotten between sessions.
 
-5. Use `ask the user in chat` for write approval:
+5. Use a structured prompt or direct chat question for write approval:
 - Prompt: "Game concept is ready. May I write it to `design/gdd/game-concept.md`?"
 - Options: `[A] Yes — write it` / `[B] Not yet — revise a section first`
 
-If [B]: ask which section to revise using `ask the user in chat` with options: `Elevator Pitch` / `Core Fantasy & Unique Hook` / `Pillars` / `Core Loop` / `MVP Definition` / `Scope Tiers` / `Risks` / `Something else — I'll describe`
+If [B]: ask which section to revise using a structured prompt with options: `Elevator Pitch` / `Core Fantasy & Unique Hook` / `Pillars` / `Core Loop` / `MVP Definition` / `Scope Tiers` / `Risks` / `Something else — I'll describe`
 
-After revising, show the updated section as a diff or clear before/after, then use `ask the user in chat` — "Ready to write the updated concept document?"
+After revising, show the updated section as a diff or clear before/after, then ask — "Ready to write the updated concept document?"
 Options: `[A] Yes — write it` / `[B] Revise another section`
 Repeat until the user selects [A].
 

skills/brainstorm/SKILL.md

@@ -5,6 +5,8 @@ description: "Use when you need the /brainstorm game-production workflow. Guided
 
 # Brainstorm
 
-Run the `/brainstorm` Codex Game Studio workflow.
+Run the Codex Game Studios brainstorm workflow.
 
-Before acting, read `DETAILS.md` for the full workflow. Apply project guidance from `AGENTS.md`, use `../../standards/` for path-specific standards, and use the pre-defined Codex custom agents in `../../.codex/agents/<agent-name>.toml` when the workflow delegates to a subagent.
+Before acting, read `DETAILS.md` for the full workflow. Apply project guidance from `AGENTS.md` and use `../../standards/` for path-specific standards.
+
+Director gates use the bundled custom agents from `../../runtime/agents/`. If the current project does not already have those agents installed in `.codex/agents/`, run `$setup-runtime` first.

skills/brainstorm/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Brainstorm"
-  short_description: "Use when you need the /brainstorm game-production workflow. Guided game concept ideation — from zero idea to a structure"
-  default_prompt: "Run /brainstorm for my game project."
+  short_description: "Shape a game idea into a concept doc"
+  default_prompt: "Use $brainstorm to shape my game concept."

skills/setup-runtime/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: setup-runtime
+description: "Use when a user asks to initialize, install, or refresh the Codex Game Studios runtime in a game project. Installs bundled director custom agents into the target project's .codex/agents directory."
+---
+
+# Setup Runtime
+
+Install the Codex Game Studios runtime assets into the current game project.
+
+## Workflow
+
+1. Treat the current working directory as the target project unless the user names another path.
+2. Run `scripts/install_codex_runtime.py <target-project>`.
+3. Report installed, unchanged, and conflicting agent files.
+4. If conflicts are reported, do not overwrite them unless the user explicitly asks for `--force`.
+
+The installer copies runtime agents from the plugin's `runtime/agents/` directory to:
+
+```text
+<target-project>/.codex/agents/
+```
+
+The runtime currently contains only Codex custom-agent TOML files. It does not install hooks, rules, MCP servers, apps, or project templates.

skills/setup-runtime/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Setup Runtime"
+  short_description: "Install game-studio agents into a project"
+  default_prompt: "Use $setup-runtime to initialize this game project."

skills/setup-runtime/scripts/install_codex_runtime.py

@@ -2,7 +2,7 @@
 """Install Codex Game Studios runtime files into a game project.
 
 Current runtime scope:
-- Copy bundled Codex custom agents from this plugin's `.codex/agents/`
+- Copy bundled Codex custom agents from this plugin's `runtime/agents/`
   directory into the target project's `.codex/agents/` directory.
 
 This installer intentionally does not install hooks, rules, MCP servers, apps,
@@ -19,8 +19,18 @@ from dataclasses import dataclass
 from pathlib import Path
 
 
-PLUGIN_ROOT = Path(__file__).resolve().parents[1]
-SOURCE_AGENTS_DIR = PLUGIN_ROOT / ".codex" / "agents"
+def find_plugin_root(start: Path) -> Path:
+    """Walk upward until the Codex plugin manifest is found."""
+    for candidate in [start, *start.parents]:
+        if (candidate / ".codex-plugin" / "plugin.json").is_file():
+            return candidate
+    raise FileNotFoundError(
+        f"Could not find .codex-plugin/plugin.json above: {start}"
+    )
+
+
+PLUGIN_ROOT = find_plugin_root(Path(__file__).resolve())
+SOURCE_AGENTS_DIR = PLUGIN_ROOT / "runtime" / "agents"
 
 
 @dataclass(frozen=True)

skills/using-codex-game-studios/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: using-codex-game-studios
+description: "Use when a user asks how the Codex Game Studios plugin is structured, what workflow to run next, how to initialize it, or how it differs from generic development workflow plugins."
+---
+
+# Using Codex Game Studios
+
+Codex Game Studios is a game-production plugin built around plugin-discovered skills, not global `~/.codex/skills` bridge folders.
+
+## Entry Points
+
+- Use `$setup-runtime` when a project needs the bundled director agents installed into `.codex/agents/`.
+- Use `$brainstorm` to turn a rough game idea into `design/gdd/game-concept.md`.
+- Use `runtime/agents/` as the plugin source of bundled custom agents.
+- Use `references/` and `standards/` only when the active workflow points to them.
+
+## Design Rule
+
+Do not rely on a global `~/.codex/skills/codex-game-studio` bridge. The installed plugin exposes its skills through `.codex-plugin/plugin.json` with `"skills": "./skills/"`, matching the normal Codex plugin layout.

skills/using-codex-game-studios/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Using Codex Game Studios"
+  short_description: "Understand the game-studio plugin workflow"
+  default_prompt: "Use $using-codex-game-studios to explain this plugin workflow."