Game Sounds

When to use this skill

Install or verify @citedy/game-sounds.
Switch a sound pack, manage rotation, set volume, or toggle event categories.
Diagnose a silent hook or create a custom local pack.
Explain the difference between the standalone CLI and Claude Code hook integration.

Route game-production SFX design or asset generation to rfxgen, game-vfx, or an engine-specific audio skill. This skill is for developer-agent feedback sounds, not a game's runtime audio system.

Instructions

Step 1: Capture the operating mode

Identify:

host: Claude Code plugin, global npm CLI, or cloned plugin directory;
action: install, status, configure, test, or custom pack;
platform player: afplay on macOS; paplay, pw-play, or ffplay on Linux;
acceptable audio behavior: volume, enabled events, and whether random rotation is desired.

Step 2: Check before installing

bash .agent-skills/game-sounds/scripts/setup.sh --check

Prefer the official Claude marketplace path when the user is in Claude Code. Use npm for a global game-sounds CLI, or clone only when a local plugin directory is explicitly wanted.

bash .agent-skills/game-sounds/scripts/setup.sh --npm
bash .agent-skills/game-sounds/scripts/setup.sh --clone

Restart Claude Code after plugin installation or hook changes.

Step 3: Validate configuration before editing it

The upstream configuration has four fields: volume, active_pack, pack_rotation, and enabled_events.

python3 .agent-skills/game-sounds/scripts/validate_config.py /path/to/config.json

Require volume in [0.0, 1.0], safe pack names, a unique string rotation list, and booleans for all event toggles. Prefer the upstream CLI over direct JSON edits:

game-sounds status
game-sounds list
game-sounds switch starcraft
game-sounds rotation add zelda
game-sounds volume 0.3
game-sounds test task-complete

Step 4: Map hooks to observable events

The inspected upstream hook mapping is:

SessionStart → session-start
UserPromptSubmit → task-acknowledge
Stop → task-complete
PostToolUseFailure → error
Notification → permission

When a hook is silent, check config discovery, event enablement, pack/category files, executable permissions, and the platform audio player in that order.

Step 5: Add custom packs conservatively

Create one pack directory with event-category subdirectories. Use only audio the user owns or is licensed to distribute. The upstream repository is MIT for its software, but bundled sounds and recognizable game/media properties may carry separate rights; preserve upstream credits and do not represent the audio catalog as universally redistributable.

Step 6: Verify real playback

A status command only proves configuration. Run one explicit game-sounds test <category> and confirm audible output with the user. If the environment is headless or has no audio device, report that configuration passed but playback was not verified.

Examples

Set a quiet rotating pair

game-sounds rotation clear
game-sounds rotation add mario
game-sounds rotation add zelda
game-sounds volume 0.2
game-sounds status

Validate a cloned plugin config

python3 .agent-skills/game-sounds/scripts/validate_config.py \
  "$HOME/.claude/plugins/game-sounds/config.json" --json

Best practices

Use the CLI for changes and the validator for diagnosis.
Test one event explicitly after configuration.
Keep volume low and allow event categories to be disabled.
Do not install or play sounds without user consent in shared or accessibility-sensitive environments.
Separate software licensing from the rights of bundled audio assets and trademarks.

References

references/upstream.md — current upstream package, commands, hook map, and platform notes.
Citedy/game-sounds