stockfish-integration

Grips001's avatarfrom Grips001

Verify Stockfish WASM integration patterns. Use when working with engine code, UCI commands, or move analysis to ensure correct async patterns and error handling.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 8, 2026⬇️3downloads
[Code Review]

When & Why to Use This Skill

This Claude skill automates the verification of Stockfish WASM engine integration patterns within your codebase. It ensures robust implementation of UCI commands, asynchronous workflows, and error handling by identifying anti-patterns and validating code against established best practices for chess engine integration, significantly reducing debugging time for engine-related features.

Use Cases

  • Validating that Stockfish WASM initialization and ready-state checks are correctly implemented before any engine operations are performed.
  • Auditing UCI command sequences to ensure game positions (FEN) are properly set before triggering move analysis or evaluations.
  • Detecting asynchronous anti-patterns such as 'fire and forget' calls or missing 'await' keywords in engine communication pipelines.
  • Ensuring comprehensive error handling for engine-specific exceptions like EngineNotReadyError or InvalidFENError to improve application stability.
  • Reviewing code in src/engine/ or analysis pipelines to ensure compliance with the project's architectural standards for engine wrappers.
namestockfish-integration
allowed-toolsRead, Grep, Glob

Stockfish WASM Integration Patterns

Automatically verify correct usage of the Stockfish WASM engine integration.

When to Apply

  • Working with files in src/engine/
  • Implementing move analysis features
  • Debugging engine communication issues
  • Adding new UCI commands

Architecture Overview

Frontend Request → WebSocket IPC → Backend Handler → Stockfish Engine
                                                          ↓
Frontend Display ← WebSocket IPC ← Backend Response ← UCI Output

Key Files

File Purpose
src/engine/stockfish-engine.ts Main engine wrapper
src/engine/stockfish-loader.ts WASM loading
src/shared/engine-types.ts Type definitions
src/shared/engine-constants.ts Engine configuration
src/backend/analysis-pipeline.ts Batch analysis integration

Correct Patterns

Engine Initialization

// Always check engine ready state before use
if (!engine.isReady()) {
  await engine.initialize();
}

UCI Command Pattern

// Set position before analysis
engine.setPosition(fen);

// Use appropriate depth/time limits
const analysis = await engine.analyze({
  depth: 20,
  multiPV: 3,
});

Error Handling

try {
  const result = await engine.getBestMove(fen);
} catch (error) {
  if (error instanceof EngineNotReadyError) {
    // Reinitialize engine
  } else if (error instanceof InvalidFENError) {
    // User feedback for invalid position
  }
}

Async Patterns

// Always await engine operations
const moves = await engine.getTopMoves(fen, 3);

// Use Promise.all for independent operations
const [eval1, eval2] = await Promise.all([
  engine.evaluate(fen1),
  engine.evaluate(fen2),
]);

Anti-Patterns to Avoid

// DON'T: Fire and forget
engine.analyze(fen); // Missing await

// DON'T: Assume engine is ready
engine.getBestMove(fen); // Should check isReady()

// DON'T: Block on synchronous operations
while (!engine.isReady()) {} // Use async/await

Verification Checklist

  1. All engine calls are awaited
  2. Engine ready state checked before use
  3. Proper error types used (not generic Error)
  4. UCI commands follow correct sequence
  5. Analysis results validated before use

Reference

  • documents/engine-integration.md - Full integration guide
  • Stockfish UCI protocol documentation