qt-suite

Run coverage analysis for the Qt project. Instruments the build, executes tests, generates an HTML report, identifies coverage gaps, and optionally triggers the test-generator agent to fill them.

Generate unit tests for Qt/PySide6 source files. Claude scans the project, identifies files that need better test coverage, and writes test files following the project's testing conventions.

Generate a new Qt widget, dialog, or window class with correct boilerplate and object names.

Build and run the Qt project's test suite. Auto-detects Python (pytest) vs C++ (CMake + CTest) and reports results with a pass/fail summary.

Scaffold a new Python/PySide6 application with pyproject.toml, src layout, and qt-suite config.

Launch the Qt/PySide6 application headlessly and run visual GUI tests using the bundled Qt Pilot MCP server. Claude interacts with the live UI via screenshots, clicks, and text input.

Qt code quality reviewer. Use PROACTIVELY after writing or modifying Qt application code. Reviews against Qt best practices, testability standards, and common anti-patterns. Examples: <example> Context: The user has just implemented a new widget. user: "I've finished implementing the DataTableWidget" assistant: "Great! Let me use the qt-app-reviewer agent to check it against Qt best practices." <commentary> Proactive code review after implementation — checks for object naming, layout usage, signal wiring, and memory management. </commentary> </example> <example> Context: The user has refactored a Qt component. user: "I refactored the main window to use a splitter" assistant: "I'll use the qt-app-reviewer to verify the refactoring follows Qt patterns correctly." <commentary> Refactors can introduce subtle Qt issues — the reviewer checks for regressions. </commentary> </example> <example> Context: A Qt file was modified in a commit. user: "Review the changes I just made to settings_dialog.py" assistant: "I'll use the qt-app-reviewer agent to review the changes." <commentary> Direct review request on a Qt file. </commentary> </example>

Qt application debugger. Use PROACTIVELY when encountering Qt errors, crashes, segfaults, unexpected widget behavior, frozen UIs, or test failures related to Qt code. Examples: <example> Context: The user reports a crash in their Qt app. user: "My PySide6 app crashes when I click the save button" assistant: "I'll use the qt-debugger agent to diagnose and fix the crash." <commentary> A crash is the primary trigger for the qt-debugger — systematic diagnosis before attempting fixes. </commentary> </example> <example> Context: A widget is not appearing as expected. user: "My widget isn't showing up on screen" assistant: "I'll use the qt-debugger agent to diagnose the visibility issue." <commentary> Widget visibility issues have specific diagnostic steps — the qt-debugger knows the checklist. </commentary> </example> <example> Context: The user sees a Qt error message. user: "I'm getting 'QObject: Cannot create children for a parent in a different thread'" assistant: "I'll use the qt-debugger agent to diagnose this thread safety violation." <commentary> Specific Qt error messages have known root causes — the qt-debugger can diagnose and fix them efficiently. </commentary> </example> <example> Context: The application UI is unresponsive. user: "My app freezes for a few seconds when processing files" assistant: "I'll use the qt-debugger agent to identify and fix the blocking operation." <commentary> UI freezes indicate blocking calls on the main thread — a threading pattern issue the qt-debugger specializes in. </commentary> </example>

Qt UI/UX advisor for widget design, keyboard navigation, accessibility, and testability-oriented widget naming. Use PROACTIVELY when reviewing UI design, evaluating widget layout, checking keyboard navigation, assessing accessibility, or ensuring widgets have object names for testing. Examples: <example> Context: The user has finished building a new dialog. user: "I've built the new FileImportDialog — does it look right?" assistant: "I'll use the qt-ux-advisor agent to review the dialog for UX quality and testability." <commentary> A completed dialog is a natural trigger for UX review — keyboard navigation, widget naming, and layout hierarchy. </commentary> </example> <example> Context: The user wants to improve keyboard navigation. user: "How do I make my form keyboard-navigable?" assistant: "I'll use the qt-ux-advisor agent to audit the form and implement correct tab order and keyboard shortcuts." <commentary> Keyboard navigation is a specialized UX concern — the qt-ux-advisor knows Qt's tab order, shortcuts, and focus policies. </commentary> </example> <example> Context: The user is checking accessibility. user: "Is my app accessible to screen reader users?" assistant: "I'll use the qt-ux-advisor agent to audit the application for accessibility." <commentary> Qt accessibility requires setting widget names, accessible descriptions, and correct roles — specialized knowledge. </commentary> </example> <example> Context: Tests fail because widgets can't be found by name. user: "The gui-tester can't find my buttons — they have no names" assistant: "I'll use the qt-ux-advisor agent to audit the widget naming and add setObjectName() calls." <commentary> Untestable widgets are a UX and quality issue — the qt-ux-advisor bridges the gap between dev work and visual testing. </commentary> </example>

