docs: clarify installation and first use

README.ja.md

@@ -25,22 +25,38 @@ Explain how an AI agent code sandbox works in 3D.
 
 ## インストール
 
-スキルを一つ選んでグローバルにインストールします。
+`npx skills` でインストールするには、**Node.js 22.20 以降**（npm と `npx` を含む）、**Git**、利用する Claude Code または Codex が必要です。まずターミナルで確認してください。
 
 ```sh
-npx skills add codekongdev/plz --skill plz-3d-explain -g
+node --version
+npm --version
+git --version
 ```
 
-<details>
-<summary>Codex</summary>
+利用するエージェントに対応するコマンドを実行します。以下は `plz-3d-explain` をグローバルにインストールし、複数のプロジェクトで使えるようにするコマンドです。
 
-Codex で使う場合は `-a codex` を指定します。次のコマンドは、現在のプロジェクトの `.agents/skills/` にインストールします。
+Claude Code:
 
 ```sh
-npx skills add codekongdev/plz --skill plz-3d-explain -a codex
+npx skills add codekongdev/plz --skill plz-3d-explain -a claude-code -g
 ```
 
-</details>
+Codex:
+
+```sh
+npx skills add codekongdev/plz --skill plz-3d-explain -a codex -g
+```
+
+一つのプロジェクトだけにインストールする場合は、そのプロジェクトのディレクトリで上のコマンドから `-g` を外して実行します。Claude Code は `.claude/skills/`、Codex は `.agents/skills/` を使用します。インストーラーが確認を求めたら、案内に従ってください。
+
+利用するエージェントのインストール済みスキルを確認します。
+
+```sh
+npx skills list -g -a claude-code
+npx skills list -g -a codex
+```
+
+対応する一覧に `plz-3d-explain` があればインストールできています。プロジェクトだけにインストールした場合は、同じプロジェクトのディレクトリで一覧コマンドからも `-g` を外してください。
 
 <details>
 <summary>スキルの一覧表示、すべてインストール</summary>
@@ -51,7 +67,7 @@ npx skills add codekongdev/plz --skill plz-3d-explain -a codex
 npx skills add codekongdev/plz -l
 ```
 
-すべてのスキルをグローバルにインストールします。
+すべてのスキルをグローバルにインストールします。エージェントの選択を求められたら、利用するツールを選んでください。
 
 ```sh
 npx skills add codekongdev/plz --skill '*' -g
@@ -76,13 +92,20 @@ cp -R plz/skills/plz-3d-explain ~/.claude/skills/plz-3d-explain
 
 ## 使い方
 
-インストールしたら、普段の言葉でエージェントに頼むだけです。
+ページを作成するプロジェクトで、エージェントの新しいセッションを開始します。スキルを明示して依頼できます。
+
+- **Claude Code:** `/plz-3d-explain コンテナの分離がどのように働くのかを 3D で解説して。`
+- **Codex:** `$plz-3d-explain コンテナの分離がどのように働くのかを 3D で解説して。`
+
+普段の言葉で依頼することもできます。
 
 - 「コンテナの分離がどのように働くのかを 3D で解説して。」
 - 「TCP ハンドシェイクの流れを 3D モデルで見せて。」
 
 英語、韓国語、簡体字中国語で依頼することもでき、ページは依頼した言語で作成されます。
 
+スキルが見つからない場合は、上の一覧コマンドでエージェントとインストール範囲を確認し、新しいセッションを開始してください。プロジェクトだけにインストールしたスキルは、そのプロジェクトで使います。`npx` が見つからない場合や Node.js のバージョンエラーが出た場合は、上の要件を確認してください。
+
 ## 動作の流れ
 
 ページを依頼すると、`plz-3d-explain` は次の 4 ステップで作業します。
@@ -97,7 +120,9 @@ cp -R plz/skills/plz-3d-explain ~/.claude/skills/plz-3d-explain
 - **向いていること:** 技術的な概念、仕組み、システム構成を 3D モデルで学ぶこと。
 - **対象外:** 静的なアーキテクチャ図やシーケンス図、データのグラフ、Blender によるモデリング、製品のランディングページ、アプリの UI デザイン。
 - **ページを開くとき:** three.js r170 と Web フォントを CDN から読み込むため、インターネット接続が必要です。
-- **ページを作成するとき:** ローカルサーバーと Playwright などのブラウザ自動化ツールによる検証を含みます。
+- **ページを作成するとき:** ローカル HTTP サーバー（スキルの例では Python 3）と、エージェントが使える Playwright などのブラウザ自動化ツールが必要です。
+
+スキルのインストールでは Python やブラウザ自動化ツールはインストールされません。ツールがない場合は、検証前にエージェントに準備を依頼してください。HTML が生成されてもブラウザ検証に合格したとは限らないため、結果の報告で実施した検証を確認してください。
 
 詳しくは[スキルの README](skills/plz-3d-explain/README.md)を参照してください。
 

