pyqgis-dev

PyQGIS Developer Skill — Expert-level guidance for QGIS 3.x Python development, designed for AI code generation.

This skill provides structured domain knowledge for generating correct, context-aware PyQGIS code across all major execution environments: Python Console, standalone scripts, Processing algorithms, and QGIS plugins.

---

Who is this for

• Developers building QGIS plugins, Processing algorithms, or standalone PyQGIS scripts
• AI coding agents (like Sisyphus / OpenCode) that generate PyQGIS code and need execution-context discipline, CRS/measurement correctness, and anti-pattern avoidance
• Code reviewers evaluating PyQGIS code for correctness, thread safety, and scenario consistency

---

Project structure

pyqgis-dev/
├── SKILL.md                         # Main entry — metadata, rules, file map
├── README.md                        # This file
├── README.zh.md                     # Chinese version
│
├── references/                      # Domain reference files
│   ├── cheat_sheet.md               # High-priority quick reference
│   ├── vector_recipes.md            # Vector layer operations
│   ├── raster_recipes.md            # Raster layer operations
│   ├── geometry_recipes.md          # Geometry creation, validation, spatial ops
│   ├── crs_recipes.md               # CRS, coordinate transforms, measurement
│   ├── measurement_recipes.md       # Length, area, distance, units
│   ├── expression_recipes.md        # QgsExpression, context, filtering
│   ├── processing_patterns.md       # Processing algorithm design & provider
│   ├── plugin_structure.md          # Plugin lifecycle, structure, i18n
│   ├── task_threading_recipes.md    # QgsTask, thread safety, background work
│   ├── maptool_canvas_recipes.md    # QgsMapTool, canvas interaction
│   ├── testing_ci_recipes.md        # pytest, fixtures, CI (Linux/macOS)
│   ├── testing_ci_recipes_windows.md # pytest, fixtures, CI (Windows)
│   ├── anti_patterns.md             # 18 common mistakes & corrections
│   └── version_policy.md            # QGIS version policy
│
├── templates/                        # Skeleton code templates
│   ├── standalone_script.py
│   ├── processing_alg.py
│   ├── processing_provider.py
│   ├── minimal_plugin/
│   │   ├── __init__.py
│   │   ├── main_plugin.py
│   │   └── metadata.txt
│   ├── prompt_scaffolds.md          # Structured prompt templates for AI
│   └── scenario_constraints.md      # Execution context rules & boundaries
│
└── checklists/                       # Quality gates
    ├── pyqgis_generation_checklist.md
    ├── scenario_selection_checklist.md
    └── regression_test_suite.md      # 10 core + 4 anti-pattern tests

---

Core capabilities

Area	Key files
Vector layers	loading, CRUD, filtering, spatial index, symbology, export
Raster layers	local, WMS/WCS/XYZ, PostGIS raster, pixel sampling
Geometry	creation, multipart, validation, spatial relationships, transforms
CRS & transforms	QgsCoordinateTransform, project vs layer CRS, reprojection
Measurement	QgsDistanceArea, ellipsoidal measurement, unit conversion
QgsExpression	context setup, feature binding, parser/eval errors, safe filtering
Processing	algorithm design, parameter types, sink/output, provider
Plugins	lifecycle, menu/toolbar, resources, i18n, Processing provider
Threading	QgsTask, thread boundaries, background compute, cancel
Map tools	QgsMapTool, canvas events, rubber band, click/selection tools
Testing & CI	pytest fixtures, qgis_app, iface mock, GitHub Actions, Docker
Anti-patterns	18 documented mistakes with wrong/right comparisons

---

Quick start

For AI agents

The top-level SKILL.md is the main entry point. Load it as a skill for any PyQGIS-related task. The cheat_sheet.md file is the highest-priority reference — it summarizes all critical constraints.

For developers

1. Start with cheat_sheet.md for a quick overview of all rules and pitfalls.
2. Navigate to the specific reference file matching your task (e.g., vector_recipes.md for layer operations).
3. Use the templates in templates/ to bootstrap new algorithms, plugins, or standalone scripts.
4. Run regression_test_suite.md to verify code generation quality after making changes.

For code reviewers

Use the checklists in checklists/ as a systematic review guide. The scenario_selection_checklist.md is particularly useful for catching execution-context mixing, which is the most common AI failure mode in PyQGIS code generation.

---

Key design decisions

• Scenario-first: Every code generation starts with execution context classification (Console / Standalone / Processing / Plugin). Context mixing is the #1 failure mode this skill is designed to prevent.
• Correctness over convenience: CRS semantics (setCrs vs coordinate transform), measurement (QgsDistanceArea vs raw geom.length()), and thread safety are non-negotiable.
• Anti-drift layers: Six defense layers — scenario constraints, prompt scaffolds, cheat sheet, anti-patterns, generation checklist, and regression test suite — work together to prevent common AI mistakes.
• Testability: Testing patterns are embedded alongside development patterns. Core logic should be separable from GUI/iface concerns and independently testable.

---

Version policy

This skill targets QGIS 3.x / PyQGIS 3.x. Minor version numbers (e.g., 3.44) are not hardcoded in references or templates unless version-specific API behavior requires it. See version_policy.md for details.