科研 Skill
QGIS自动化地理处理
qgis-agent
Drives QGIS (PyQGIS, processing, GDAL) for GIS/remote sensing tasks: raster/vector ops, spectral indices, reprojection, zonal statistics, map layouts. Use for any QGIS-based geospatial task.
SKILL.md
Working in QGIS as an agent
You drive QGIS through its Python engine (PyQGIS and the processing algorithms), not by clicking. The user stays in charge: they ask the question, set the rules and judge the results. Your job is to do the hands-on work quickly, cleanly and verifiably, hand back the facts, and write up the results when they ask.
The cycle below has been proven on real projects. Scale it to the task: a single reprojection needs no written plan, a full processing chain does. Always answer in the user's language.
1. Get to know the project
- Read the project's rules file if there is one (
CLAUDE.mdfor Claude Code,AGENTS.mdfor Codex and most other agents), then the assignment or instructions (often insources/). Note the formulas, class intervals, units, required map elements and deliverables. These are constraints, not suggestions. - If there is none, propose one based on
assets/project_rules_template.md, saved under the name your agent reads (CLAUDE.mdorAGENTS.md), filled in with what you already know (QGIS version, CRS, resolution), and get it approved. It saves repeating the same rules every session. - If the request is vague (missing area, period or deliverables), offer to complete it with
assets/request_template.mdrather than guessing. - Inventory the data with
scripts/check_data.py: CRS, pixel size, extent, nodata and value range for rasters; CRS, geometry type, feature count and area for vectors. If satellite bands are already in the folder, also runscripts/check_imagery.pyon them (see the imagery rules below). - Never modify the original data (
data/raw/or equivalent). Work on copies: if a step goes wrong, you restart from the source without downloading anything again.
Suggested layout for an empty folder:
project/
├── sources/ assignment, papers
├── data/raw/ original data
├── data/ prepared data
├── scripts/ numbered steps
├── outputs/ rasters, maps, tables
└── AGENTS.md project rules (CLAUDE.md for Claude Code)
2. Find QGIS's Python
Scripts must run with the Python that ships with QGIS, otherwise qgis.core and processing cannot be found.
- macOS and Linux:
bash <skill>/scripts/qgis_python.sh --infoprints the QGIS and GDAL versions.bash <skill>/scripts/qgis_python.sh my_script.py argsruns a script in the right environment, with no window. - Windows: look for
python-qgis.batorpython-qgis-ltr.batinC:\Program Files\QGIS *\bin\orC:\OSGeo4W\bin\, and run scripts with it (python-qgis-ltr.bat my_script.py args). It sets up the environment, but leaves the Processing plugin off the Python path:scripts/pyqgis_template.pyadds it fromQgsApplication.pkgDataPath(), so start step scripts from the template. - If your commands run in a sandbox (Codex, or Claude Code with sandboxing on), the download scripts need network access to the hosts listed in the README: ask the user to approve it rather than working around the block.
qgis_process, installed with QGIS, runs a single algorithm from the command line (qgis_process run native:reprojectlayer -- INPUT=... TARGET_CRS=EPSG:32630 OUTPUT=...). Handy for a one-off operation.
Start every new step from scripts/pyqgis_template.py: it contains the headless start-up (QgsApplication and Processing) and saves the project with relative paths. On older QGIS versions (3.28 and earlier) some API names differ: see the end of references/pyqgis.md.
3. Propose a plan and wait for approval
Before running a multi-step task, present a short plan:
- the steps, each with its QGIS equivalent: the menu path and the algorithm id (for example Raster > Raster Calculator,
native:zonalhistogram); - the CRS, the resolution and the area the calculations cover;
- the files that will be created;
- open questions, and any planned deviation from the assignment.
Wait for approval. Fixing a plan takes a minute; fixing a chain that has already run takes half an hour, and the user must be able to defend each of these choices in front of someone else.
If the user asks "how do I do it?", offer both routes: you run the chain with this method, or you guide them menu by menu in QGIS. The plan, the tools, the imagery rules below and the checks are the same either way.
4. Run it end to end
- One step, one numbered script in
scripts/(01_area.py,02_images.py...), rerunnable, with its parameters at the top and paths relative to the project root. This is what lets the user redo everything on another date or another area with one sentence. - Use the QGIS tools the assignment names (raster calculator, reclassify by table, zonal histogram, print layout...) rather than a home-made calculation: the user must be able to redo the step by hand in the menus and get the same result. Write the menu path in a comment.
- Apply the assignment's formulas and intervals exactly as given. If one looks wrong, say so; do not silently fix it.
- For imagery, read only the area you need (windowed reads of COG files) and run long downloads in the background while you write the next step.
- Save the
.qgzproject with relative paths, layer styles and print layouts. Also export each style as a.qmlinstyles/so it can be reused. - Keep a short
journal.md: each user request, the decisions taken and why. It is the record of the method, useful when the user writes up. - If a bundled script fails, read its message: it says what to do. Fix the cause or tell the user. Do not swap in home-made code or another data source without checking its values against the reference ranges below; a quiet workaround can produce wrong results that look fine.
Satellite imagery rules, to apply in every plan (details in references/remote_sensing.md):
- Find and download Sentinel-2 with
scripts/s2_search.pyandscripts/s2_download.py: open catalogue, no account, only the needed extent, clouds and coverage measured over the area itself. Prefer them to sending the user to a download portal. If the user wants to download by hand, name the product (level 2A) and the bands. - Use reflectance, not raw values: apply the scale and offset from the band metadata (usually value × 0.0001 − 0.1), unless the metadata says the offset is already applied (see imagery already in the folder, below).
- Indices that use B11 or B12 (NDMI, NBR, MNDWI, NDBI) are computed at 20 m: average the 10 m bands down to 20 m. Never resample the 20 m bands up to 10 m, which creates detail that is not in the data. Pixel area at 20 m: 0.04 ha.
- Take all tiles from the same pass (same date), and pick a date whose tiles cover the whole area.
- If the image files cannot be reached (network, firewall or sandbox), the scripts say so: rerun both with
--collection sentinel-2-l2a, a mirror stored on another host. Never read that mirror with your own code: its values already include the −0.1 offset (earthsearch:boa_offset_applied: true) while its metadata still declares it, so subtracting it again makes every band 0.1 too low and skews every index. The scripts handle this. - Imagery already in the folder (sent by the user or a classmate, downloaded by hand, from another tool or catalogue) never went through the download scripts, so their protections do not apply. Before any calculation, run
scripts/check_imagery.py <folder>(with--areaand the study area if there is one), and put the formula it prints and its evidence in the plan. The rules it applies, which hold even if you read the files yourself:- STAC item (
item.json): readearthsearch:boa_offset_appliedbeforeraster:bands. If it istrue, reflectance = value × 0.0001, whatever offsetraster:bandsdeclares. - ESA metadata (
MTD_MSIL2A.xml): reflectance = (value +BOA_ADD_OFFSET) /BOA_QUANTIFICATION_VALUE; with noBOA_ADD_OFFSET, value / 10000. - No metadata: level 2A bands acquired after 25 January 2022 carry the −1000 offset. Assume it, say so in the plan and the report, and check the raw values: if more than 1 % of a visible band is below 1000, those pixels would come out negative, so the offset is already applied or absent; ask where the files come from. For older dates it depends on the processing (the reprocessed archive has the offset): the raw values may rule it out, otherwise ask.
- STAC item (
- Sanity check before computing indices: with the chosen formula, almost no pixel of a visible band (B02, B03, B04) should be negative. Dark targets (vegetation in red and blue, water, shadow) go negative when the offset is subtracted twice. Bright ground hides the error: with no raw value below 1000, both formulas give plausible reflectance, the pixels cannot tell them apart, and only the metadata decides. A plausible result is not a check. A median visible reflectance below 0.03 over land also points to a double offset.
- A scene without a mask band (SCL or similar) is never averaged as it is. Measure the cloud share over the area (
check_imagery.pyestimates it from B02 and B04, as a lower bound), report it with the result, and mask the clouds before giving a mean or a share: with the SCL band if you can get it, otherwise with the estimate, saying so. Without a blue band, look at a composite of the scene and ask for the mask band.
Read references/pyqgis.md before writing PyQGIS code: tested recipes (raster calculator, discrete symbology, reclassification, zonal histogram, print layout, legend, scale bar, interface screenshots) and known pitfalls. Read references/remote_sensing.md as soon as satellite imagery is involved: bands, reflectance, clouds, index formulas, open data sources, licences.
5. Show evidence
Do not say "done" without showing:
- a PNG preview of each map (layout export at 100 or 150 dpi), which you look at yourself before presenting it;
- the key figures (means, areas, percentages) in a small table;
- the value range of each raster produced.
If the user wants to learn to redo a step by hand, open QGIS with the tool pre-filled and take a screenshot (see "Interface screenshots" in references/pyqgis.md).
6. Check before handing over
Calculations are rarely wrong; assumptions are wrong more often. Before handing over a result, go through this list. scripts/check_data.py and scripts/check_project.py cover part of it.
- CRS and pixel size of every layer, and the right UTM zone.
- Plausible ranges: normalised index within [−1, 1], reflectance within [0, 1] after scaling.
- Class areas add up to the area total (pixel count × pixel area).
- Areas cover the study area, not the image's bounding rectangle.
- All tiles come from the same date; no mixing of 10 m and 20 m bands without explicit resampling.
- The reflectance formula comes from the metadata, or is stated as an assumption; the cloud share over the area is measured (from the mask band, or estimated) and reported.
- Discrete symbology: QGIS expects the upper bound of each class.
- Statistics and regressions computed in float64 (in float32 a slope can be wrong with no error message).
- Every surprising result looked at on a natural colour composite (B04, B03, B02).
- The
.qgzproject reopened from scratch: valid layers, styles and layouts present, legends limited to the intended layers. - When a result matters, one step recomputed another way (numpy against the raster calculator, for example) and compared pixel by pixel.
End with the list of deviations from the assignment and unchecked assumptions. The user must know them before handing anything in.
7. Corrections
One remark at a time. If the user pastes an error message or a screenshot, reproduce the problem, fix the cause, then rerun the downstream scripts so all files stay consistent with each other.
8. Hand over a work report, then write more if asked
At the end, produce a factual work report, like a lab notebook, following references/work_report.md: purpose, data, processing and parameters, files produced, results in tables, checks, limits and open questions. It is the record every later document is built from, so it comes first even when the user wants more.
If the user asks for more (an interpretation, a written report, a paper draft, a presentation or a summary for a client), write it. Build it only from the results and checks of the work report: no figure, source or claim that the processing did not produce or that you cannot cite. Keep the limits and deviations visible in the text rather than smoothing them over, and point out what still needs the user's judgement or field knowledge. Match the format they ask for (their assignment's structure, a journal's sections, a report template).
Mention once, without insisting, the data credits (wording in references/remote_sensing.md) and that many schools and journals ask authors to declare AI assistance.
Skill files
| File | When to use it |
|---|---|
scripts/qgis_python.sh | Run a script with QGIS's Python (macOS, Linux) |
scripts/pyqgis_template.py | Starting point for each step script |
scripts/check_data.py | Data inventory and output checks |
scripts/check_project.py | Reopen a .qgz from scratch and list what it contains |
scripts/check_imagery.py | Imagery already in a folder: reflectance formula and evidence, clouds without a mask band |
scripts/s2_search.py | Find clear Sentinel-2 dates over an area |
scripts/s2_download.py | Download bands as reflectance, for the needed extent only |
references/pyqgis.md | Before writing PyQGIS code |
references/remote_sensing.md | As soon as satellite imagery is involved |
references/work_report.md | For the final work report |
assets/project_rules_template.md | Project rules to propose |
assets/request_template.md | To complete a vague request |
示例提示词
帮我在QGIS里对这个.qgz工程跑缓冲区分析并输出工作报告。
所属插件
安装该插件会一并获得同领域的 18 个 Skill / MCP。
同插件的其他科研 Skill
- OpenAQ空气质量分析Accesses OpenAQ air quality data (PM2.5, O3, NO2), runs spatial interpolation, health exposure indices, city comparisons. Use for air pollution monitoring and exposure analysis.
- Copernicus气候数据下载Downloads climate/weather data from the Copernicus Climate Data Store (ERA5, seasonal forecasts) via cdsapi, covering API setup and request splitting. Use for any CDS/ECMWF download.
- 气候趋势检验分析Runs climate trend analysis: Mann-Kendall test, Sen’s slope, extreme indices (RX1day, R10mm), percentile thresholds, IPCC-style figures. Use to detect and visualize climate trends.
- 生态多样性群落分析Computes community-ecology diversity metrics and ordination: Shannon/Simpson indices, rarefaction, NMDS/PCoA, PERMANOVA. Use when analyzing species-by-site community composition data.
- ERA5再分析气候数据Downloads and analyzes ERA5 reanalysis data via the Copernicus CDS API: anomalies, trends, publication-quality climate maps. Use for ERA5-specific climate analysis end to end.
- GBIF物种分布建模Queries GBIF occurrence records, applies spatial thinning, and fits species distribution models (MaxEnt, BRT) with pygbif/geopandas/elapid. Use for occurrence and habitat-suitability analysis.
- 综合地理空间科学分析Covers broad geospatial workflows: satellite imagery, vector/raster GIS, spatial ML, point clouds, cloud-native formats (STAC, COG). Use as a general entry point for remote sensing or GIS tasks.
- GeoPandas矢量GIS分析Performs vector GIS analysis with GeoPandas: spatial joins, overlays, buffer/dissolve, choropleth maps, rasterio integration. Use for vector spatial analysis and raster-vector workflows.
- DEM水文地貌分析Runs DEM-based hydrological analysis with pysheds: watershed delineation, flow direction/accumulation, stream networks, runoff estimation. Use for terrain-driven hydrology modeling.
- 海洋碳酸盐化学Computes seawater carbonate chemistry with PyCO2SYS: pH, pCO2, aragonite/calcite saturation, air-sea CO2 flux. Use for ocean carbon-cycle and acidification analysis.
- MetPy大气探空分析Performs atmospheric analysis with MetPy/Siphon: downloads NWP data, plots skew-T log-P diagrams, computes CAPE/CIN, builds synoptic composites. Use for weather-sounding meteorology analysis.
- 地震波形数据处理Analyzes seismological data with ObsPy: waveform download, filtering, P/S phase picking, moment magnitude, spectral analysis. Use for earthquake and seismic-waveform analysis.
- 海洋再分析数据分析Downloads and analyzes oceanographic data from Copernicus Marine Service and Argo floats with gsw/xarray: mixed layer depth, eddy kinetic energy, T-S diagrams. Use for physical oceanography.
- 物理海洋学论文绘图绘制物理海洋学论文图:区域/全球/极地地图、多面板、垂向剖面、Hovmöller图、cmocean配色与期刊版式。投稿级海洋学图件排版和配色时使用。
- 种群动态建模Models population dynamics with logistic/exponential growth, Lotka-Volterra, matrix population models, mark-recapture abundance estimation. Use for quantitative population ecology.
- 多光谱遥感影像处理Reads, reprojects, and analyzes multispectral GeoTIFF imagery with rioxarray/rasterio: NDVI/EVI, cloud masking, mosaicking, Cloud-Optimized GeoTIFF export. Use for raster remote-sensing processing.
- Google Earth Engine卫星分析Runs Google Earth Engine satellite analysis with geemap/ee: NDVI time series, land-cover classification, change detection, GeoTIFF export. Use for cloud-based large-scale satellite analysis.
常见问题
QGIS自动化地理处理能做什么?
Drives QGIS (PyQGIS, processing, GDAL) for GIS/remote sensing tasks: raster/vector ops, spectral indices, reprojection, zonal statistics, map layouts. Use for any QGIS-based geospatial task。
如何安装QGIS自动化地理处理?
在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「QGIS自动化地理处理」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。
QGIS自动化地理处理需要哪些权限?
该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。
QGIS自动化地理处理经过官方审核吗?
是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。