Use this agent when coverage analysis has identified untested code paths and tests need to be generated to fill those gaps. Also use when asked to "generate tests for the coverage gaps", "write tests for the uncovered lines", "fill coverage gaps", or "improve test coverage for these files". Examples: <example> Context: The user just ran /qt:coverage and it found that calculator.py has 74% coverage with lines 18-22 and 45 untested. user: "Generate tests for the coverage gaps" assistant: "I'll use the test-generator agent to write targeted tests for the uncovered lines in calculator.py." <commentary> The user explicitly asked to generate tests for coverage gaps that were just discovered. This is the test-generator's core use case. </commentary> </example> <example> Context: /qt:coverage completed and found 3 files below the 80% threshold. user: "Yes, generate tests for those gaps" assistant: "I'll launch the test-generator agent to target the uncovered paths in each file." <commentary> The user confirmed they want gap-filling tests after the coverage command offered to generate them. </commentary> </example> <example> Context: The user has been told about coverage gaps and wants to improve them. user: "Write tests targeting lines 18-22 in calculator.py — those are the error handling paths" assistant: "I'll use the test-generator agent to write tests for those specific lines." <commentary> The user specified exact lines to target, which is the test-generator's precise use case. </commentary> </example>

Qt application development specialist. Use PROACTIVELY when creating a new Qt project, implementing Qt widgets or windows, building new features in a PySide6/PyQt6 application, or designing the architecture of a Qt GUI app. Examples: <example> Context: The user is starting a new PySide6 application. user: "I want to build a desktop app for managing my music library" assistant: "I'll use the qt-app-dev agent to help architect and scaffold the application." <commentary> A new Qt application needs architecture decisions, project layout, and initial scaffolding — the qt-app-dev agent's primary use case. </commentary> </example> <example> Context: The user is adding a new feature to an existing Qt app. user: "Add a settings panel to my PySide6 application" assistant: "I'll use the qt-app-dev agent to implement the settings panel with the correct Qt patterns." <commentary> Implementing a settings panel requires knowledge of QSettings, QDialog, and layout patterns — the qt-app-dev agent has these as preloaded skills. </commentary> </example> <example> Context: A new .py file importing PySide6 was just created. user: "I've created main_window.py — implement the main window" assistant: "I'll use the qt-app-dev agent to implement the main window with proper QMainWindow structure." <commentary> A new Qt file being created is a trigger for proactive qt-app-dev involvement. </commentary> </example> <example> Context: The user wants to display data in a table. user: "I need to show a list of products in a table" assistant: "I'll use the qt-app-dev agent to implement this with QAbstractTableModel and QTableView." <commentary> Qt Model/View is a non-trivial pattern — the qt-app-dev agent knows when and how to use it. </commentary> </example>

