cursor-agent-skills

Setup and patterns for a Vite + React frontend with Capacitor and Ionic React, plus a separate Next.js backend in a monorepo. Use when creating or modifying a Capacitor mobile app with a Vite frontend and Next.js API, or when adding Capacitor to an existing Vite app with a Next.js backend.

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.

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.

Canonical flow for starting and verifying a backend dev server. Use before running API tests: check port, start from correct directory, confirm readiness via short-timeout health request. Prevents 60–90+ second curl timeouts and port-conflict misdiagnosis.

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%.

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

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.