README.ko.md

@@ -25,22 +25,38 @@ Explain how an AI agent code sandbox works in 3D.
 
 ## 설치
 
-스킬 하나를 전역으로 설치:
+`npx skills`로 설치하려면 **Node.js 22.20 이상**(npm과 `npx` 포함), **Git**, 사용할 Claude Code 또는 Codex가 필요합니다. 터미널에서 먼저 확인하세요.
 
 ```sh
-npx skills add codekongdev/plz --skill plz-3d-explain -g
+node --version
+npm --version
+git --version
 ```
 
-<details>
-<summary>Codex</summary>
+사용할 에이전트에 맞는 명령을 실행합니다. 아래 명령은 `plz-3d-explain`을 전역으로 설치해 여러 프로젝트에서 쓸 수 있게 합니다.
 
-Codex에서 쓰려면 `-a codex`를 붙입니다. 아래 명령은 지금 프로젝트의 `.agents/skills/`에 설치합니다.
+Claude Code:
 
 ```sh
-npx skills add codekongdev/plz --skill plz-3d-explain -a codex
+npx skills add codekongdev/plz --skill plz-3d-explain -a claude-code -g
 ```
 
-</details>
+Codex:
+
+```sh
+npx skills add codekongdev/plz --skill plz-3d-explain -a codex -g
+```
+
+한 프로젝트에만 설치하려면 해당 프로젝트 폴더에서 위 명령의 `-g`를 빼고 실행하세요. Claude Code는 `.claude/skills/`, Codex는 `.agents/skills/`를 사용합니다. 설치 도구가 확인을 요청하면 안내에 따라 진행합니다.
+
+사용할 에이전트의 설치 목록을 확인합니다.
+
+```sh
+npx skills list -g -a claude-code
+npx skills list -g -a codex
+```
+
+해당 목록에 `plz-3d-explain`이 있으면 됩니다. 프로젝트에만 설치했다면 같은 프로젝트 폴더에서 목록 명령의 `-g`도 빼고 실행하세요.
 
 <details>
 <summary>스킬 목록 보기, 전체 설치</summary>
@@ -51,7 +67,7 @@ npx skills add codekongdev/plz --skill plz-3d-explain -a codex
 npx skills add codekongdev/plz -l
 ```
 
-모든 스킬을 전역으로 설치:
+모든 스킬을 전역으로 설치합니다. 에이전트 선택을 요청하면 사용할 도구를 고르세요.
 
 ```sh
 npx skills add codekongdev/plz --skill '*' -g
@@ -76,13 +92,20 @@ cp -R plz/skills/plz-3d-explain ~/.claude/skills/plz-3d-explain
 
 ## 사용법
 
-설치한 뒤에는 에이전트에게 평소 말투로 요청하면 됩니다.
+페이지를 만들 프로젝트에서 에이전트의 새 세션을 시작합니다. 스킬을 직접 지정해 요청할 수 있습니다.
+
+- **Claude Code:** `/plz-3d-explain 컨테이너 격리가 어떻게 동작하는지 3D로 설명해 줘.`
+- **Codex:** `$plz-3d-explain 컨테이너 격리가 어떻게 동작하는지 3D로 설명해 줘.`
+
+평소 말투로 요청해도 됩니다.
 
 - “컨테이너 격리가 어떻게 동작하는지 3D로 설명해 줘.”
 - “TCP 핸드셰이크가 어떻게 이뤄지는지 3D 모형으로 보여 줘.”
 
 영어, 일본어, 중국어 간체로 요청해도 되며, 페이지는 요청한 언어로 만들어집니다.
 
+스킬이 보이지 않으면 위 목록 명령으로 에이전트와 설치 범위를 확인한 뒤 새 세션을 시작하세요. 프로젝트에만 설치한 스킬은 설치한 프로젝트에서 사용해야 합니다. `npx`가 없거나 Node.js 버전 오류가 나오면 위 준비물을 확인하세요.
+
 ## 동작 방식
 
 페이지를 요청하면 `plz-3d-explain`은 네 단계로 작업합니다.
