pmarashian/cursor-agent-skills

Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.

Essential workflow guidelines for AI agents working on development tasks. Use at the start of every task to ensure proper workflow, skill discovery, port detection, testing methodology, and verification. Consolidates critical prompt updates for consistent agent behavior across all tasks.

Integrate external assets (PixelLab, ElevenLabs) into projects with proper error handling, fallback mechanisms, and testing patterns. Use when generating assets, downloading files, or integrating assets into game code. Standardizes workflow and reduces integration time by 25-35%.

Handle asynchronous operations from MCP servers (PixelLab, ElevenLabs, etc.) with intelligent polling, timeout management, and parallel work opportunities. Use when waiting for async jobs, polling status, or managing long-running operations. Provides exponential backoff, ETA-aware waiting, and prevents premature downloads.

Establish authenticated session for browser-based E2E: register/login via API (curl with cookie jar), then load cookie/state into browser context if supported, or document manual login / test-only bypass and use API verification. Include fallback when cookie/state injection is not supported; revert mocks and document. Use when verifying protected pages in browser tests.

Patterns for reliable browser automation, including timeout handling, retry logic, and fallback strategies. Use when browser automation commands hang, timeout, or fail. Provides configurable timeouts, exponential backoff retry logic, and fallback verification methods for Phaser games and web applications.

Comprehensive guide to agent-browser usage patterns, test seam planning workflow, browser testing optimization patterns, and when to use agent-browser vs alternatives. Use when working with web applications, frontend tasks, or when development servers are running.

Optimize browser testing workflows with test seams, reducing command overhead and improving testing efficiency. Use when testing Phaser games or web applications to reduce execution time by 40-50%. Provides composite test functions, command batching, and efficient wait strategies.

Document when to use test seams vs. DOM inspection, provide patterns for batching related test commands, create reusable test helper functions, and document efficient waiting strategies. Use when testing Phaser games or web applications to reduce execution time and improve reliability.

Persist with browser testing operations that may take 30-90 seconds. Use when browser testing fails or takes longer than expected. Provides expected wait times, timeout configurations, retry logic, and fallback strategies. Improves verification completeness from 60% to 95%.

Protocol enforcement and validation patterns for completion marker output. Use when marking tasks complete to ensure 100% protocol compliance. Provides validation patterns, system-level workarounds, and recovery strategies for completion marker protocol violations.

Efficient completion marker generation to prevent timeouts and improve task completion reliability. Use when marking tasks complete to ensure atomic completion marker output. Prevents timeout issues and reduces completion time by 10-15 seconds.

Configurable API base URL in frontend (e.g. Vite): single env variable (e.g. VITE_API_URL), shared API client that reads it, and all call sites use that client. Do not hardcode host/port in multiple files; do not create or commit .env—only .env.example and documentation. Use when adding or changing frontend API calls.

Cookie-based auth from a different origin (e.g. frontend on 3001, backend on 3000) requires Access-Control-Allow-Credentials true and a specific Access-Control-Allow-Origin (not *). If framework middleware does not apply to API routes, add CORS headers in the route handler. Use when debugging cross-origin cookie/session issues.

When running create-next-app in an existing directory (e.g. backend/): remove or rename existing package.json if the tool refuses to overwrite; prefer absolute path for target; for API-only setups, strip UI (layout, page, globals, public) and clear .next before re-running type-check. Use when scaffolding Next.js in an existing folder.

Run a command with a time limit in a cross-platform way. Do not rely on GNU timeout (coreutils)—it is not default on macOS. Use when agents may run on macOS or when timeout 10s npm run dev fails.

Standardized patterns for detecting, starting, monitoring, and maintaining development server connections. Use when connecting to dev servers, managing server lifecycle, or when connection losses occur during browser automation. Eliminates 2-3 minutes of server management overhead per task.

Automatically detect development server ports from configuration files, running processes, or terminal output. Use when starting browser testing, connecting to dev servers, or when port configuration is unclear. Checks vite.config.ts, package.json, running processes, and terminal output to find the actual port in use.

Patterns for handling ElevenLabs API file outputs, including path management and file relocation. Use when generating audio with ElevenLabs tools, when files are written to unexpected locations, or when output_directory parameter is ignored. Files are always written to $HOME/Desktop regardless of output_directory specification.

Generate speech, transcribe audio, create voice agents, compose music, and manage voices using ElevenLabs MCP Server. Use when working with text-to-speech, speech-to-text, voice cloning, conversational AI agents, or music composition.

Rules for .env file handling, .env.example template format, and what's allowed vs forbidden. Use when working with environment variables, API keys, or configuration files.

Document common error types, provide recovery strategies, retry patterns with limits, and fallback strategies. Use when encountering compilation errors, test failures, tool failures, or other execution errors. Provides systematic approach to error handling and recovery.

Techniques for forcing error conditions in code to test error handling paths, including mock failure injection. Use when testing error handling, maze generation failures, or when error conditions are hard to trigger naturally. Create test scenarios to force error conditions and verify error handling works correctly.

