majidmanzarpour/threejs-game-skills

threejs‑game‑skills – AI‑driven skill pack for building Three.js browser games

What it is – A collection of agent skills that let large‑language‑model (LLM) assistants such as Codex and Claude Code act as a full‑stack game developer for Three.js. The pack bundles a Vite + TypeScript scaffold, helper scripts, deterministic test hooks and a director skill that orchestrates specialist sub‑skills (gameplay, graphics, UI, asset generation, audio, debugging, QA, release). The idea is that you tell the agent “build a premium hover‑racing game” and the director automatically calls the right sub‑skills, generates code and assets, runs Playwright‑based smoke/visual‑regression tests, and produces a release‑ready build – all without you having to write the low‑level Three.js code yourself.

---

Key components

Skill	Role
threejs‑game‑director	Entry point; decides scope, routes to other skills, keeps a project note, runs verification passes.
threejs‑gameplay‑systems	Sets up game loops, input, camera, physics, scoring, and overall architecture.
threejs‑aaa‑graphics‑builder	Improves models, materials, lighting, VFX and produces a visual‑scorecard.
threejs‑game‑ui‑designer	Builds HUDs, menus, responsive overlays, touch‑area safety checks.
threejs‑debug‑profiler	Finds runtime errors, performance bottlenecks, mobile‑specific bugs.
threejs‑qa‑release	Generates production builds, runs Playwright screenshots, canvas‑pixel checks, viewport tests, and creates a release risk report.
threejs‑3d‑generator	(Optional) Calls the Tripo API to turn text or images into GLB/FBX assets.
threejs‑image‑generator	(Optional) Calls Gemini image generation for textures, skyboxes, UI art, etc.
threejs‑audio‑generator	(Optional) Calls ElevenLabs for SFX, music loops, voice‑over/TTS.

All skills live under a skills/ folder, each with a SKILL.md description, reference docs, and scripts that the agent can invoke.

---

Installation

# Install for Codex agents
npx skills add majidmanzarpour/threejs-game-skills --skill '*' -a codex -g -y

# Install for Claude Code agents
npx skills add majidmanzarpour/threejs-game-skills --skill '*' -a claude-code -g -y

If the skills CLI you use does not support the -a flag, clone the repo and run the bundled installer:

./install.sh --codex      # only Codex skills
./install.sh --claude     # only Claude Code skills
./install.sh --all        # both

The installer copies the skills/ directory into the appropriate agent‑skill location, skips duplicate names unless --force is given, and never removes unrelated user skills.

---

How to use it

1. Open an empty folder (or an existing Three.js project) in the LLM‑agent UI.
2. Prompt the agent with a natural‑language request and name the director skill, e.g.:

   Use threejs-game-director to build a futuristic tower‑defense game from scratch.
   Automatically use the relevant gameplay, graphics, UI, asset generation, audio,
   debug and QA skills. First create a playable loop, then iterate until it passes
   browser, mobile, visual, performance and release checks.
   

3. The director loads the scaffold, creates the core loop, calls the graphics/UI/audio sub‑skills as needed, runs the bundled Playwright tests, and finally returns a summary with evidence (build logs, screenshots, performance metrics, asset IDs).

The same prompt works for both Codex and Claude Code because the SKILL.md files are shared.

---

Optional API keys

The core workflow works without any paid services. If you provide the following keys, the asset‑generation skills can pull in higher‑quality external assets:

Provider	Skill	Env var
Tripo	threejs‑3d‑generator	TRIPO_API_KEY
Google Gemini	threejs‑image‑generator	GEMINI_API_KEY
ElevenLabs	threejs‑audio‑generator	ELEVENLABS_API_KEY

The director includes a small probe script (probe_asset_credentials.sh) that reports whether each key is set.

---

Demos

Game	Video	Playable link
Neon Ridge Drift	Watch on X	https://ridgedrift.netlify.app
Championship Snooker Arena	Watch on X	https://snookerarena.netlify.app
Starship Dogfight	Watch on X	https://starshipdogfight.netlify.app
Tide Singer	Watch on X	https://tidesinger.netlify.app
Ripcore	Watch on X	https://ripcore.netlify.app

Each demo was generated by the skill pack, showing that the director can produce a complete, polished Three.js game with minimal manual coding.

---

Evidence & verification

When a skill claims success it must provide concrete artifacts, for example:

• npm run build output and a production bundle.
• Playwright screenshots and a visual‑regression baseline.
• Canvas‑pixel non‑blank checks and rendered‑budget metrics (triangles, draw calls, texture memory).
• Performance snapshots when graphics change.
• A visual scorecard (calibrated against reference anchors) for AAA‑level claims.
• Bot play‑test metrics for gameplay loops.
• Paths to any generated 3D/2D/audio assets or a note that credentials were missing.

The director’s check_evidence.py script validates the manifest that lists all these artifacts.

---

Maintenance & testing

Developers can run the repository’s own checks:

npm install
npm run check:scripts
npm run validate:skills
npm run test:helpers

Helper scripts are also exposed for manual runs (e.g., inspect-threejs-canvas.mjs).

---

License

MIT – free to use, modify, and redistribute.

---

TL;DR

threejs‑game‑skills is a ready‑to‑install pack of LLM‑agent skills that let AI assistants act as a complete Three.js game studio. Install the pack, tell the director what kind of game you want, and the system will generate code, assets, run automated tests, and give you a release‑ready web game – all without you writing the low‑level Three.js boilerplate yourself.