@@ -97,7 +120,9 @@ cp -R plz/skills/plz-3d-explain ~/.claude/skills/plz-3d-explain
 - **알맞은 경우:** 기술 개념, 동작 원리, 시스템 구조를 3D 모형으로 공부할 때 알맞습니다.
 - **대상이 아닌 것:** 정적 아키텍처·시퀀스 다이어그램, 데이터 차트, Blender 모델링, 제품 랜딩 페이지, 앱 UI 디자인.
 - **페이지를 열 때:** three.js r170과 웹폰트를 CDN에서 받으므로 인터넷 연결이 필요합니다.
-- **페이지를 만들 때:** 로컬 서버와 Playwright 같은 브라우저 자동화 도구로 검증하는 단계가 포함됩니다.
+- **페이지를 만들 때:** 로컬 HTTP 서버(스킬 예시는 Python 3)와 에이전트가 사용할 수 있는 Playwright 같은 브라우저 자동화 도구가 필요합니다.
+
+스킬 설치 명령이 Python이나 브라우저 자동화 도구까지 설치하지는 않습니다. 도구가 없다면 검증 전에 에이전트에게 준비를 요청하세요. HTML이 만들어졌다는 것만으로 브라우저 검증까지 통과한 것은 아니므로, 결과 보고에서 실제로 실행한 검증을 확인하세요.
 
 자세한 내용은 [스킬 README](skills/plz-3d-explain/README.md)를 참고해 주세요.
 

README.md

@@ -25,22 +25,38 @@ Explain how an AI agent code sandbox works in 3D.
 
 ## Install
 
-Install one skill globally:
+To install with `npx skills`, you need **Node.js 22.20 or later** (with npm and `npx`), **Git**, and a working Claude Code or Codex installation. Check the tools in your terminal:
 
 ```sh
-npx skills add codekongdev/plz --skill plz-3d-explain -g
+node --version
+npm --version
+git --version
 ```
 
-<details>
-<summary>Codex</summary>
+Choose your agent below. These commands install `plz-3d-explain` globally, so it is available across projects.
 
-For Codex, add `-a codex`. This command installs the skill into the current project's `.agents/skills/` directory:
+Claude Code:
 
 ```sh
-npx skills add codekongdev/plz --skill plz-3d-explain -a codex
+npx skills add codekongdev/plz --skill plz-3d-explain -a claude-code -g
 ```
 
-</details>
+Codex:
+
+```sh
+npx skills add codekongdev/plz --skill plz-3d-explain -a codex -g
+```
+
+For a project-only installation, run the matching command from that project's directory and omit `-g`. Claude Code uses `.claude/skills/`; Codex uses `.agents/skills/`. Follow any confirmation prompts from the installer.
+
+Confirm the installation for your agent:
+
+```sh
+npx skills list -g -a claude-code
+npx skills list -g -a codex
+```
+
+Look for `plz-3d-explain` in the matching list. For a project-only installation, run the list command from the same project and omit `-g` too.
 
 <details>
 <summary>List or install all skills</summary>
@@ -51,7 +67,7 @@ List available skills:
 npx skills add codekongdev/plz -l
 ```
 
-Install all skills globally:
+Install all skills globally, choosing the agent when prompted:
 
 ```sh
 npx skills add codekongdev/plz --skill '*' -g
