spatial
Answer questions about spatial data using DuckDB. Use when the user mentions locations, coordinates, lat/lng, distances, maps, addresses, "near", "within", "closest", geographic names, or spatial file formats (GeoJSON, Shapefile, GeoPackage, GPX, GeoParquet). Also triggers when the user wants to find places, buildings, or roads — Overture Maps provides free global data on S3 with zero API keys. Handles spatial joins, distance calculations, containment checks, density analysis, and format conversions for geographic data.
- Installs
- 725
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/duckdb/duckdb-skills --skill spatial- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads spatial automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
You are answering spatial questions using DuckDB's spatial extension and, when needed, Overture Maps as a free global data source.
Question or file: $0
Additional context: ${1:-}
Step 1 — Understand what the user needs
Classify the question:
| Pattern | Data source | Key functions |
|---|---|---|
| "Find X near Y" (no user file) | Overture Maps on S3 | ST_Distance_Spheroid, bbox filtering |
| "How far between A and B" | Geocode or user data | ST_Distance_Spheroid |
| "Which points fall inside polygons" | User files | ST_Contains |
| "Analyze this GeoJSON/Shapefile/GPX" | User file | ST_Read, measurement functions |
| "Show density/hotspots" | User or Overture data | H3 hex binning |
| "Convert to GeoJSON/GeoPackage" | User file | COPY TO (FORMAT GDAL) |
| "Count buildings/roads in area" | Overture Maps | bbox filtering + aggregation |
If the question involves real-world places, POIs, buildings, roads, or boundaries and the user hasn't provided a file, use Overture Maps — read references/overture.md for S3 paths and schema.
For spatial function syntax, read references/functions.md.
Step 2 — Write and run the query
Always start with:
LOAD spatial;
SET geometry_always_xy = true;
Add extensions as needed:
- Overture/remote data:
LOAD httpfs; CREATE SECRET (TYPE S3, PROVIDER config, REGION 'us-west-2'); - H3 hex binning:
INSTALL h3 FROM community; LOAD h3;
Key principles
bbox filtering first — When querying Overture, always filter on bbox.xmin/xmax/ymin/ymax before any spatial function. This uses Parquet predicate pushdown and avoids downloading the full dataset.
Always set geometry_always_xy = true — This ensures all spatial functions interpret coordinates as longitude, latitude (the standard for Overture, GeoJSON, and most data sources). Without it, spheroid functions assume latitude first and return wrong results.
Use spheroid functions for real-world distances — ST_Distance_Spheroid returns meters on the WGS84 ellipsoid. Plain ST_Distance uses planar coordinates and gives meaningless results for lat/lng. Important: spheroid functions (ST_Distance_Spheroid, ST_Area_Spheroid, etc.) require POINT_2D inputs, not generic GEOMETRY. Overture geometry columns are typed GEOMETRY('OGC:CRS84') and cannot be cast directly. Extract coordinates first:
ST_Point(ST_X(geometry), ST_Y(geometry))::POINT_2D
CSV with lat/lng needs conversion — ST_Point(longitude, latitude) (longitude first). This is the most common gotcha.
Run the query in a single bash call:
duckdb -c "
LOAD spatial;
<ADDITIONAL_SETUP>
<YOUR_QUERY>
"
Step 3 — Present results
- For tabular results: show the data directly
- For spatial results: consider exporting to GeoJSON for visualization (
COPY TO 'result.geojson' WITH (FORMAT GDAL, DRIVER 'GeoJSON')) - For distance/area results: use human-readable units (km for large distances, m for small)
- For density/hotspot results: describe the pattern and offer to export for visualization
If the query fails:
duckdb: command not found→ delegate to/duckdb-skills:install-duckdb- Missing extension →
INSTALL spatial; LOAD spatial;orINSTALL h3 FROM community; LOAD h3; - S3 access denied → suggest checking AWS credentials
- No results with Overture → widen the bbox, check the category spelling, or try a broader search
FAQ
What does the spatial skill do?
Answer questions about spatial data using DuckDB. Use when the user mentions locations, coordinates, lat/lng, distances, maps, addresses, "near", "within", "closest", geographic names, or spatial file formats (GeoJSON, Shapefile, GeoPackage, GPX, GeoParquet). Also triggers when the user wants to find places, buildings, or roads — Overture Maps provides free global data on S3 with zero API keys. Handles spatial joins, distance calculations, containment checks, density analysis, and format conversions for geographic data.
How do I install spatial?
Run npx skills add https://github.com/duckdb/duckdb-skills --skill spatial in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/spatial/ (personal) or .claude/skills/spatial/ (project).
Which AI agents can use spatial?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is spatial safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains spatial?
It is published by duckdb in duckdb/duckdb-skills. It has 725 recorded installs.
More from duckdb/duckdb-skills
query
duckdb/duckdb-skills
Run SQL queries against the attached DuckDB database or ad-hoc against files. Accepts raw SQL or natural language questions. Uses DuckDB Friendly SQL idioms.
duckdb-docs
duckdb/duckdb-skills
Search DuckDB and DuckLake documentation and blog posts. Returns relevant doc chunks for a question or keyword using full-text search against a locally cached index.
read-file
duckdb/duckdb-skills
Read any data file (CSV, JSON, Parquet, Avro, Excel, spatial, SQLite) or remote URL (S3, HTTPS). Use when user references a data file, asks "what's in this file", or wants to preview/profile a dataset. Not for source code.
attach-db
duckdb/duckdb-skills
Attach a DuckDB database file for use with /duckdb-skills:query. Explores the schema (tables, columns, row counts) and writes a SQL state file so subsequent queries can restore this session automatically via duckdb -init.
install-duckdb
duckdb/duckdb-skills
Install or update DuckDB extensions. Each argument is either a plain extension name (installs from core) or name@repo (e.g. magic@community). Pass --update to update extensions instead of installing.
read-memories
duckdb/duckdb-skills
Search past Claude Code session logs to recall prior decisions, patterns, or unresolved work. Use when user says "do you remember", "what did we do", references past conversations, or you need context from prior sessions.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.