audit(plugin-grade): implement all 6 recommended actions from Anthropic guide grading

- Add argument-hint to 11 skills missing it (26/27 now covered, playdotfun submodule excluded)
- Standardize compatibility field placement to root level (game-qa, meshyai)
- Improve README positioning with outcome-focused opening
- Create trigger test suite (tests/trigger-tests.md) with 5-7 prompts per skill
- Add troubleshooting guide (docs/troubleshooting.md) covering all common issues
- Document reference/wrapper skill convention in CLAUDE.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
rshtirmer
2026-03-10 17:23:51 -04:00
parent 86a264dc3e
commit 0dbf4a9e32
15 changed files with 484 additions and 3 deletions
+33
View File
@@ -177,6 +177,24 @@ skills/phaser/
**Skills with companion files:** `phaser` (8), `game-qa` (7), `game-audio` (6), `meshyai` (3), `game-assets` (3), `threejs-game` (3+), `make-game` (3).
## Reference vs User-Invocable Skills
Skills come in two flavors with a deliberate separation of concerns:
- **User-invocable skills** (17) — Triggered by slash commands (e.g., `/add-audio`). These handle the full user-facing workflow: detect the game, load reference skills, run the pipeline, validate output. They have `argument-hint` in frontmatter.
- **Reference skills** (10) — Deep domain knowledge loaded by other skills (or directly via `/load`). They contain patterns, code examples, and conventions but don't drive a workflow themselves.
Four domains have both a reference and a user-invocable skill:
| Reference Skill | User-Invocable Skill | Why Both Exist |
|-----------------|---------------------|----------------|
| `game-audio` | `add-audio` | `game-audio` has Web Audio API patterns reused by `add-audio` AND `make-game` step 3 |
| `game-qa` | `qa-game` | `game-qa` has Playwright patterns reused by `qa-game` AND the QA subagent in `make-game` |
| `game-assets` | `add-assets` | `game-assets` has pixel art patterns reused by `add-assets` AND `make-game` step 1.5 |
| `game-designer` | `design-game` | `game-designer` has visual polish patterns reused by `design-game` AND `make-game` step 2 |
This separation avoids duplicating domain knowledge across multiple skills. The reference skill is the single source of truth; the user-invocable skill orchestrates the workflow and loads the reference skill for domain knowledge.
## Common Tasks
**Add a new skill**: Create `skills/<name>/SKILL.md`. Follow existing skill format with tech stack, architecture, code examples, and checklist. For skills >300 lines, extract detailed code examples and reference material into companion files.
@@ -241,3 +259,18 @@ The `/monetize-game` command (and Step 5 of `/make-game`) registers games on [Pl
**SDK**: CDN script (`https://sdk.play.fun/latest`) + `src/playfun.js` that wires EventBus events (score changes, game over) to Play.fun points tracking. Non-blocking — if SDK fails to load, game still works.
**Anti-cheat**: Games are registered with `maxScorePerSession`, `maxSessionsPerDay`, and `maxCumulativePointsPerDay` based on the game's scoring system.
## Troubleshooting
See `docs/troubleshooting.md` for common issues including:
- Skill triggering (wrong skill loads, skill doesn't trigger, negative tests)
- Build failures (module not found, port conflicts, empty dist)
- Playwright/QA (browser not found, low FPS in headless, visual regression tolerance)
- Deployment (here.now failures, anonymous expiry, GitHub Pages blank page)
- Play.fun (auth failures, SDK not loading, anti-cheat rejections)
- 3D assets (T-pose, wrong facing, Meshy timeouts)
- Audio (autoplay policy, frequency issues)
## Trigger Test Suite
See `tests/trigger-tests.md` for manual test prompts (5-7 per skill) verifying correct trigger behavior. Covers all 17 user-invocable skills plus negative tests for prompts that should NOT trigger any skill.
+5 -1
View File
@@ -1,6 +1,10 @@
# game-creator
The game studio for the agent internet. Build, monetize, and ship 2D (Phaser 3) and 3D (Three.js) browser games with one command. QA runs after every step. Monetize with [Play.fun](https://play.fun) (OpenGameProtocol). Works with **40+ AI coding agents** (via `npx skills add`). Share your play.fun URL on [Moltbook](https://www.moltbook.com/).
**Go from game idea to deployed, monetized browser game in minutes — not hours.**
Tell your AI coding agent "make a space invaders game" and get a fully playable 2D or 3D browser game with pixel art, procedural audio, and automated QA. Deploy instantly to the web. Monetize with [Play.fun](https://play.fun). Share on [Moltbook](https://www.moltbook.com/).
Works with **40+ AI coding agents** — Claude Code, Cursor, Windsurf, Cline, and more via `npx skills add`.
**Owner**: [OpusGameLabs](https://github.com/OpusGameLabs)
+165
View File
@@ -0,0 +1,165 @@
# Troubleshooting
Common issues and fixes for the game-creator plugin.
## Skill Triggering Issues
### Skill doesn't trigger
**Symptom**: You say "make a game" but the skill doesn't load.
**Fixes**:
1. Check the skill is installed: `npx skills list` should show `game-creator`
2. Use the explicit slash command: `/game-creator:make-game 2d my-game`
3. If using a non-Claude agent, ensure the agent supports skill loading (check `npx skills add` docs for your agent)
4. Try rephrasing with exact trigger phrases from the skill description (e.g., "build me a game", "create a new game")
### Skill triggers on unrelated query
**Symptom**: Asking about game theory or board games loads a game-creator skill.
**Fixes**:
1. Be specific: "Explain game theory in economics" vs "make a game"
2. If a skill loads incorrectly, tell the agent: "I don't want the game-creator skill, I'm asking about X"
3. Each skill's description includes "Do NOT use for..." clauses — if these are insufficient, open an issue
### Wrong skill triggers
**Symptom**: You want to add audio but `/add-feature` loads instead.
**Reference — which skill to use**:
| Want to... | Use this | Not this |
|------------|----------|----------|
| Build from scratch | `/make-game` | `/add-feature` |
| Add pixel art | `/add-assets` | `/add-feature` |
| Add 3D models | `/add-3d-assets` | `/add-feature` |
| Add music/SFX | `/add-audio` | `/add-feature` |
| Visual polish | `/design-game` | `/improve-game` |
| Add gameplay mechanic | `/add-feature` | `/improve-game` |
| Full audit + fixes | `/improve-game` | `/review-game` (review only) |
| Code review only | `/review-game` | `/improve-game` (also implements) |
| Write tests | `/qa-game` | `/review-game` |
| Deploy | `/monetize-game` (includes deploy) | — |
## Build Failures
### `npm run build` fails with module not found
**Cause**: Missing import or circular dependency.
**Fix**: Check that all imports use relative paths (`./core/EventBus.js`, not `core/EventBus`). Vite requires file extensions in ES module imports.
### `npm run dev` port already in use
**Cause**: Another dev server is running on port 3000.
**Fix**: Kill the existing process (`lsof -ti:3000 | xargs kill`) or use a different port (`npm run dev -- --port 3001`). The make-game pipeline auto-increments ports when it detects conflicts.
### Vite build outputs empty `dist/`
**Cause**: `index.html` is not in the project root, or `vite.config.js` has a wrong `root` setting.
**Fix**: Ensure `index.html` is at the project root (not inside `src/`). Check `vite.config.js` doesn't override `root`.
## Playwright / QA Issues
### Tests fail with "browser not found"
**Fix**: Run `npx playwright install chromium`. The make-game pipeline attempts this automatically but it can fail in restricted environments.
### FPS test fails (reports ~7 FPS)
**Expected**: Headless Chromium runs at reduced FPS (~7-9). The default threshold is 5 FPS. This is not a bug — real browsers achieve 60 FPS.
**Fix**: Don't raise the FPS threshold above 5 for headless tests. Use Playwright MCP (real browser) for accurate FPS measurement.
### Visual regression tests fail with pixel differences
**Expected**: Parallax clouds and animated elements shift between captures. The default tolerance is 3000 maxDiffPixels.
**Fix**: Increase `maxDiffPixels` if your game has more animation, or use `page.clock.install()` to freeze time before screenshots.
### `render_game_to_text()` returns undefined
**Cause**: The function isn't exposed on `window`, or the game hasn't booted yet.
**Fix**: Ensure `main.js` sets `window.render_game_to_text = () => { ... }` and the test fixture waits for the game to initialize (check `game-test.js` fixture for the pattern).
## Deployment Issues
### here.now deploy fails
**Causes**:
1. No internet connection
2. `dist/` doesn't exist (run `npm run build` first)
3. The `here-now` skill isn't installed
**Fix**: Run `npx skills add heredotnow/skill --skill here-now -g` to install the deployment skill. Then `npm run build && npx here-now dist/`.
### Anonymous deploy expires after 24 hours
**Expected**: Anonymous here.now deploys are temporary. The deploy output includes a "claim URL" — visit it to make the deploy permanent.
### GitHub Pages deploy shows blank page
**Cause**: Vite's `base` path doesn't match the GitHub Pages URL.
**Fix**: Set `base: '/<repo-name>/'` in `vite.config.js` (or `base: '/'` if using a custom domain).
## Play.fun / Monetization Issues
### Authentication fails
**Fix**:
1. Visit https://play.fun/dashboard
2. Refresh your Creator Credentials
3. Paste the API Key and Secret Key when prompted
4. If using MCP, update the `x-api-key` and `x-secret-key` headers in your MCP client configuration
### SDK doesn't load (points not tracking)
**Cause**: The CDN script failed to load (network issue or ad blocker).
**Expected**: The SDK is non-blocking. Games work without it. Points buffer locally and sync when the SDK becomes available.
**Fix**: Check browser console for SDK errors. Ensure `https://sdk.play.fun/latest` is not blocked. The `src/playfun.js` wrapper handles SDK absence gracefully.
### Anti-cheat rejects valid scores
**Cause**: `maxScorePerSession` is set too low for your game's scoring system.
**Fix**: Update the anti-cheat limits when registering the game. The limits in `playfun.js` should match realistic gameplay maximums — check the `ANTI_CHEAT` object in Constants.js.
## 3D Asset Issues
### GLB model loads in T-pose (no animation)
**Cause**: Used `.clone(true)` instead of `SkeletonUtils.clone()`.
**Fix**: Always use `SkeletonUtils.clone(model)` from `three/examples/jsm/utils/SkeletonUtils.js` for animated models. Regular clone breaks skeleton bindings.
### Model faces wrong direction
**Cause**: Different models have different default facing directions.
**Fix**: Store a `facingOffset` per character model. Soldier/Xbot face -Z (need `+Math.PI`), Robot/Fox face +Z (need `+0`). Apply the offset to the model's rotation.
### Meshy AI generation times out
**Expected**: Meshy text-to-3D takes 2-5 minutes. Image-to-3D can take longer.
**Fix**: The `meshy-generate.mjs` script polls automatically. If it times out, check your `MESHY_API_KEY` is valid and you haven't hit the API rate limit.
## Audio Issues
### No sound plays
**Cause**: Browser autoplay policy blocks AudioContext before user interaction.
**Fix**: Audio must initialize on first user interaction (click/tap/keypress). The `AudioManager.js` pattern listens for the `AUDIO_INIT` event, which fires on first game input. Don't try to play audio before this event.
### Music sounds wrong / out of tune
**Cause**: Web Audio API oscillator frequencies are in Hz, not MIDI notes.
**Fix**: Use the frequency conversion helpers in the audio skill. Check `music.js` patterns for correct note-to-frequency mapping.
+1
View File
@@ -1,6 +1,7 @@
---
name: fetch-tweet
description: Fetch tweet content directly from fxtwitter API. Use when given a tweet/X URL to extract the tweet text, author, media, and engagement stats without loading x.com.
argument-hint: "[tweet-url]"
license: MIT
metadata:
author: OpusGameLabs
+1
View File
@@ -1,6 +1,7 @@
---
name: game-3d-assets
description: 3D asset engineer that finds, downloads, and integrates GLB/GLTF models into Three.js browser games. Use when a 3D game needs real models instead of primitive BoxGeometry/SphereGeometry shapes.
argument-hint: "[topic]"
license: MIT
metadata:
author: OpusGameLabs
+1
View File
@@ -1,6 +1,7 @@
---
name: game-architecture
description: Game architecture patterns and best practices for browser games. Use when designing game systems, planning architecture, structuring a game project, or making architectural decisions about game code.
argument-hint: "[topic]"
license: MIT
metadata:
author: OpusGameLabs
+1
View File
@@ -1,6 +1,7 @@
---
name: game-assets
description: Game asset engineer that creates pixel art sprites, animated characters, and visual entities for browser games. Use when a game needs better character art, enemy sprites, item visuals, or any upgrade from basic geometric shapes to recognizable pixel art.
argument-hint: "[topic]"
license: MIT
metadata:
author: OpusGameLabs
+1
View File
@@ -1,6 +1,7 @@
---
name: game-audio
description: Game audio engineer using Web Audio API for procedural music and sound effects in browser games. Zero dependencies. Use when adding music or SFX to a game.
argument-hint: "[topic]"
license: MIT
metadata:
author: OpusGameLabs
+1
View File
@@ -1,6 +1,7 @@
---
name: game-deploy
description: Deploy browser games to here.now (default), GitHub Pages, or other hosting. Use when deploying a game, setting up hosting, or publishing a game build. Do NOT use for local development servers (use npm run dev).
argument-hint: "[platform]"
license: MIT
compatibility: Requires internet access. Uses npx (here.now) or gh CLI (GitHub Pages) for deployment.
metadata:
+1
View File
@@ -1,6 +1,7 @@
---
name: game-designer
description: Game UI/UX designer that analyzes and improves the visual polish, atmosphere, and player experience of browser games. Use when a game needs visual improvements, better backgrounds, particles, animations, screen transitions, juice/feel, or overall aesthetic upgrades.
argument-hint: "[topic]"
license: MIT
metadata:
author: OpusGameLabs
+2 -1
View File
@@ -1,12 +1,13 @@
---
name: game-qa
description: Game QA testing with Playwright — visual regression, gameplay verification, performance, and accessibility for browser games. Use when writing or running game tests, debugging test failures, or building QA infrastructure. This is the reference skill — use qa-game for the user-facing command.
argument-hint: "[topic]"
license: MIT
compatibility: Requires Node.js and Playwright for browser-based game testing.
metadata:
author: OpusGameLabs
version: 1.3.0
tags: [game, qa, testing, playwright]
compatibility: Requires Node.js and Playwright for browser-based game testing.
---
# Game QA with Playwright
+2 -1
View File
@@ -1,12 +1,13 @@
---
name: meshyai
description: Generate custom 3D models from text or images using Meshy AI, then auto-rig and animate them for Three.js games. The preferred source for all 3D game assets. Use when the user says "generate a 3D model", "create a character model", "use Meshy", or needs a custom GLB model that doesn't exist in free libraries.
argument-hint: "[text-prompt or image-path]"
license: MIT
compatibility: Requires MESHY_API_KEY environment variable and internet access for Meshy AI API calls.
metadata:
author: OpusGameLabs
version: 1.3.0
tags: [game, 3d, meshy, ai, model-generation, rigging, animation]
compatibility: Requires MESHY_API_KEY environment variable and internet access for Meshy AI API calls.
---
# Meshy AI — 3D Model Generation, Rigging & Animation
+1
View File
@@ -3,6 +3,7 @@ name: promo-video
description: >
Record a high-FPS autonomous promo video of a Phaser game using Playwright.
Triggers on: promo video, gameplay recording, marketing video, game capture.
argument-hint: "[path-to-game]"
license: MIT
compatibility: Requires Playwright and FFmpeg installed locally for video capture and encoding.
metadata:
+1
View File
@@ -1,6 +1,7 @@
---
name: threejs-game
description: Build 3D browser games with Three.js using event-driven modular architecture. Use when creating a new 3D game, adding 3D game features, setting up Three.js scenes, or working on any Three.js game project.
argument-hint: "[topic]"
license: MIT
metadata:
author: OpusGameLabs
+268
View File
@@ -0,0 +1,268 @@
# Skill Trigger Test Suite
Manual test prompts to verify skills trigger correctly. Run each prompt against the plugin and verify the expected skill loads (or doesn't load).
## How to Use
1. Install the plugin: `npx skills add OpusGameLabs/game-creator`
2. For each test case, enter the prompt in your AI coding agent
3. Verify the correct skill loads (check the skill name in the agent's response)
4. Mark pass/fail
---
## make-game
**Should trigger:**
- "make a game"
- "build me a game"
- "create a new game"
- "make a 2D platformer"
- "build a 3D space shooter"
- "I want to make a flappy bird clone"
- "create a browser game from scratch"
**Should NOT trigger:**
- "improve my existing game" → `improve-game`
- "add a new feature to my game" → `add-feature`
- "fix the bug in my game" → (no skill)
- "explain how games work" → (no skill)
---
## quick-game
**Should trigger:**
- "quick game"
- "fast game"
- "rapid prototype a game"
- "make a game quickly"
- "speed run a game build"
**Should NOT trigger:**
- "make a polished game" → `make-game`
- "build a production game" → `make-game`
---
## improve-game
**Should trigger:**
- "improve my game"
- "make my game better"
- "audit my game"
- "what should I fix in my game"
- "enhance the gameplay"
**Should NOT trigger:**
- "add a jetpack feature" → `add-feature`
- "make the background prettier" → `design-game`
- "add music to my game" → `add-audio`
- "review my game code" → `review-game`
---
## add-feature
**Should trigger:**
- "add a jetpack feature"
- "add double jump"
- "I want to add a power-up system"
- "add multiplayer"
- "add a new weapon"
**Should NOT trigger:**
- "add background music" → `add-audio`
- "add pixel art sprites" → `add-assets`
- "add 3D models" → `add-3d-assets`
- "improve the whole game" → `improve-game`
---
## add-assets
**Should trigger:**
- "add pixel art to my game"
- "replace shapes with sprites"
- "add character art"
- "make the player look like a real character"
- "add enemy sprites"
**Should NOT trigger:**
- "add 3D models" → `add-3d-assets`
- "add a jetpack feature" → `add-feature`
- "make the background prettier" → `design-game`
---
## add-3d-assets
**Should trigger:**
- "add 3D models to my game"
- "replace cubes with real models"
- "add a character model"
- "find a 3D model of a tree"
**Should NOT trigger:**
- "add pixel art" → `add-assets`
- "generate a 3D model with Meshy" → `meshyai`
- "create a 3D environment" → `worldlabs`
---
## add-audio
**Should trigger:**
- "add music to my game"
- "add sound effects"
- "add audio"
- "I want background music"
- "add a jump sound"
**Should NOT trigger:**
- "explain how Web Audio API works" → (no skill)
- "add a feature" → `add-feature`
---
## design-game
**Should trigger:**
- "make my game look better"
- "add visual polish"
- "add particles"
- "improve the UI"
- "add screen transitions"
- "make it juicy"
**Should NOT trigger:**
- "improve gameplay mechanics" → `improve-game`
- "add pixel art sprites" → `add-assets`
---
## monetize-game
**Should trigger:**
- "monetize my game"
- "add Play.fun to my game"
- "register on play.fun"
- "add the play.fun SDK"
- "launch a playcoin"
**Should NOT trigger:**
- "deploy my game" → (use `/monetize-game` which includes deploy, or direct deploy)
- "explain what play.fun is" → (no skill)
---
## qa-game
**Should trigger:**
- "add tests to my game"
- "write Playwright tests"
- "add QA tests"
- "test my game"
**Should NOT trigger:**
- "review my game code" → `review-game`
- "run the existing tests" → (no skill, just `npm run test`)
---
## review-game
**Should trigger:**
- "review my game code"
- "code review"
- "check my architecture"
- "audit the codebase"
**Should NOT trigger:**
- "fix the bugs" → (no skill)
- "improve my game" → `improve-game` (also implements fixes)
- "add tests" → `qa-game`
---
## record-promo
**Should trigger:**
- "record a promo video"
- "capture gameplay footage"
- "make a marketing video"
- "record my game"
**Should NOT trigger:**
- "take a screenshot" → (no skill)
- "add a video player to my game" → `add-feature`
---
## use-template
**Should trigger:**
- "use the flappy bird template"
- "clone a template"
- "start from a template"
- "use template tower-defense"
**Should NOT trigger:**
- "make a game from scratch" → `make-game`
- "show me the gallery" → (no skill)
---
## meshyai
**Should trigger:**
- "generate a 3D model"
- "use Meshy to create a character"
- "create a 3D model of a dragon"
- "generate a GLB model"
**Should NOT trigger:**
- "find a 3D model online" → `game-3d-assets`
- "create a 3D environment" → `worldlabs`
- "add 3D models to my game" → `add-3d-assets`
---
## worldlabs
**Should trigger:**
- "generate a 3D world"
- "create an environment"
- "make a 3D scene"
- "use World Labs"
**Should NOT trigger:**
- "generate a 3D character model" → `meshyai`
- "add 3D models to my game" → `add-3d-assets`
---
## fetch-tweet
**Should trigger:**
- (auto-triggered when a tweet URL is detected in make-game)
- "fetch this tweet: https://x.com/user/status/123"
**Should NOT trigger:**
- "post a tweet" → (no skill)
- "search Twitter" → (no skill)
---
## Negative Tests (No Skill Should Trigger)
These prompts should NOT trigger any game-creator skill:
- "What is the capital of France?"
- "Write a Python script to sort a list"
- "Explain quantum computing"
- "Help me with my React app"
- "Design a database schema"
- "Write a poem about games" (mentions "games" but not a game creation task)
- "What's the best game engine?" (informational, not actionable)
- "Run my existing tests" (use `npm run test`, not a skill)