Use this agent when the user wants to visually test a Qt/PySide6 application's UI behavior using the Qt Pilot MCP server. Triggers on requests to "test the GUI", "run visual tests", "test what the user sees", "interact with the app", "test the UI flows", "check the interface", or "run the app and test it". Also activates when /qt:visual is invoked. Examples: <example> Context: The user has just finished implementing a new dialog in their PySide6 app. user: "Test the new file save dialog to make sure it works correctly" assistant: "I'll use the gui-tester agent to launch the app headlessly and walk through the save dialog flow." <commentary> The user wants end-to-end visual testing of a specific UI flow, which is exactly what the gui-tester agent does via Qt Pilot. </commentary> </example> <example> Context: The user wants a general smoke test of their application. user: "Run the app and test that all the main buttons work" assistant: "I'll use the gui-tester agent to launch the app and interact with each UI element." <commentary> A smoke test of the running UI is the gui-tester's general-purpose use case. </commentary> </example> <example> Context: The user invoked /qt:visual. user: "/qt:visual test the login flow" assistant: "Starting visual testing session for the login flow." <commentary> The /qt:visual command delegates to this agent for the actual GUI testing work. </commentary> </example> <example> Context: The user wants to verify UI behavior after a code change. user: "The main window was refactored — make sure the UI still behaves correctly" assistant: "I'll use the gui-tester agent to run a visual regression check on the main window." <commentary> Visual regression checking after refactoring is a core gui-tester use case. </commentary> </example>

Qt application architecture, project structure, and entry-point patterns for PySide6, PyQt6, and C++/Qt. Use when structuring a Qt app, setting up QApplication, designing the main window, choosing between MVC/MVP patterns, organizing a src layout, or deciding how to separate concerns in a GUI application. Trigger phrases: "structure my Qt app", "QApplication setup", "app entry point", "Qt project layout", "organize Qt code", "Qt MVC", "Qt MVP", "main window architecture", "new Qt project"

Python Qt binding differences and migration guides — PySide6 vs PyQt6 API differences, and migration paths from PyQt5 to both modern bindings. Use when choosing between PySide6 and PyQt6, porting a PyQt5 codebase, handling binding-specific API differences, or writing code that must work with both bindings. Trigger phrases: "PySide6 vs PyQt6", "PyQt5 migration", "binding difference", "migrate from PyQt5", "PyQt6 migration", "PySide6 or PyQt6", "binding compatibility", "porting Qt Python", "LGPL vs GPL"

This skill should be used when the user asks about "coverage", "test coverage", "coverage gaps", "untested code", "gcov", "lcov", "coverage report", "improve coverage", "missing tests", "coverage threshold", "coverage-driven test generation", or "what code isn't tested". Covers the full coverage feedback loop for both Python/PySide6 (coverage.py) and C++/Qt (gcov + lcov). Also activates for "pytest-cov", "run coverage on my Qt project", or "CI coverage report".

Diagnosing and fixing Qt application issues — crashes, event loop problems, widget rendering failures, segfaults, and common runtime errors. Use when Qt crashes, a widget doesn't appear, the event loop freezes, signals aren't connecting, or the app exits unexpectedly. Trigger phrases: "Qt error", "crash", "segfault", "widget not showing", "event loop", "app exits unexpectedly", "Qt warning", "QPainter error", "assertion failed", "QObject destroyed", "application not responding"

Qt dialog patterns — QDialog, QMessageBox, QFileDialog, QInputDialog, and custom modal/modeless dialogs. Use when creating confirmation prompts, file pickers, settings dialogs, custom data entry dialogs, or wizard-style multi-step dialogs. Trigger phrases: "dialog", "QMessageBox", "QFileDialog", "QInputDialog", "modal", "modeless", "settings dialog", "confirm dialog", "custom dialog", "file picker", "wizard", "popup"

Qt layout managers — arranging and sizing widgets within containers. Use when placing widgets, controlling resize behavior, building form layouts, creating splitters, nesting containers, or debugging widgets that don't appear where expected. Trigger phrases: "arrange widgets", "layout", "resize behavior", "QSplitter", "center widget", "widget not visible", "expand to fill", "fixed size", "stretch factor", "form layout", "grid layout", "spacing", "margins"

Qt Model/View architecture — QAbstractItemModel, table/list/tree views, item delegates, and proxy models. Use when displaying tabular data, building a list with custom items, implementing a tree, creating a sortable/filterable table, or writing a custom item delegate. Trigger phrases: "QAbstractItemModel", "table view", "list model", "QTableView", "QListView", "tree view", "item delegate", "sort table", "filter model", "QSortFilterProxyModel", "custom model", "model data"