@@ -76,13 +92,20 @@ See [plz-3d-explain on skills.sh](https://skills.sh/codekongdev/plz/plz-3d-expla
 
 ## Usage
 
-After installing, ask your agent in plain language:
+Start a new agent session in the project where you want to create the page. To use the skill explicitly:
+
+- **Claude Code:** `/plz-3d-explain Explain how container isolation works in 3D.`
+- **Codex:** `$plz-3d-explain Explain how container isolation works in 3D.`
+
+You can also ask in plain language:
 
 - “Explain how container isolation works in 3D.”
 - “Show how a TCP handshake works as a 3D model.”
 
 You can also ask in Korean, Japanese, or Simplified Chinese; the page is written in the language you ask in.
 
+If the skill is not available, check the agent and installation scope with the list commands above, then start a new session. Project-only skills must be used from the project where you installed them. If `npx` is missing or reports an unsupported Node.js version, check the prerequisites above.
+
 ## How it works
 
 When you ask for a page, `plz-3d-explain` works in four steps:
@@ -97,7 +120,9 @@ When you ask for a page, `plz-3d-explain` works in four steps:
 - **Good for:** learning a technical concept, mechanism, or system structure with a 3D model.
 - **Out of scope:** static architecture or sequence diagrams, data charts, Blender modeling, product landing pages, and app UI design.
 - **Opening a page:** needs an internet connection, because three.js r170 and web fonts load from CDNs.
-- **Creating a page:** includes validation with a local server and browser automation such as Playwright.
+- **Creating a page:** requires a local HTTP server (the skill uses Python 3 as an example) and a browser automation tool the agent can use, such as Playwright.
+
+Installing the skill does not install Python or browser automation. If these tools are unavailable, ask your agent to help prepare them before validation. A generated HTML file alone does not mean browser validation passed; check the agent’s report for what it actually tested.
 
 Details are in the [skill README](skills/plz-3d-explain/README.md).
 

README.zh-CN.md

@@ -25,22 +25,38 @@ Explain how an AI agent code sandbox works in 3D.
 
 ## 安装
 
-全局安装一个技能：
+使用 `npx skills` 安装时，需要 **Node.js 22.20 或更高版本**（包含 npm 和 `npx`）、**Git**，以及已配置好的 Claude Code 或 Codex。先在终端中检查：
 
 ```sh
-npx skills add codekongdev/plz --skill plz-3d-explain -g
+node --version
+npm --version
+git --version
 ```
 
-<details>
-<summary>Codex</summary>
+执行与你使用的代理对应的命令。以下命令会全局安装 `plz-3d-explain`，供多个项目使用。
 
-在 Codex 中使用时，加上 `-a codex`。以下命令会将技能安装到当前项目的 `.agents/skills/` 目录：
+Claude Code:
 
 ```sh
-npx skills add codekongdev/plz --skill plz-3d-explain -a codex
+npx skills add codekongdev/plz --skill plz-3d-explain -a claude-code -g
 ```
 
-</details>
+Codex:
+
+```sh
+npx skills add codekongdev/plz --skill plz-3d-explain -a codex -g
+```
+
+如果只想在一个项目中安装，请在该项目目录中执行对应命令，并去掉 `-g`。Claude Code 使用 `.claude/skills/`，Codex 使用 `.agents/skills/`。如果安装工具要求确认，请按提示操作。
+
+检查所用代理的已安装技能列表：
+
+```sh
+npx skills list -g -a claude-code
+npx skills list -g -a codex
+```
+
+在对应列表中找到 `plz-3d-explain` 即可。如果只安装到了项目中，请在同一项目目录中执行列表命令，并同样去掉 `-g`。
 
 <details>
 <summary>查看技能列表或安装全部技能</summary>
@@ -51,7 +67,7 @@ npx skills add codekongdev/plz --skill plz-3d-explain -a codex
 npx skills add codekongdev/plz -l
 ```
 
-全局安装所有技能：
+全局安装所有技能。如果提示选择代理，请选择你使用的工具。
 
 ```sh
 npx skills add codekongdev/plz --skill '*' -g
@@ -76,13 +92,20 @@ cp -R plz/skills/plz-3d-explain ~/.claude/skills/plz-3d-explain
 
 ## 使用方法
 
-安装完成后，直接用日常语言向代理提出需求即可：
+在需要创建页面的项目中，启动代理的新会话。可以明确指定技能：
+
+- **Claude Code:** `/plz-3d-explain 用 3D 讲解容器隔离是如何工作的。`
+- **Codex:** `$plz-3d-explain 用 3D 讲解容器隔离是如何工作的。`
+
+也可以直接用日常语言提出需求：
 
 - “用 3D 讲解容器隔离是如何工作的。”
 - “用 3D 模型演示 TCP 握手的过程。”
 
 也可以用英语、韩语或日语提出需求，页面会使用你提问的语言编写。
 
+如果找不到技能，请用上面的列表命令检查代理和安装范围，再启动新会话。仅安装到项目中的技能需要在该项目中使用。如果找不到 `npx` 或出现 Node.js 版本错误，请检查上面的环境要求。
+
 ## 工作流程
 
 请求生成页面后，`plz-3d-explain` 分四步完成：
@@ -97,7 +120,9 @@ cp -R plz/skills/plz-3d-explain ~/.claude/skills/plz-3d-explain
 - **适用于：** 通过 3D 模型学习技术概念、运行机制或系统结构。
 - **不适用于：** 静态架构图或时序图、数据图表、Blender 建模、产品落地页和应用 UI 设计。
 - **打开页面时：** 页面通过 CDN 加载 three.js r170 和 Web 字体，因此需要联网。
-- **制作页面时：** 包含使用本地服务器和 Playwright 等浏览器自动化工具进行的验证。
+- **制作页面时：** 需要本地 HTTP 服务器（技能中的示例使用 Python 3）以及代理可用的浏览器自动化工具，例如 Playwright。
+
+安装技能不会同时安装 Python 或浏览器自动化工具。如果缺少这些工具，请在验证前让代理协助准备。生成 HTML 文件并不代表已通过浏览器验证，请查看代理报告中实际执行的检查。
 
 详情请参阅[技能 README](skills/plz-3d-explain/README.md)。