Skip to content

docs: clarify installation and first use - #36

Merged
codekongdev merged 1 commit into
mainfrom
docs/quick-start
Nov 4, 2026
Merged

codekongdev merged 1 commit into
mainfrom
docs/quick-start

Conversation

@codekongdev

Copy link
Copy Markdown
Owner

Summary

First-time users had to infer the prerequisites, installation scope, and how to confirm that a skill was ready to use. The root and both skill READMEs now walk through prerequisites, explicit Claude Code/Codex installation commands, installation checks, and a first request in English, Korean, Japanese, and Simplified Chinese.

Clarify that npx skills needs Node.js 22.20+ and Git, distinguish global from project installation, and explain that the server/browser tools used for 3D validation are prepared separately. Replace skill README links to repository-level files with GitHub URLs so they remain usable after standalone installation.

The documented shell commands install skill files into the chosen agent/scope or list installed skills; the version commands only inspect the environment. The changed external links point to this repository and its existing license/contribution guide. Skill execution instructions and assets are unchanged.

Closes #35

Type of change

  • Translation or README
  • Bug fix
  • Skill improvement (SKILL.md, references/, or assets/)
  • New skill
  • CI or tooling
  • Other

How I verified it

  • node scripts/check-readme-translations.mjs — all 12 READMEs pass; code blocks, URLs, images, table rows, language switches, and relative links are consistent.
  • git diff --check — passes.
  • Reviewed installation flags and Node.js requirements against skills CLI 1.7.6. During the preceding audit, both public skills installed successfully into an isolated project for Claude Code and Codex, including their required resources.
  • An independent review found no blocking issue. A new page was not generated in either agent as part of this documentation change.

Checklist

  • node scripts/check-readme-translations.mjs passes (or I only changed things it does not cover)
  • If I changed ENGINE in template.html, I applied the same change to example-agent-sandbox.html, and node scripts/check-templates.mjs passes (not applicable)
  • If I added a UI_TEXT key, I added it for en, ko, ja, and zh-CN, and node scripts/check-templates.mjs passes (not applicable)
  • I did not commit references/preferences.md, generated pages, or verification screenshots
  • I added no new external URLs or shell commands, or I explained them in the summary above
  • If this is a new skill, I understand that maintainers may add the translations to my branch, and I enabled "Allow edits by maintainers" (not applicable)

@coderabbitai

coderabbitai Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Summary

Summary by CodeRabbit

  • Documentation
    • Updated multilingual installation guides with prerequisites, agent-specific global and project-level setup instructions, installation checks, and troubleshooting steps.
    • Added Claude Code and Codex usage examples and clarified requirements for local servers and browser-based validation, including how to report checks that could not be run.
    • Updated project, demo, and contribution links in the relevant guides.

Updates root and skill READMEs in English, Japanese, Korean, and Simplified Chinese. The documentation adds prerequisites, agent-specific installation and invocation examples, installation checks, and troubleshooting guidance. It also clarifies the tools needed for page verification and updates repository links in skill READMEs.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other · Severity of issue fixed: Low

Assessment against linked issues

Objective Addressed Explanation
Explicit Claude Code and Codex install commands with clear global or project scope [#35] ✅
Installation checks and direct skill invocation examples [#35] ✅
Troubleshooting and 3D verification-tool prerequisites [#35] ✅
Usable repository links and four-language README consistency [#35] ❓ The summaries show updates in all four languages, but do not report the README consistency check result.

Possibly related PRs

  • codekongdev/plz#33: Introduces the plz-setup-issues skill and its README files, which this PR updates with installation and usage guidance.
Merge Risk: Minimal · up to d052a

This documentation-only change introduces no established merge-blocking risk.

Architecture risk: Low · up to d052a

The change affects 5 systems.

Changed systems: skills, README.ja.md, README.ko.md, README.md, README.zh-CN.md

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — skills (service) was modified; 8 changed files map to changed impact.
  • observed — README.ja.md (service) was modified; 1 changed file maps to changed impact.
  • observed — README.ko.md (service) was modified; 1 changed file maps to changed impact.
  • observed — README.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

  • observed — Modified behavior in README.ja.md: インストール要件に Node.js 22.20 以降、npm、Git、利用するエージェントを追加し、Claude Code と Codex のグローバルインストール手順、-g を外すプロジェクト単位の手順、インストール済みスキルの一覧確認方法を記載しました。旧手順の単一コマンドと Codex の折りたたみ説明は置き換えられました。
  • observed — Modified behavior in README.ja.md: 全スキルのグローバルインストールについて、エージェント選択を求められた場合は利用するツールを選ぶ説明を追加しました。
  • observed — Modified behavior in README.ja.md: 新しいセッションで Claude Code は /plz-3d-explain、Codex は $plz-3d-explain を使う呼び出し例を追加しました。スキルが見つからない場合はエージェント、インストール範囲、セッション、Node.js 要件を確認する手順も追記しました。通常の言葉での依頼例と言語対応の記述は維持されています。
  • observed — Modified behavior in README.ja.md: ページ作成要件に Python 3 を例とするローカル HTTP サーバーを追加し、スキルのインストールでは Python やブラウザ自動化ツールをインストールしないこと、ツールがなければ検証前に準備を依頼すること、HTML の生成だけではブラウザ検証の合格を示さないことを明記しました。旧記述の「ローカルサーバー」はより具体化されています。
Recent review info
Run configuration
Commits

Reviewing files that changed from the base of the PR and between ad5c454 and d052a90.

Files selected for processing: 12
  • README.ja.md
  • README.ko.md
  • README.md
  • README.zh-CN.md
  • skills/plz-3d-explain/README.ja.md
  • skills/plz-3d-explain/README.ko.md
  • skills/plz-3d-explain/README.md
  • skills/plz-3d-explain/README.zh-CN.md
  • skills/plz-setup-issues/README.ja.md
  • skills/plz-setup-issues/README.ko.md
  • skills/plz-setup-issues/README.md
  • skills/plz-setup-issues/README.zh-CN.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

@codekongdev
codekongdev merged commit 788cb1d into main Nov 4, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: make installation and first use clear for new users

1 participant