Coding Guidance Qt
Fix Qt5/Qt6 CMake builds by applying version-driven find_package, linking, and moc/uic/qrc conventions instead of hard-coded Qt targets.
Overview
Coding Guidance Qt is an agent skill for the Build phase that standardizes CMake and Qt5/Qt6 compatibility patterns for find_package, linking, and moc/uic/qrc generated steps.
Install
npx skills add https://github.com/n-n-code/n-n-code-skills --skill coding-guidance-qtWhat is this skill?
- Version-driven CMake: QT NAMES Qt6 Qt5 and Qt${QT_VERSION_MAJOR} targets instead of hard-coded Qt5:: / Qt6::
- Qt6-first guidance to prefer qt_standard_project_setup() and qt_add_executable() over hand-rolled targets
- Explicit review hotspots: stale Q_OBJECT/moc, uic/qrc drift, and platform-specific cached generated files
- Treats moc, uic, and qrc edits as build-contract changes requiring regeneration
- Open only when CMake, generated Qt steps, or dual Qt version support is in scope
Adoption & trust: 1 installs on skills.sh; 4 GitHub stars; 3/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
Your Qt app builds on one Qt major version or one developer machine but fails in CI because CMake hard-codes Qt5:: or Qt6:: and generated moc/uic/qrc outputs are stale.
Who is it for?
Maintainers of CMake-based Qt apps who need agent help during Qt version upgrades or mysterious moc/uic/qrc failures.
Skip if: Greenfield Qt projects already locked to a single Qt6 template with no dual-version requirement, or QMake-only repos without CMake.
When should I use this skill?
The task touches CMake, generated Qt build steps (moc, uic, qrc), or real Qt5/Qt6 compatibility requirements.
What do I get? / Deliverables
CMake and target wiring use version-agnostic Qt patterns and regenerated build steps so dual Qt5/Qt6 support compiles reliably across environments.
- Updated CMake patterns for dual Qt support
- Identified moc/uic/qrc regeneration fixes
Recommended Skills
Journey fit
Build is the canonical phase because the skill addresses compile-time CMake and Qt code-generation contracts, not ideation or launch distribution. Integrations fits CMake/Qt toolchain wiring, generated build steps, and cross-version compatibility—core build-system integration work.
How it compares
Reference skill for Qt CMake contracts—not a general C++ style guide or UI design system.
Common Questions / FAQ
Who is coding-guidance-qt for?
Solo and small-team developers shipping Qt/C++ apps with CMake who hit Qt5/Qt6 portability or code-generation build breaks.
When should I use coding-guidance-qt?
Use it in Build when CMakeLists.txt hard-codes Qt targets, moc/uic/qrc fail after class changes, or the repo advertises both Qt5 and Qt6 support.
Is coding-guidance-qt safe to install?
It is documentation-style guidance; review the Security Audits panel on this Prism page before granting your agent shell access to run CMake builds.
SKILL.md
READMESKILL.md - Coding Guidance Qt
# Qt Build Compatibility Open this reference only when the task touches CMake, generated Qt build steps, or real Qt5/Qt6 compatibility requirements. ## Use when - the repo claims support for both Qt5 and Qt6 - `CMakeLists.txt` contains hard-coded `Qt5::` or `Qt6::` targets - generated-code inputs such as moc, uic, or qrc are part of the failure - a build works on one Qt version and fails on the other ## Core patterns - Prefer version-driven discovery over hard-coded target families: ```cmake find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core Widgets) find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core Widgets) ``` - Prefer version-driven targets: ```cmake target_link_libraries(myapp Qt${QT_VERSION_MAJOR}::Core Qt${QT_VERSION_MAJOR}::Widgets ) ``` - In Qt6-first repos that are not already standardized on a stable local pattern, prefer Qt's helper commands such as `qt_standard_project_setup()` and `qt_add_executable()` over ad hoc Qt target setup. - Treat moc, uic, and qrc changes as build-contract changes, not local cleanup. ## Review hotspots - hard-coded `Qt5::` / `Qt6::` targets in a repo that claims both - new hand-rolled CMake setup in a Qt6-first repo where Qt helper commands would be clearer and less error-prone - generated headers or sources not regenerated after class-shape changes - stale `Q_OBJECT` additions that compile only because one platform cached old generated files - resource lookups that depend on the current working directory ## Validation - configure and build each claimed Qt variant - verify generated-code inputs are part of the build graph - smoke-test the changed UI path on at least one affected platform # Qt Debugging Checklist Open this reference when the task is primarily diagnosis rather than ordinary implementation. ## Use when - the failure class is still unclear and you need to categorize before editing - the bug looks like ownership, signal/slot, layout, thread-affinity, or style breakage - the change is mostly diagnosis rather than feature or refactor work ## Fast categorization Classify the symptom before changing code: - invisible widget - zero-size widget or collapsed layout - deleted-object access - cross-thread QObject misuse - pre-`QApplication` GUI object construction - frozen event loop / blocked GUI thread - signal connected but never fires - style or QSS mismatch ## High-value checks ### Invisible or collapsed widget - check `isVisible()`, `isHidden()`, and actual size - verify parent visibility for child widgets - verify a real layout is attached - check `QSizePolicy`, stretch, minimum size, margins, and accidental `setFixedSize(0, 0)` ### Deleted-object or lifecycle bug - check whether the object is owned by a parent that is already gone - check `deleteLater()` timing and queued callbacks - prefer `QPointer` for observing objects with unstable lifetime - in C++, use ASan before guessing ### Thread-affinity bug - look for cross-thread parent/child creation - verify where the receiver lives, not only where the signal was emitted - make queued delivery explicit if the hop matters ### Signal path bug - verify sender lifetime - verify exact signal/slot signature compatibility - verify `Q_OBJECT` is present and moc reran after the last change ### Frozen UI - find the blocking call on the GUI thread - move I/O or heavy work off-thread - treat `processEvents()` as diagnosis only, not the final fix ### Style or QSS bug - inspect the effective stylesheet - use local `unpolish()` / `polish()` and `update()` to confirm rule application before changing rendering logic ## Review hotspots - code changes made before the failure class was identified - `processEvents()` used as a production fix instead of diagnosis - guessed lifecycle or thread explanations without checking object ownership or affinity - layout or style fixes applied without verifying the actual geometry or active stylesheet state ## Useful C++ diagnostics