An OpenStreetMap-first site analysis skill for Codex-style workflows. This repository packages the skill definition, supporting references, lightweight Python scripts, and tests needed to resolve a site, fetch context, run quality checks, and generate report-ready artifacts.

• Resolves a site from a place query or a latitude/longitude pair
• Fetches OSM-first context from Nominatim and Overpass
• Routes analysis to the minimum required module: traffic, hydrology, land-use, or site-context
• Runs lightweight quality checks and assigns a confidence level
• Produces a canonical structured result, Markdown report, and SVG static map

The skill is designed for early-stage analysis, not survey-grade or legal deliverables.

osm-site-analysis/
├── SKILL.md
├── README.md
├── references/
│ ├── data-sources.md
│ ├── output-contract.md
│ ├── pressure-scenarios.md
│ └── quality-rules.md
├── scripts/
│ ├── fetch_osm_context.py
│ ├── check_quality.py
│ ├── render_static_map.py
│ ├── run_site_analysis.py
│ └── smoke_test_live_api.py
└── tests/
 ├── test_osm_site_analysis_scripts.py
 └── test_osm_site_analysis_smoke.py

Clone or copy this folder into your Codex skills directory as:

~/.codex/skills/osm-site-analysis

Then invoke the skill when a task involves site analysis from a place, boundary, or coordinates and needs OSM-first context, cross-source validation, confidence-aware conclusions, or static map output.

The scripts use the Python standard library only.

python3 scripts/fetch_osm_context.py \
 --query "Colosseum, Rome" \
 --module traffic \
 --output out/context.json

You can also use coordinates:

python3 scripts/fetch_osm_context.py \
 --lat 41.8902 \
 --lon 12.4922 \
 --module site-context \
 --output out/context.json

Optional --south --west --north --east values can be added to override the analysis extent around a query or point input.

python3 scripts/check_quality.py \
 --input out/context.json \
 --output out/quality_report.json

python3 scripts/render_static_map.py \
 --input out/context.json \
 --output out/map.svg

python3 scripts/run_site_analysis.py \
 --query "Colosseum, Rome" \
 --module traffic \
 --output-dir out/rome-traffic \
 --title "Colosseum Traffic Analysis"

This pipeline writes:

• structured_result.json
• quality_report.json
• report.md
• map.svg

Run the local test suite:

python3 -m unittest discover -s tests

Run the live API smoke test only when you want real network verification:

OSM_LIVE_SMOKE=1 python3 -m unittest tests.test_osm_site_analysis_smoke

The smoke test calls live Nominatim and Overpass services, so it should be used sparingly.

• Network access is required for fetch_osm_context.py, run_site_analysis.py without --input, and the live smoke test.
• The generated confidence level is heuristic and intended to help scope follow-up validation, not replace it.
• The skill favors structured evidence, explicit warnings, and conservative claims when data quality is weak.