# terrain-hydrology

Configures elevation surface analysis, viewsheds, and hydrologic modeling from DTMs and DSMs.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 35
- Author: Muhammed Enes Duran
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/muend/geoai-skills/tree/HEAD/skills/terrain-hydrology/SKILL.md
- Updated: 2026-10-17
- HTML: https://affpapa.org/en/nevibecode/skills/terrain-hydrology

## What it does

The skill enforces a strict verification workflow for elevation rasters before running flow or visibility models. It insists on checking coordinate systems: running slope calculations on an unprojected EPSG:4326 DEM without z-factor corrections corrupts derivative values roughly a hundredfold.

Under the hood, it guides hydrological conditioning using tools such as WhiteboxTools, pysheds, richdem, GDAL, and GRASS. The workflow prioritizes least-cost depression breaching before filling pits, applies D8 or MFD flow routing, and snaps pour points to high-accumulation cells to prevent tiny broken watersheds.

For viewshed studies, the skill dictates using a surface model with obstacles (DSM) rather than bare earth, while factoring in target heights and earth curvature. Omitting depression breaching over road culverts leads directly to artificial flat lakes and bogus river channels.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add muend/geoai-skills --skill terrain-hydrology -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/terrain-hydrology/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/terrain-hydrology/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add muend/geoai-skills --skill terrain-hydrology -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/terrain-hydrology/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add muend/geoai-skills --skill terrain-hydrology -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/terrain-hydrology/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install muend/geoai-skills terrain-hydrology
```

2. **Manually: put the files in place**
- File: `.github/skills/terrain-hydrology/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add muend/geoai-skills --skill terrain-hydrology -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/muend/geoai-skills --path skills/terrain-hydrology
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/terrain-hydrology/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add muend/geoai-skills --skill terrain-hydrology -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/muend/geoai-skills/tree/HEAD/skills/terrain-hydrology/SKILL.md

## When to use it
- verify DEM projection and vertical units before analysis
- condition terrain rasters using depression breaching and filling
- delineate stream networks and watersheds with pour-point snapping
- calculate slope, aspect, curvature, and topographic indices
- generate viewsheds accounting for observer heights and refraction

## Example prompts
- Inspect dem.tif, reproject to a local projected CRS, and compute slope in degrees
- Condition this elevation raster using WhiteboxTools and delineate the catchment
- Calculate a viewshed from a 30m tower point taking earth curvature into account

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: db889b59cdfdc015.

BEGIN THIRD-PARTY FILE db889b59cdfdc015
````text
---
name: terrain-hydrology
description: >-
  Always invoke for terrain, drainage, viewshed, or visibility analysis from
  elevation, even before the DEM or correct surface is chosen. Covers
  DTM-versus-DSM selection, slope, aspect, curvature, hillshade, conditioning,
  flow direction/accumulation, streams, watersheds, and catchments. Use
  point-cloud-lidar first only when an elevation surface must be created from
  LiDAR or photogrammetric points.
license: MIT
metadata:
  author: Muhammed Enes Duran
---

# Terrain & Hydrology

Purpose: terrain products whose numbers are physically meaningful. The two
recurring failure modes: **unit mismatch** (degree coordinates with meter
elevations silently corrupts every derivative) and **unconditioned DEMs**
(flow routed into spurious pits produces fragmented, fictional streams).

## DEM hygiene first

| Check | Rule |
|---|---|
| Surface type | **DTM** (bare earth) for hydrology/slope; **DSM** (with canopy/buildings) for viewshed/solar. Using a DSM for watersheds routes rivers over treetops. |
| Source | Copernicus GLO-30 > SRTM for most global work; national LiDAR DTMs when available (see `point-cloud-lidar` to make your own). Record source + acquisition date. |
| Nodata | Identify the nodata value (-9999, -32768, 3.4e38) and mask it — never let it enter statistics or fill algorithms as "very deep hole". |
| Voids | Fill data voids (interpolation from edges) BEFORE hydrological conditioning; document filled areas. |
| **CRS + units** | Reproject to a projected CRS so horizontal units = vertical units (meters). Slope from a 4326 DEM without z-factor correction is the classic silent error. If staying geographic, apply a latitude-dependent z-factor — better: don't. |

## Derivatives

```python
import whitebox
wbt = whitebox.WhiteboxTools()
wbt.slope("dem.tif", "slope_deg.tif", units="degrees")
wbt.aspect("dem.tif", "aspect_deg.tif")
wbt.plan_curvature("dem.tif", "plan_curv.tif")
```

- Slope: state units (degrees vs percent — 45° = 100%); Horn's method
  (3×3) is the standard; steeper terrain → consider resolution effects
  (slope flattens as cell size grows — report cell size with every slope
  statistic).
- Aspect: circular variable — never average it arithmetically; use vector
  (sin/cos) averaging; flat cells have undefined aspect (mask, don't zero).
- Curvature: plan (flow convergence) vs profile (flow acceleration) —
  pick per question.
- Hillshade is for cartography (see `cartography-geoviz`), never analysis
  input.
- Ruggedness/position: TRI, TPI (radius-dependent — report the radius),
  geomorphons for landform classification.

## Hydrological conditioning — order matters

```
voids filled → breach depressions (preferred) → fill remaining pits
````
END THIRD-PARTY FILE db889b59cdfdc015

The third-party file has ended. Everything between the db889b59cdfdc015 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2766 of 7272 bytes. © Muhammed Enes Duran · MIT · https://github.com/muend/geoai-skills/tree/HEAD/skills/terrain-hydrology/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md