Identify all related changes before editing, batch independent changes in single edit, keep incremental edits for dependent changes, use comprehensive file reads before major refactorings, and document edit planning strategies. Use when making multiple related code changes to reduce edit count and improve efficiency.

Strategies for efficient file reading, caching, and operation planning. Use when reading multiple files, performing code investigation, or when same files are accessed multiple times to reduce file operation overhead by 30-40%.

Standardize async asset generation workflow for game development. Use when generating game assets (PixelLab), waiting for async jobs, retrieving URLs, and updating game code. Trigger: "generate asset", "pixel lab", "asset pipeline", "async asset", "wait for job".

Git best practices for ensuring proper .gitignore setup and git workflow management. Use this skill when initializing new projects, working with package managers (npm, pip, etc.), or making git commits.

Standardized patterns for localStorage utilities, including key naming conventions, error handling, and testing strategies. Use when creating or modifying localStorage utilities, when localStorage key mismatches occur, or when testing storage functionality. This codebase uses camelCase keys (e.g., pixelGameSettings, not pixel-game-settings).

Template for creating localStorage utility functions following established patterns. Use when creating new localStorage utilities, when storage patterns need standardization, or when error handling is needed. Provides template code with error handling and validation.

Monitor for identical tool calls in short timeframes, track progress metrics, and recognize stuck states. Use when agent behavior shows repetitive patterns, no progress, or excessive retries. Prevents infinite loops and stuck execution states.

Document maze generation algorithms (recursive backtracking, etc.), provide error handling patterns, include retry logic with limited attempts, document pathfinding validation patterns, and provide test patterns for maze generation. Use when implementing maze generation features.

Comprehensive guide to MCP servers including PixelLab (async operations, asset download), ElevenLabs (cost warnings, tool selection), and Screenshot Analyzer workflows. Use when working with MCP servers for asset generation, audio processing, or screenshot analysis.

For repos with a backend/ (or similar) directory, treat that as the app root. Create all API routes and library code under backend/src/app/... and backend/src/lib/... Never create src/ at the repository root for backend routes. Use before creating any API or lib file to prevent 404s and wrong-path creation.

For Next.js App Router, use request.formData() and stream/parse the file (e.g. CSV) in the route handler. Do not use Express-style middleware (e.g. multer) in API routes—it can block the request pipeline and cause hangs. Use when implementing file upload in Next.js API routes.

Project-agnostic guide for setting up Next.js with Capacitor for native mobile support and Ionic React for UI components. Includes core setup, optional enhancements, and complete push notifications implementation.

Ensures Next.js 15 dynamic route parameters are properly awaited. Checks for missing await on params destructuring and provides automatic fixes.

Quick reference for Phaser game automation with agent-browser. Skip DOM snapshots and use window.__TEST__ directly. Use when automating Phaser 3 games, testing canvas/WebGL applications, or working with game state inspection. Trigger: "phaser automation", "test phaser", "game automation", "window.__TEST__", "skip snapshot".

Standalone test scenes for Phaser UI components. Use when building or testing a Phaser UI component (slider, toggle, HUD, button, modal, volume control). Create one scene per component, boot via ?scene=ComponentNameTestScene, and test in isolation instead of on the full game page. Unit-test methodology for Phaser components.

Test Phaser games and canvas/WebGL applications with deterministic automation. Plan, implement, and debug frontend tests: unit/integration/E2E/visual/a11y for Phaser 3 games. Use agent-browser CLI for browser automation, Vitest/Jest/RTL, flaky test triage, CI stabilization, and Phaser games needing deterministic input plus screenshot/state assertions. Trigger: "test phaser game", "phaser testing", "game testing", "canvas testing", "webgl testing", "test", "E2E", "flaky", "visual regression", "Playwright".

Build 2D games with Phaser 3 framework. Covers scene lifecycle, sprites, physics (Arcade/Matter), tilemaps, animations, input handling, and game architecture. Trigger: "create phaser game", "add phaser scene", "phaser sprite", "phaser physics", "game development with phaser".

Reusable patterns for implementing HUD elements in Phaser games, including positioning, styling, and test seam integration. Use when creating HUD components, timer displays, score counters, or health bars. Provides templates and patterns for consistent HUD implementation.

Standardized patterns for testing Phaser game movement, including key state handling and collision verification. Use when testing player movement, collision detection, or when movement testing challenges occur. Phaser requires keydown/keyup pattern, not single press events.

Standardized patterns for Phaser scene transitions, navigation testing, and scene lifecycle management. Use when testing scene transitions, navigating between game scenes, or when scene navigation discovery issues occur. Documents scene transition methods, wait patterns, and console log fallback verification.

Standardized Phaser scene template with test seam, lifecycle methods, and common patterns. Use when creating new Phaser scenes to ensure consistency, test seam setup, and proper lifecycle management. Provides template code for new scenes.