Packaging and distributing Qt Python applications — PyInstaller, Briefcase, and platform-specific build configurations. Use when distributing a PySide6 or PyQt6 app as a standalone executable, creating installers, configuring macOS bundles, Windows executables, or Linux AppImages. Trigger phrases: "package app", "PyInstaller", "distribute", "deploy", "standalone executable", "installer", "bundle app", "briefcase", "Windows build", "macOS build", "AppImage", "one-file"

This skill should be used when the user asks to "visual test", "test the GUI", "headless test", "test a running app", "interact with the UI", "take a screenshot of the app", "click a widget", "find a widget", "test UI behavior", "Qt Pilot", "launch app headlessly", or "test what the user sees". Covers the Qt Pilot MCP server's 15 tools for AI-driven headless GUI testing of Qt/PySide6 applications. Also activates for "Xvfb", "automate UI", "visual regression", "capture screenshot of app".

QML and Qt Quick — declarative UI language for modern Qt applications. Use when building a QML-based UI, embedding QML in a Python/C++ app, exposing Python/C++ objects to QML, creating QML components, or choosing between QML and widgets. Trigger phrases: "QML", "Qt Quick", "declarative UI", "QQmlApplicationEngine", "expose to QML", "QML component", "QML signal", "pyqtProperty", "QML vs widgets", "QtQuick.Controls", "Item", "Rectangle"

Qt resource system — .qrc files, embedding icons and assets, loading resources at runtime, and using pyrcc6 or PySide6-rcc. Use when bundling icons, images, or other files into the application, loading resources via ":/" paths, or migrating from a file-system asset approach. Trigger phrases: ".qrc file", "embed icon", "pyrcc6", "PySide6-rcc", "bundled assets", "resource path", ":/icons/", "QIcon", "QPixmap from resources", "bundle image"

Persistent application settings using QSettings — storing and restoring user preferences, window geometry, recent files, and application state. Use when saving user preferences, persisting window size/position, storing recent file lists, or managing application configuration. Trigger phrases: "QSettings", "persistent settings", "save preferences", "restore window", "user preferences", "remember state", "save window geometry", "recent files", "app configuration", "settings persistence"

Qt signals and slots — the core inter-object communication mechanism. Use when connecting signals to slots, defining custom signals, debugging disconnected signals, passing data between objects, or handling cross-thread communication safely. Trigger phrases: "connect signal", "custom signal", "slot not firing", "disconnect signal", "cross-thread signal", "signal not working", "emit signal", "define signal", "QObject signal"

Qt stylesheets (QSS) and theming — custom widget appearance, dark/light mode, color palettes, and platform-consistent styling. Use when applying custom styles, implementing dark mode, theming an application, styling specific widget states, or overriding platform defaults. Trigger phrases: "stylesheet", "QSS", "theme", "dark mode", "custom widget appearance", "style widget", "QPalette", "widget color", "hover style", "disabled style", "app theme", "visual style"

Qt threading patterns — QThread, QRunnable, QThreadPool, and thread safety for GUI applications. Use when running background tasks, keeping the UI responsive during long operations, managing worker threads, using thread pools, or debugging race conditions and deadlocks. Trigger phrases: "QThread", "worker", "background task", "thread safety", "UI freezing", "long operation", "QRunnable", "QThreadPool", "thread pool", "concurrent", "responsive UI", "blocking the event loop"

This skill should be used when the user asks to "write a test", "add tests to", "create a QTest", "how do I test a widget", "unit test for Qt", "pytest-qt", "test a PySide6 class", "QML test", "QtQuickTest", "write a test case", "test this class", or "generate a test file". Covers C++ QTest, Python pytest-qt, and QML TestCase patterns with CMake integration. Also activates for "write a C++ Qt test", "add a CMake test target", or "set up testlib".