スキルの一覧表示、すべてインストール
@@ -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)を参照してください。 diff --git a/README.ko.md b/README.ko.md index c45c63b..d4bb0f8 100644 --- a/README.ko.md +++ b/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 ``` -
-
+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`도 빼고 실행하세요.
Codex
+사용할 에이전트에 맞는 명령을 실행합니다. 아래 명령은 `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 ``` -스킬 목록 보기, 전체 설치
@@ -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)를 참고해 주세요. diff --git a/README.md b/README.md index d147373..f7b4f94 100644 --- a/README.md +++ b/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 ``` -
-
+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.
Codex
+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 ``` -List or install all skills
@@ -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). diff --git a/README.zh-CN.md b/README.zh-CN.md index a0ae90f..af232f1 100644 --- a/README.zh-CN.md +++ b/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 ``` -
-
+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`。
Codex
+执行与你使用的代理对应的命令。以下命令会全局安装 `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 ``` -查看技能列表或安装全部技能
@@ -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)。 diff --git a/skills/plz-3d-explain/README.ja.md b/skills/plz-3d-explain/README.ja.md index 4db3856..6571f66 100644 --- a/skills/plz-3d-explain/README.ja.md +++ b/skills/plz-3d-explain/README.ja.md @@ -11,24 +11,45 @@
-AI エージェントのコードサンドボックスのデモを[英語](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.en.html)または[韓国語](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.html)でブラウザから開けます。コンテナ、microVM、WASM、OS サンドボックスによる隔離の仕組みを全10章で解説しています。サンプル HTML（[英語](assets/example-agent-sandbox.en.html)、[韓国語](assets/example-agent-sandbox.html)）もリポジトリに含まれています。codekongdev による [plz](../../README.md) シリーズのスキルです。
+AI エージェントのコードサンドボックスのデモを[英語](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.en.html)または[韓国語](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.html)でブラウザから開けます。コンテナ、microVM、WASM、OS サンドボックスによる隔離の仕組みを全10章で解説しています。サンプル HTML（[英語](assets/example-agent-sandbox.en.html)、[韓国語](assets/example-agent-sandbox.html)）もリポジトリに含まれています。codekongdev による [plz](https://github.com/codekongdev/plz) シリーズのスキルです。
-[](../../LICENSE)  
+[](https://github.com/codekongdev/plz/blob/main/LICENSE)  
## インストール
-グローバルにインストールします。
+`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
```
-Codex で使う場合は `-a codex` を指定します。次のコマンドは、現在のプロジェクトの `.agents/skills/` にインストールします。
+利用するエージェントのコマンドを選んでください。`-g` でグローバルにインストールすると、複数のプロジェクトで使えます。
+
+Claude Code:
+
+```sh
+npx skills add codekongdev/plz --skill plz-3d-explain -a claude-code -g
+```
+
+Codex:
+
+```sh
+npx skills add codekongdev/plz --skill plz-3d-explain -a codex -g
+```
+
+現在のプロジェクトだけで使う場合は、そのプロジェクトのディレクトリで上記コマンドから `-g` を外して実行します。インストーラーは `.agents/skills/` にスキルを保存し、Claude Code を選んだ場合はリンクも作成します。
+
+利用するエージェントのインストール一覧に `plz-3d-explain` が表示されることを確認します。
```sh
-npx skills add codekongdev/plz --skill plz-3d-explain -a codex
+npx skills list -g -a claude-code
+npx skills list -g -a codex
```
+プロジェクトにインストールした場合は、確認コマンドでも `-g` を外し、同じプロジェクトで実行します。一覧にない場合は、選択したエージェントとインストール範囲を確認してください。一覧にあってもエージェントが認識しない場合は、利用するプロジェクトで新しいエージェントセッションを開始します。
+
Claude Code に手動でインストールする場合は、リポジトリを clone し、`skills/plz-3d-explain` を `~/.claude/skills/plz-3d-explain` にコピーするか、シンボリックリンクを作成します。コピーする場合のコマンドは次のとおりです。
```sh
@@ -41,7 +62,12 @@ cp -R plz/skills/plz-3d-explain ~/.claude/skills/plz-3d-explain
## 使い方
-学びたいテーマや調べたいリポジトリを添えて、エージェントに依頼します。[SKILL.md](SKILL.md) に記載された起動フレーズを使った例です。
+インストール後、プロジェクトでエージェントを開き、スキルを指定して依頼します。
+
+- Claude Code: `/plz-3d-explain コンテナの隔離を 3D で説明して。`
+- Codex: `$plz-3d-explain コンテナの隔離を 3D で説明して。`
+
+[SKILL.md](SKILL.md) の起動フレーズを使い、普段の言葉で依頼することもできます。
- 「コンテナと仮想マシンの違いを 3D で説明して。」
- 「HTTP リクエストがサーバーを経由して外部 API に届く仕組みを、3D モデルで見せて。」
@@ -64,7 +90,9 @@ cp -R plz/skills/plz-3d-explain ~/.claude/skills/plz-3d-explain
出力はビルド不要の単一 HTML ファイルです。three.js r170 と Web フォントを CDN から読み込むため、ページを開く際はインターネット接続が必要です。
-ページ作成時の検証には、ローカルサーバーと Playwright などのブラウザ自動化ツールを使います。コンソールエラー、ラベルの重なりやはみ出し、横方向のスクロール、自動再生、タッチ操作を確認します。手順は [SKILL.md](SKILL.md)、検証用フックは[エンジン API](references/engine-api.md)、よくある問題は[注意点](references/gotchas.md)を参照してください。
+検証にはローカル HTTP サーバー（スキルの例では Python 3 を使用）と、エージェントから操作できる Playwright などのブラウザ自動化ツールが必要です。`npx skills` はスキルファイルのみをインストールし、これらのツールはインストールしません。利用できない場合はエージェントに準備を依頼し、実行できなかった検証項目を結果に明記してもらってください。
+
+コンソールエラー、ラベルの重なりやはみ出し、横方向のスクロール、自動再生、タッチ操作を確認します。手順は [SKILL.md](SKILL.md)、検証用フックは[エンジン API](references/engine-api.md)、よくある問題は[注意点](references/gotchas.md)を参照してください。
スマートフォンではモデルを左右にのみ回転できます。ステージ上を縦にスワイプするとページがスクロールし、横にスワイプするとモデルが回転します。上下への傾き変更やズームには対応していません。
@@ -84,10 +112,10 @@ cp references/preferences.example.md references/preferences.md
## コントリビュート
-コントリビュートや翻訳を歓迎します。詳しくは [CONTRIBUTING.md](../../CONTRIBUTING.md) を参照してください。
+コントリビュートや翻訳を歓迎します。詳しくは [CONTRIBUTING.md](https://github.com/codekongdev/plz/blob/main/CONTRIBUTING.md) を参照してください。
## ライセンス
-[MIT](../../LICENSE)。
+[MIT](https://github.com/codekongdev/plz/blob/main/LICENSE)。
CDN から読み込む外部リソースの three.js（MIT）と、Pretendard・Hahmlet・IBM Plex フォント（SIL OFL）は、このリポジトリには同梱していません。
diff --git a/skills/plz-3d-explain/README.ko.md b/skills/plz-3d-explain/README.ko.md
index 5ed73b4..8410149 100644
--- a/skills/plz-3d-explain/README.ko.md
+++ b/skills/plz-3d-explain/README.ko.md
@@ -11,24 +11,45 @@
-AI 에이전트 코드 샌드박스 데모를 [한국어](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.html)나 [영어](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.en.html)로 브라우저에서 바로 열어 볼 수 있습니다. 컨테이너, 마이크로VM, WASM, OS 샌드박스의 격리 방식을 10장으로 설명합니다. 예제 HTML([한국어](assets/example-agent-sandbox.html), [영어](assets/example-agent-sandbox.en.html))도 저장소에 있습니다. codekongdev(코드콩)가 만드는 [plz](../../README.md) 시리즈의 스킬입니다.
+AI 에이전트 코드 샌드박스 데모를 [한국어](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.html)나 [영어](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.en.html)로 브라우저에서 바로 열어 볼 수 있습니다. 컨테이너, 마이크로VM, WASM, OS 샌드박스의 격리 방식을 10장으로 설명합니다. 예제 HTML([한국어](assets/example-agent-sandbox.html), [영어](assets/example-agent-sandbox.en.html))도 저장소에 있습니다. codekongdev(코드콩)가 만드는 [plz](https://github.com/codekongdev/plz) 시리즈의 스킬입니다.
-[](../../LICENSE)  
+[](https://github.com/codekongdev/plz/blob/main/LICENSE)  
## 설치
-전역으로 설치합니다.
+`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
```
-Codex에서 쓰려면 `-a codex`를 붙입니다. 아래 명령은 지금 프로젝트의 `.agents/skills/`에 설치합니다.
+사용할 에이전트의 명령을 선택하세요. `-g`로 전역 설치하면 여러 프로젝트에서 사용할 수 있습니다.
+
+Claude Code:
+
+```sh
+npx skills add codekongdev/plz --skill plz-3d-explain -a claude-code -g
+```
+
+Codex:
+
+```sh
+npx skills add codekongdev/plz --skill plz-3d-explain -a codex -g
+```
+
+현재 프로젝트에서만 쓰려면 해당 프로젝트 폴더에서 위 명령의 `-g`를 빼고 실행합니다. 설치 도구는 `.agents/skills/`에 스킬을 저장하고, Claude Code를 선택하면 연결도 만듭니다.
+
+사용할 에이전트의 설치 목록에 `plz-3d-explain`이 표시되는지 확인합니다.
```sh
-npx skills add codekongdev/plz --skill plz-3d-explain -a codex
+npx skills list -g -a claude-code
+npx skills list -g -a codex
```
+프로젝트에 설치했다면 확인 명령에서도 `-g`를 빼고 같은 프로젝트에서 실행합니다. 목록에 없다면 선택한 에이전트와 설치 범위를 확인하세요. 목록에 있지만 에이전트에서 인식하지 못한다면 사용할 프로젝트에서 새 에이전트 세션을 시작합니다.
+
Claude Code에 수동으로 설치하려면 저장소를 내려받은 뒤 `skills/plz-3d-explain` 폴더를 `~/.claude/skills/plz-3d-explain`에 복사하거나 링크합니다. 복사하는 명령은 다음과 같습니다.
```sh
@@ -41,7 +62,12 @@ cp -R plz/skills/plz-3d-explain ~/.claude/skills/plz-3d-explain
## 쓰는 법
-에이전트에게 공부할 주제나 살펴볼 저장소를 함께 적어 요청합니다. [SKILL.md](SKILL.md)의 트리거 문구를 쓴 예시입니다.
+설치한 뒤 프로젝트에서 에이전트를 열고 스킬을 직접 지정해 요청합니다.
+
+- Claude Code: `/plz-3d-explain 컨테이너 격리를 3D로 설명해 줘.`
+- Codex: `$plz-3d-explain 컨테이너 격리를 3D로 설명해 줘.`
+
+[SKILL.md](SKILL.md)의 트리거 문구로 평소처럼 요청해도 됩니다.
- “컨테이너와 가상 머신의 차이를 3D로 공부하게 만들어줘.”
- “HTTP 요청이 서버를 거쳐 외부 API로 가는 원리를 모형으로 보여줘.”
@@ -64,7 +90,9 @@ cp -R plz/skills/plz-3d-explain ~/.claude/skills/plz-3d-explain
결과물은 빌드가 필요 없는 단일 HTML입니다. three.js r170과 웹폰트를 CDN에서 받으므로 페이지를 열 때 인터넷이 필요합니다.
-페이지 제작의 검증 단계에서는 로컬 서버와 Playwright 같은 브라우저 자동화 도구를 씁니다. 콘솔 오류, 라벨 겹침·잘림, 가로 스크롤, 자동 실행과 터치 조작을 확인합니다. 검증 방법은 [SKILL.md](SKILL.md), 검증 훅은 [엔진 API](references/engine-api.md), 자주 생기는 문제는 [함정](references/gotchas.md)에 정리돼 있습니다.
+검증에는 로컬 HTTP 서버(스킬 예시는 Python 3 사용)와 에이전트가 사용할 수 있는 Playwright 같은 브라우저 자동화 도구가 필요합니다. `npx skills`는 스킬 파일만 설치하며 이 도구들을 함께 설치하지 않습니다. 도구가 없다면 에이전트에게 준비를 요청하고, 실행하지 못한 검사는 검증 결과에서 구분해 달라고 하세요.
+
+콘솔 오류, 라벨 겹침·잘림, 가로 스크롤, 자동 실행과 터치 조작을 확인합니다. 검증 방법은 [SKILL.md](SKILL.md), 검증 훅은 [엔진 API](references/engine-api.md), 자주 생기는 문제는 [함정](references/gotchas.md)에 정리돼 있습니다.
휴대폰에서는 모형을 좌우로만 돌립니다. 무대 위를 세로로 쓸면 페이지가 스크롤되고, 가로로 밀면 모형이 돕니다. 위아래 기울이기와 확대는 지원하지 않습니다.
@@ -84,10 +112,10 @@ cp references/preferences.example.md references/preferences.md
## 기여
-기여와 번역을 환영합니다. 자세한 내용은 [CONTRIBUTING.md](../../CONTRIBUTING.md)를 참고해 주세요.
+기여와 번역을 환영합니다. 자세한 내용은 [CONTRIBUTING.md](https://github.com/codekongdev/plz/blob/main/CONTRIBUTING.md)를 참고해 주세요.
## 라이선스
-[MIT](../../LICENSE).
+[MIT](https://github.com/codekongdev/plz/blob/main/LICENSE).
페이지가 CDN에서 불러오는 외부 자원인 three.js(MIT)와 글꼴 Pretendard·Hahmlet·IBM Plex(SIL OFL)는 저장소에 포함하지 않습니다.
diff --git a/skills/plz-3d-explain/README.md b/skills/plz-3d-explain/README.md
index e162b90..7ee3fd3 100644
--- a/skills/plz-3d-explain/README.md
+++ b/skills/plz-3d-explain/README.md
@@ -11,24 +11,45 @@ Mobile: chapter 8, OS sandboxing.
-Open the AI agent code sandbox demo in [English](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.en.html) or [Korean](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.html): ten chapters on isolation with containers, microVMs, WASM, and OS sandboxes. The example HTML files ([English](assets/example-agent-sandbox.en.html), [Korean](assets/example-agent-sandbox.html)) are also in the repository. This skill is part of [plz](../../README.md), by codekongdev.
+Open the AI agent code sandbox demo in [English](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.en.html) or [Korean](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.html): ten chapters on isolation with containers, microVMs, WASM, and OS sandboxes. The example HTML files ([English](assets/example-agent-sandbox.en.html), [Korean](assets/example-agent-sandbox.html)) are also in the repository. This skill is part of [plz](https://github.com/codekongdev/plz), by codekongdev.
-[](../../LICENSE)  
+[](https://github.com/codekongdev/plz/blob/main/LICENSE)  
## Install
-Install globally:
+To install with `npx skills`, you need Node.js 22.20 or later (with npm and `npx`), Git, and Claude Code or Codex. Check the command-line tools first:
```sh
-npx skills add codekongdev/plz --skill plz-3d-explain -g
+node --version
+npm --version
+git --version
```
-For Codex, add `-a codex`. This command installs the skill into the current project's `.agents/skills/` directory:
+Choose your agent below. `-g` installs the skill globally, so it is available across projects.
+
+Claude Code:
+
+```sh
+npx skills add codekongdev/plz --skill plz-3d-explain -a claude-code -g
+```
+
+Codex:
+
+```sh
+npx skills add codekongdev/plz --skill plz-3d-explain -a codex -g
+```
+
+For this project only, run the matching command from the project directory with `-g` omitted. The installer stores the skill in `.agents/skills/` and links it for Claude Code when selected.
+
+Check the installation for your agent; the list should include `plz-3d-explain`:
```sh
-npx skills add codekongdev/plz --skill plz-3d-explain -a codex
+npx skills list -g -a claude-code
+npx skills list -g -a codex
```
+For a project installation, omit `-g` from the check and run it in the same project. If the skill is missing, check the selected agent and installation scope. If it is listed but unavailable in your agent, start a new agent session from the intended project.
+
For a manual Claude Code installation, clone the repository, then copy or symlink `skills/plz-3d-explain` to `~/.claude/skills/plz-3d-explain`. To copy it:
```sh
@@ -41,7 +62,12 @@ See [plz-3d-explain on skills.sh](https://skills.sh/codekongdev/plz/plz-3d-expla
## Usage
-Ask your agent about a topic you want to learn or a repository you want to explore. These requests use the triggers described in [SKILL.md](SKILL.md):
+After installing, open your agent in the project and invoke the skill directly:
+
+- Claude Code: `/plz-3d-explain Explain container isolation in 3D.`
+- Codex: `$plz-3d-explain Explain container isolation in 3D.`
+
+You can also ask in plain language, using the triggers in [SKILL.md](SKILL.md):
- “Explain the difference between containers and virtual machines in 3D.”
- “Show me a 3D model of how an HTTP request goes through a server to an external API.”
@@ -64,7 +90,9 @@ The skill checks the material, plans the chapters, fills the [template](assets/t
The output is a single HTML file with no build step. It loads three.js r170 and web fonts from CDNs, so opening the page requires an internet connection.
-Creating a page includes validation with a local server and browser automation such as Playwright. Checks cover console errors, overlapping or clipped labels, horizontal overflow, autorun, and touch gestures. See [SKILL.md](SKILL.md) for the process, the [engine API](references/engine-api.md) for validation hooks, and [gotchas](references/gotchas.md) for common issues.
+The validation step needs a local HTTP server (the skill uses Python 3 in its example) and a browser automation tool the agent can use, such as Playwright. `npx skills` installs the skill files; it does not install these tools. If they are unavailable, ask your agent to prepare them before validating the page and to report any checks it could not run.
+
+Validation covers console errors, overlapping or clipped labels, horizontal overflow, autorun, and touch gestures. See [SKILL.md](SKILL.md) for the process, the [engine API](references/engine-api.md) for validation hooks, and [gotchas](references/gotchas.md) for common issues.
On mobile, models rotate horizontally only. A vertical swipe over the stage scrolls the page; a horizontal swipe rotates the model. Tilting and zooming are not supported.
@@ -84,10 +112,10 @@ Use the copied file to record fonts, colors, validation tools, the output locati
## Contributing
-Contributions and translations are welcome. See [CONTRIBUTING.md](../../CONTRIBUTING.md).
+Contributions and translations are welcome. See [CONTRIBUTING.md](https://github.com/codekongdev/plz/blob/main/CONTRIBUTING.md).
## License
-[MIT](../../LICENSE).
+[MIT](https://github.com/codekongdev/plz/blob/main/LICENSE).
The external resources loaded from CDNs—three.js (MIT) and the Pretendard, Hahmlet, and IBM Plex fonts (SIL OFL)—are not bundled in this repository.
diff --git a/skills/plz-3d-explain/README.zh-CN.md b/skills/plz-3d-explain/README.zh-CN.md
index c241d68..99a11d8 100644
--- a/skills/plz-3d-explain/README.zh-CN.md
+++ b/skills/plz-3d-explain/README.zh-CN.md
@@ -11,24 +11,45 @@
-可以直接在浏览器中打开 AI 代理代码沙箱演示的[英文版](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.en.html)或[韩文版](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.html)。演示共 10 章，介绍容器、microVM、WASM 和 OS 沙箱的隔离机制。仓库中也提供了示例 HTML（[英文版](assets/example-agent-sandbox.en.html)、[韩文版](assets/example-agent-sandbox.html)）。本技能属于 codekongdev 编写的 [plz](../../README.md) 系列。
+可以直接在浏览器中打开 AI 代理代码沙箱演示的[英文版](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.en.html)或[韩文版](https://codekongdev.github.io/plz/skills/plz-3d-explain/assets/example-agent-sandbox.html)。演示共 10 章，介绍容器、microVM、WASM 和 OS 沙箱的隔离机制。仓库中也提供了示例 HTML（[英文版](assets/example-agent-sandbox.en.html)、[韩文版](assets/example-agent-sandbox.html)）。本技能属于 codekongdev 编写的 [plz](https://github.com/codekongdev/plz) 系列。
-[](../../LICENSE)  
+[](https://github.com/codekongdev/plz/blob/main/LICENSE)  
## 安装
-全局安装：
+使用 `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
```
-在 Codex 中使用时，加上 `-a codex`。以下命令会将技能安装到当前项目的 `.agents/skills/` 目录：
+选择要使用的代理对应的命令。`-g` 表示全局安装，可在多个项目中使用。
+
+Claude Code:
+
+```sh
+npx skills add codekongdev/plz --skill plz-3d-explain -a claude-code -g
+```
+
+Codex:
+
+```sh
+npx skills add codekongdev/plz --skill plz-3d-explain -a codex -g
+```
+
+如果只在当前项目中使用，请在项目目录中运行上述命令并去掉 `-g`。安装工具会将技能保存到 `.agents/skills/`，选择 Claude Code 时还会创建链接。
+
+查看对应代理的已安装技能列表，确认其中包含 `plz-3d-explain`：
```sh
-npx skills add codekongdev/plz --skill plz-3d-explain -a codex
+npx skills list -g -a claude-code
+npx skills list -g -a codex
```
+如果安装在项目中，检查时也要去掉 `-g`，并在同一项目目录中运行。如果列表中没有该技能，请检查选择的代理和安装范围。如果列表中有但代理无法识别，请在目标项目中启动新的代理会话。
+
手动安装到 Claude Code 时，先克隆仓库，再将 `skills/plz-3d-explain` 复制或以符号链接的方式放到 `~/.claude/skills/plz-3d-explain`。复制命令如下：
```sh
@@ -41,7 +62,12 @@ cp -R plz/skills/plz-3d-explain ~/.claude/skills/plz-3d-explain
## 使用方法
-向代理说明想学习的主题，或提供想了解的仓库。以下示例使用了 [SKILL.md](SKILL.md) 中描述的触发方式：
+安装后，在项目中打开代理，直接指定技能发出请求：
+
+- Claude Code: `/plz-3d-explain 用 3D 讲解容器隔离。`
+- Codex: `$plz-3d-explain 用 3D 讲解容器隔离。`
+
+也可以使用 [SKILL.md](SKILL.md) 中的触发方式，用自然语言请求：
- “用 3D 讲解容器和虚拟机的区别。”
- “用 3D 模型展示 HTTP 请求如何经过服务器到达外部 API。”
@@ -64,7 +90,9 @@ cp -R plz/skills/plz-3d-explain ~/.claude/skills/plz-3d-explain
生成结果是单个 HTML 文件，无需构建。页面通过 CDN 加载 three.js r170 和 Web 字体，因此打开时需要联网。
-制作页面时，会使用本地服务器和 Playwright 等浏览器自动化工具进行验证，检查控制台错误、标签重叠或越界、横向滚动、自动播放和触摸操作。具体流程见 [SKILL.md](SKILL.md)，验证钩子见[引擎 API](references/engine-api.md)，常见问题见[注意事项](references/gotchas.md)。
+验证需要本地 HTTP 服务器（技能示例使用 Python 3）以及代理能够操作的浏览器自动化工具，例如 Playwright。`npx skills` 只安装技能文件，不会安装这些工具。如果工具不可用，请让代理先准备工具，并在结果中说明哪些检查未能执行。
+
+验证会检查控制台错误、标签重叠或越界、横向滚动、自动播放和触摸操作。具体流程见 [SKILL.md](SKILL.md)，验证钩子见[引擎 API](references/engine-api.md)，常见问题见[注意事项](references/gotchas.md)。
手机端只能左右旋转模型。在展示区内上下滑动会滚动页面，左右滑动会旋转模型。不支持上下倾斜或缩放。
@@ -84,10 +112,10 @@ cp references/preferences.example.md references/preferences.md
## 参与贡献
-欢迎贡献代码和翻译。详情请参阅 [CONTRIBUTING.md](../../CONTRIBUTING.md)。
+欢迎贡献代码和翻译。详情请参阅 [CONTRIBUTING.md](https://github.com/codekongdev/plz/blob/main/CONTRIBUTING.md)。
## 许可证
-[MIT](../../LICENSE)。
+[MIT](https://github.com/codekongdev/plz/blob/main/LICENSE)。
页面通过 CDN 加载的外部资源不随仓库分发，包括 three.js（MIT）以及 Pretendard、Hahmlet、IBM Plex 字体（SIL OFL）。
diff --git a/skills/plz-setup-issues/README.ja.md b/skills/plz-setup-issues/README.ja.md
index 5ee1023..b29d874 100644
--- a/skills/plz-setup-issues/README.ja.md
+++ b/skills/plz-setup-issues/README.ja.md
@@ -1,36 +1,50 @@
# plz-setup-issues
[English](README.md) | [한국어](README.ko.md) | 日本語 | [简体中文](README.zh-CN.md)
-GitHub リポジトリに、再利用できる簡潔な Issue 分類、フォーム、トリアージ規則を設定します。Claude Code と Codex に対応し、[plz](../../README.md) に含まれるスキルです。
+GitHub リポジトリに、再利用できる簡潔な Issue 分類、フォーム、トリアージ規則を設定します。Claude Code と Codex に対応し、[plz](https://github.com/codekongdev/plz) に含まれるスキルです。
## インストール
-グローバルにインストール:
+`npx skills` でインストールするには、Node.js 22.20 以降（npm と `npx` を含む）、Git、利用する Claude Code または Codex が必要です。まずターミナルでツールを確認します。
```sh
-npx skills add codekongdev/plz --skill plz-setup-issues -g
+node --version
+npm --version
+git --version
```
-Codex では `-a codex` を付けます。以下のコマンドは現在のプロジェクトの `.agents/skills/` にインストールします。
+利用するエージェントのコマンドを選んでください。`-g` でグローバルにインストールすると、複数のプロジェクトで使えます。
+
+Claude Code:
```sh
-npx skills add codekongdev/plz --skill plz-setup-issues -a codex
+npx skills add codekongdev/plz --skill plz-setup-issues -a claude-code -g
```
-## 使い方
-
-Claude Code:
+Codex:
-```text
-/plz-setup-issues Set up issue management in this repository.
+```sh
+npx skills add codekongdev/plz --skill plz-setup-issues -a codex -g
```
-Codex:
+現在のプロジェクトだけで使う場合は、そのプロジェクトのディレクトリで上記コマンドから `-g` を外して実行します。インストーラーは `.agents/skills/` にスキルを保存し、Claude Code を選んだ場合はリンクも作成します。
-```text
-$plz-setup-issues Set up issue management in this repository.
+利用するエージェントのインストール一覧に `plz-setup-issues` が表示されることを確認します。
+
+```sh
+npx skills list -g -a claude-code
+npx skills list -g -a codex
```
+プロジェクトにインストールした場合は、確認コマンドでも `-g` を外し、同じプロジェクトで実行します。一覧にない場合は、選択したエージェントとインストール範囲を確認してください。一覧にあってもエージェントが認識しない場合は、利用するプロジェクトで新しいエージェントセッションを開始します。
+
+## 使い方
+
+インストール後、対象リポジトリでエージェントを開き、スキルを指定して依頼します。
+
+- Claude Code: `/plz-setup-issues このリポジトリの Issue 管理を初期設定して。`
+- Codex: `$plz-setup-issues このリポジトリの Issue 管理を初期設定して。`
+
ローカルファイルの作成のみを依頼することも、特定の GitHub リポジトリへのラベル適用を明示的に依頼することもできます。変更前に既存の設定を確認し、競合する規則は解決方針が決まるまで保持します。
## デフォルト構成
diff --git a/skills/plz-setup-issues/README.ko.md b/skills/plz-setup-issues/README.ko.md
index ccb0aee..c65242f 100644
--- a/skills/plz-setup-issues/README.ko.md
+++ b/skills/plz-setup-issues/README.ko.md
@@ -1,36 +1,50 @@
# plz-setup-issues
[English](README.md) | 한국어 | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
-GitHub 저장소에 재사용할 수 있는 간결한 이슈 분류, 이슈 양식, 검토 규칙을 세팅합니다. Claude Code와 Codex에서 사용할 수 있으며, [plz](../../README.md)에 포함된 스킬입니다.
+GitHub 저장소에 재사용할 수 있는 간결한 이슈 분류, 이슈 양식, 검토 규칙을 세팅합니다. Claude Code와 Codex에서 사용할 수 있으며, [plz](https://github.com/codekongdev/plz)에 포함된 스킬입니다.
## 설치
-전역으로 설치:
+`npx skills`로 설치하려면 Node.js 22.20 이상(npm과 `npx` 포함), Git, 사용할 Claude Code 또는 Codex가 필요합니다. 먼저 터미널에서 도구를 확인합니다.
```sh
-npx skills add codekongdev/plz --skill plz-setup-issues -g
+node --version
+npm --version
+git --version
```
-Codex에서 쓰려면 `-a codex`를 붙입니다. 아래 명령은 현재 프로젝트의 `.agents/skills/`에 설치합니다.
+사용할 에이전트의 명령을 선택하세요. `-g`로 전역 설치하면 여러 프로젝트에서 사용할 수 있습니다.
+
+Claude Code:
```sh
-npx skills add codekongdev/plz --skill plz-setup-issues -a codex
+npx skills add codekongdev/plz --skill plz-setup-issues -a claude-code -g
```
-## 사용법
-
-Claude Code:
+Codex:
-```text
-/plz-setup-issues Set up issue management in this repository.
+```sh
+npx skills add codekongdev/plz --skill plz-setup-issues -a codex -g
```
-Codex:
+현재 프로젝트에서만 쓰려면 해당 프로젝트 폴더에서 위 명령의 `-g`를 빼고 실행합니다. 설치 도구는 `.agents/skills/`에 스킬을 저장하고, Claude Code를 선택하면 연결도 만듭니다.
-```text
-$plz-setup-issues Set up issue management in this repository.
+사용할 에이전트의 설치 목록에 `plz-setup-issues`가 표시되는지 확인합니다.
+
+```sh
+npx skills list -g -a claude-code
+npx skills list -g -a codex
```
+프로젝트에 설치했다면 확인 명령에서도 `-g`를 빼고 같은 프로젝트에서 실행합니다. 목록에 없다면 선택한 에이전트와 설치 범위를 확인하세요. 목록에 있지만 에이전트에서 인식하지 못한다면 사용할 프로젝트에서 새 에이전트 세션을 시작합니다.
+
+## 사용법
+
+설치한 뒤 대상 저장소에서 에이전트를 열고 스킬을 지정해 요청합니다.
+
+- Claude Code: `/plz-setup-issues 이 저장소의 이슈 관리 초기 설정을 해 줘.`
+- Codex: `$plz-setup-issues 이 저장소의 이슈 관리 초기 설정을 해 줘.`
+
로컬 파일만 만들도록 요청하거나, 특정 GitHub 저장소에 라벨까지 적용하도록 명시할 수 있습니다. 변경 전에 기존 설정을 확인하며, 충돌하는 규칙은 해결 방향이 정해질 때까지 보존합니다.
## 기본 구성
diff --git a/skills/plz-setup-issues/README.md b/skills/plz-setup-issues/README.md
index a81e246..b010f2b 100644
--- a/skills/plz-setup-issues/README.md
+++ b/skills/plz-setup-issues/README.md
@@ -1,36 +1,50 @@
# plz-setup-issues
English | [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
-Set up issue management for a GitHub repository with a small, reusable taxonomy, issue forms, and written triage rules. Works with Claude Code and Codex. Part of [plz](../../README.md).
+Set up issue management for a GitHub repository with a small, reusable taxonomy, issue forms, and written triage rules. Works with Claude Code and Codex. Part of [plz](https://github.com/codekongdev/plz).
## Install
-Install globally:
+To install with `npx skills`, you need Node.js 22.20 or later (with npm and `npx`), Git, and Claude Code or Codex. Check the command-line tools first:
```sh
-npx skills add codekongdev/plz --skill plz-setup-issues -g
+node --version
+npm --version
+git --version
```
-For Codex, add `-a codex`. This installs into the current project's `.agents/skills/` directory:
+Choose your agent below. `-g` installs the skill globally, so it is available across projects.
+
+Claude Code:
```sh
-npx skills add codekongdev/plz --skill plz-setup-issues -a codex
+npx skills add codekongdev/plz --skill plz-setup-issues -a claude-code -g
```
-## Usage
-
-Claude Code:
+Codex:
-```text
-/plz-setup-issues Set up issue management in this repository.
+```sh
+npx skills add codekongdev/plz --skill plz-setup-issues -a codex -g
```
-Codex:
+For this project only, run the matching command from the project directory with `-g` omitted. The installer stores the skill in `.agents/skills/` and links it for Claude Code when selected.
-```text
-$plz-setup-issues Set up issue management in this repository.
+Check the installation for your agent; the list should include `plz-setup-issues`:
+
+```sh
+npx skills list -g -a claude-code
+npx skills list -g -a codex
```
+For a project installation, omit `-g` from the check and run it in the same project. If the skill is missing, check the selected agent and installation scope. If it is listed but unavailable in your agent, start a new agent session from the intended project.
+
+## Usage
+
+After installing, open your agent in the target repository and invoke the skill:
+
+- Claude Code: `/plz-setup-issues Set up issue management in this repository.`
+- Codex: `$plz-setup-issues Set up issue management in this repository.`
+
You can request local files only, or explicitly ask to apply labels to a named GitHub repository. Existing settings are inspected before changes, and conflicting conventions are preserved until resolved.
## Defaults
diff --git a/skills/plz-setup-issues/README.zh-CN.md b/skills/plz-setup-issues/README.zh-CN.md
index fb7036e..8cbe643 100644
--- a/skills/plz-setup-issues/README.zh-CN.md
+++ b/skills/plz-setup-issues/README.zh-CN.md
@@ -1,36 +1,50 @@
# plz-setup-issues
[English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | 简体中文
-为 GitHub 仓库设置可复用的精简议题分类、议题表单和分诊规则。支持 Claude Code 和 Codex，是 [plz](../../README.md) 的一部分。
+为 GitHub 仓库设置可复用的精简议题分类、议题表单和分诊规则。支持 Claude Code 和 Codex，是 [plz](https://github.com/codekongdev/plz) 的一部分。
## 安装
-全局安装：
+使用 `npx skills` 安装时，需要 Node.js 22.20 或更高版本（包含 npm 和 `npx`）、Git，以及要使用的 Claude Code 或 Codex。先在终端确认工具可用：
```sh
-npx skills add codekongdev/plz --skill plz-setup-issues -g
+node --version
+npm --version
+git --version
```
-在 Codex 中使用时加上 `-a codex`。以下命令安装到当前项目的 `.agents/skills/` 目录：
+选择要使用的代理对应的命令。`-g` 表示全局安装，可在多个项目中使用。
+
+Claude Code:
```sh
-npx skills add codekongdev/plz --skill plz-setup-issues -a codex
+npx skills add codekongdev/plz --skill plz-setup-issues -a claude-code -g
```
-## 使用方法
-
-Claude Code:
+Codex:
-```text
-/plz-setup-issues Set up issue management in this repository.
+```sh
+npx skills add codekongdev/plz --skill plz-setup-issues -a codex -g
```
-Codex:
+如果只在当前项目中使用，请在项目目录中运行上述命令并去掉 `-g`。安装工具会将技能保存到 `.agents/skills/`，选择 Claude Code 时还会创建链接。
-```text
-$plz-setup-issues Set up issue management in this repository.
+查看对应代理的已安装技能列表，确认其中包含 `plz-setup-issues`：
+
+```sh
+npx skills list -g -a claude-code
+npx skills list -g -a codex
```
+如果安装在项目中，检查时也要去掉 `-g`，并在同一项目目录中运行。如果列表中没有该技能，请检查选择的代理和安装范围。如果列表中有但代理无法识别，请在目标项目中启动新的代理会话。
+
+## 使用方法
+
+安装后，在目标仓库中打开代理，指定技能发出请求：
+
+- Claude Code: `/plz-setup-issues 初始化这个仓库的议题管理。`
+- Codex: `$plz-setup-issues 初始化这个仓库的议题管理。`
+
可以只请求生成本地文件，也可以明确要求向指定的 GitHub 仓库应用标签。修改前会检查现有设置，冲突的规则会保留，直到确定解决方案。
## 默认配置