/qt-qml-review

name: qt-qml-review
description: >-
  Invoke when the user asks to review, check, audit, or look
  over Qt6 QML code -- or suggest before committing. Runs
  deterministic linting (47+ rules) then six parallel deep-
  analysis agents covering bindings, layout, loaders, delegates,
  states, and performance. Optionally invokes system qmllint
  for type-level checks. Reports only high-confidence issues
  (>80/100) with structured mitigations. Read-only -- never
  modifies code.
license: LicenseRef-Qt-Commercial OR BSD-3-Clause
compatibility: Designed for Claude Code, GitHub Copilot, and similar agents.
disable-model-invocation: false
metadata:
  author: qt-ai-skills
  version: "1.0"
  qt-version: "6.x"
  category: review

Qt QML Code Review

A structured, read-only code review skill for Qt6 QML code that combines deterministic linting with parallel agent-driven deep analysis across six focused domains.

When to use this skill

• When the user mentions review-related tasks: "review", "check",

"audit", "look over", "code review", "sanity check"

• Suggest running this skill **before committing** QML code
• When the user asks to validate Qt6 QML code quality

Scope detection

Detect the user's intended scope from their language:

Diff/commit scope (narrow)

Triggered by language like: "this commit", "these changes", "the diff", "what I changed", "my changes", "staged changes", "outstanding changes", "before I commit"

**Action**: Run `git diff` (unstaged) and `git diff --cached` (staged) to obtain the changeset. If the user says "this commit", use `git diff HEAD~1..HEAD`. Review only the changed lines plus sufficient surrounding context (±50 lines) for understanding. Only report issues found in the changed lines -- do not report issues in unchanged surrounding context.

Codebase scope (wide)

Triggered by language like: "review the codebase", "audit the project", "check the repository", "review src/", or when a specific file/directory path is given without commit language.

**Action**: Glob for `*.qml` files in the specified scope. Review all matched files.

Execution order

The review proceeds in three phases. **Never skip a phase.**

Phase 1: Deterministic linting (Python script)

Run the unified Python linter against the target files. Requires Python 3.6+ (no external dependencies). If Python is not available, warn the user and skip to Phase 1b.

python3 references/lint-scripts/qt_qml_lint.py <files...>
# If python3 is not found, fall back to:
python references/lint-scripts/qt_qml_lint.py <files...>

This single-pass scanner encodes all mechanically-checkable rules from the QML review checklist. It reads each file once and evaluates all rules per line, plus block-level structural checks. Output is deterministic and repeatable. The linter is authoritative -- do not second-guess its output.

Collect all output before proceeding.

**Rule categories** (47+ checks):

• **IMP** (Imports) -- ordering, versioning, redundancy, deprecation
• **ORD** (Ordering) -- QML attribute ordering convention
• **BND** (Bindings) -- property var, imperative =, Qt.binding style
• **LAY** (Layout) -- anchors/Layout mixing, sizing in layouts
• **LDR** (Loader) -- status guards, createComponent, createQmlObject
• **DEL** (Delegates) -- required properties, reuse safety, connect()
• **STA** (States) -- PropertyChanges syntax, transitions, StateGroup
• **IMG** (Images) -- sourceSize, asynchronous loading
• **PRF** (Performance) -- transparent rect, opacity, clip, layer
• **STY** (Style) -- id:root, camelCase, group notation
• **SIG** (Signals) -- Connections target, handler syntax
• **ERR** (Error/Security) -- hardcoded http://, non-portable paths
• **JS** (JavaScript) -- var/let/const, loose equality

Phase 1b: System qmllint (optional)

Attempt to run `qmllint` if available on the system. Detection order:

1. `$QT_HOST_PATH/bin/qmllint` 2. `which qmllint` / `where qmllint` 3. Skip if not found (warn user)

If found, run with JSON output:

qmllint --json - -I <import-paths> <files...>

Parse the JSON output and merge with Python linter findings. Deduplicate by file+line+issue. qmllint is authoritative for type- level checks (unresolved types, incompatible assignments, alias cycles). The Python linter is authoritative for style, ordering, and performance patterns that qmllint does not cover.

Phase 2: Agent-driven deep analysis (6 parallel agents)

Launch six focused review agents in parallel. Name each agent descriptively when launching (e.g. "Agent 1: Bindings & Properties") to provide progress visibility. Each agent has a tight scope and a specific checklist. Agents are READ-ONLY -- they must never edit or write files.

**Tool-agnostic agent contract**: Each agent described below is a self-contained review mission. In Claude Code, launch them as general-purpose subagents. In other tools, implement each as whatever subprocess, prompt chain, or analysis pass the tool supports. The key requirement is that each agent:

• Has read access to all source files in scope
• Can search/grep the codebase to trace symbols
• Reports findings in the structured format below
• Applies confidence thresholds: >80 = confirmed finding,

60-79 = investigation target (max 10 total across all agents), <60 = suppress

• Does NOT duplicate findings from Phase 1 lint output

(pass lint output as context to each agent)

See **Agent missions** below for the six agents.

Phase 3: Consolidation and reporting

Merge lint script output, qmllint output (if available), and all agent findings. Deduplicate (same file+line+issue = one finding). Apply confidence scoring. Format the final report using the output format below.

Agent missions

Launch all six agents in parallel. Pass each agent: 1. The list of files in scope 2. The Phase 1 lint output (so they skip already-flagged issues) 3. The Phase 1b qmllint output if available 4. Their specific mission below

Each agent should read all