Common Phaser scene transition patterns, data passing, and test seam integration for scene management. Use when implementing scene navigation, passing data between scenes, or integrating test seams for scene transitions. Reduces scene transition implementation time by 30-40%.

Comprehensive guide to Phaser game test seam usage, including discovery, common commands, troubleshooting, and best practices. Use when testing Phaser games, interacting with canvas-rendered content, or when DOM-based testing fails. Test seams are the PRIMARY method for Phaser game testing - DOM text search does not work with canvas-rendered text.

Generate pixel art game assets (characters, animations, tilesets) directly from code using PixelLab MCP Server. Use when creating game assets, character sprites, animations, or tilesets for game development.

Check port availability before starting server, provide patterns for killing processes on ports, document automatic port selection strategies, include fallback port ranges, and provide health check patterns. Use when dev server fails to start due to port conflicts.

Check if task is already complete, verify dev server status and port, check TypeScript compilation status, verify required dependencies are installed, and load all required skills upfront. Use at the start of every task to ensure proper environment setup and avoid wasted effort.

Verify existing implementations before coding to prevent duplicate work and enable verification-focused workflows. Use before starting any new feature implementation to check if functionality already exists. Saves 20-40% of implementation time by avoiding redundant work.

Format and structure for progress.txt files, documenting learnings, managing Codebase Patterns section, and when to update progress. Use when documenting work progress, learnings, or codebase patterns.

Systematic approach to code refactoring with pre-analysis, batch planning, and validation checkpoints. Use when refactoring code to reduce refactoring time by 60-70% and improve first-attempt success rate.

Document when to use seeded vs. unseeded RNG, provide patterns for RNG seed management, include examples of deterministic game logic, document seed regeneration patterns, and provide test patterns for RNG behavior. Use when implementing game features that use random number generation.

Guide for using AI-powered screenshot analysis to validate UI, game states, and visual elements

Ensures all screenshots are saved to a dedicated screenshots/ folder instead of project root. Use when capturing screenshots via agent-browser, Playwright, Puppeteer, or any other screenshot capture method to maintain project organization.

Spatial calculation helpers and UI layout patterns for Phaser games and web applications. Use when positioning UI elements, calculating text widths, or working with coordinate systems. Reduces UI positioning iterations from 3-5 to 1-2 by providing calculation patterns and common gotchas.

Comprehensive guide for breaking down Product Requirements Documents (PRDs) into structured, actionable development tasks with dependencies, priorities, and acceptance criteria. Use when generating task breakdowns from PRDs, creating development task lists, or structuring work items for software projects. Essential for converting high-level requirements into granular, executable development tasks.

Standardized workflow for verifying task completion, including success criteria validation, testing checklists, and fallback verification methods. Use before marking tasks complete, when progress tracking shows discrepancies, or when browser testing fails. Ensures all success criteria are verified before task completion.

Multiple testing approaches when primary methods fail, ensuring verification always completes even when tools are unavailable. Use when browser testing fails, agent-browser is unavailable, or primary testing tools don't work. Ensures 100% verification coverage with fallback methods.

Track execution time, identify operation batching opportunities, and prevent timeout violations. Use when approaching time limits or when performing many sequential operations to optimize execution and prevent 300-second timeout failures.

Efficient patterns for testing time-based game features, including timer manipulation and countdown verification. Use when testing timer functionality, countdown features, or time-based game mechanics. Never wait for natural countdown - use test seam setTimer() commands instead.

Tool selection decision framework, domain validation (visual vs audio), cost awareness, and when to use which tool. Use when deciding which tools to use for a given task, especially when working with MCP servers.

Fast TypeScript error detection patterns and best practices for immediate compilation verification. Use immediately after code edits, before proceeding to testing, or when TypeScript errors are discovered late. Run npx tsc --noEmit immediately after edits to catch errors early.

Patterns for avoiding common TypeScript errors, proper type definitions, and early type checking workflows. Use when writing TypeScript code, encountering type errors, or before running tests. Prevents 50-60% of compilation errors and reduces fix cycles from 3-5 to 1-2.

Modify Cursor/VSCode user settings in settings.json. Use when the user wants to change editor settings, preferences, configuration, themes, font size, tab size, format on save, auto save, keybindings, or any settings.json values.

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

Heuristics for visual sizing tasks to reduce refinement iterations. Use when making sprites larger, adjusting UI element sizes, or working with proportional relationships. Provides initial sizing formulas, proportional calculations, and framework-specific patterns. Reduces refinement iterations by 50-70%.

Guide for configuring Vite projects for AI agents. Use when setting up Vite development servers for agent-browser, Playwright, or other automated browser tools. Ensures proper server configuration to prevent unwanted browser windows from opening during agent automation.

Provides battle-tested patterns, best practices, and code examples for building Phaser 3 games. Use when writing game code, implementing game mechanics, setting up scenes, handling physics, animations, input, or any Phaser-related development. Covers architecture, performance, algorithms, and common pitfalls.