hex-grid-spatial — Claude Code skill: hex grid distances and neighbours
hex-grid-spatial is a Claude Code skill that calculates neighbours, hex distance, and radius cells on odd-r offset maps for movement or area-of-effect logic.
Apache-2.0 1 installs ★ 1,933 updated 2026-10-24
npx skills add benchflow-ai/skillsbench --skill hex-grid-spatial -a claude-codeWhat hex-grid-spatial does
The skill hands the agent three Python helpers for a hex map. Coordinates follow the odd-r offset scheme: rows with an odd index sit half a tile further right, counting starts at the bottom-left tile, columns grow rightward and rows upward.
Neighbours come from a six-entry direction table. On odd rows four of those entries shift by one column compared with even rows, while east and west stay put. Get the parity wrong and the neighbour list lands on the wrong column, so a map stored in another layout has to be converted to odd-r first.
Distance converts both tiles to cube coordinates and returns the step count between them. The radius helper scans a square around the centre and keeps only tiles that pass the distance check, which gets costly on large radii.
What it helps with
- list the six tiles touching a hex
- measure how many steps separate two tiles
- collect every tile within a radius of a city
- test whether two tiles share an edge
- convert offset coordinates to cube form for distance math
Example prompts for the agent
- List the six neighbours of tile (21, 13) on the hex map
- How many hexes between (21, 13) and (24, 13)? Use the hex distance helper
- Give me every tile within 3 of (21, 13), centre excluded
How to install hex-grid-spatial
1Skills CLI (Vercel)
npx skills add benchflow-ai/skillsbench --skill hex-grid-spatial -a claude-code2Manually: put the files in place
~/.claude/skills/hex-grid-spatial/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/hex-grid-spatial/
1Skills CLI (Vercel)
npx skills add benchflow-ai/skillsbench --skill hex-grid-spatial -a codex2Manually: put the files in place
.agents/skills/hex-grid-spatial/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add benchflow-ai/skillsbench --skill hex-grid-spatial -a cursor2Manually: put the files in place
.cursor/skills/hex-grid-spatial/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install benchflow-ai/skillsbench tasks/civ6-adjacency-optimizer/environment/skills/hex-grid-spatial2Manually: put the files in place
.github/skills/hex-grid-spatial/SKILL.md1Skills CLI (Vercel)
npx skills add benchflow-ai/skillsbench --skill hex-grid-spatial -a gemini-cli2Platform CLI
gemini skills install https://github.com/benchflow-ai/skillsbench --path tasks/civ6-adjacency-optimizer/environment/skills/hex-grid-spatialManually: put the files in place
.devin/skills/hex-grid-spatial/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add benchflow-ai/skillsbench --skill hex-grid-spatial -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about hex-grid-spatial
How do I install hex-grid-spatial in Claude Code?
Run npx skills add benchflow-ai/skillsbench --skill hex-grid-spatial -a claude-code. The skill file lands at ~/.claude/skills/hex-grid-spatial/SKILL.md.
What does hex-grid-spatial do?
It gives the agent helpers for a hex map: the six neighbours of a tile, the distance between two tiles, and every tile inside a radius. Coordinates are odd-r offset.
Which grid layout does it support?
Odd-r offset only, where odd rows are shifted right. On any other layout the neighbours and distances come out wrong, so the map has to be converted first.
Source text
SKILL.md · Apache-2.0
---
name: hex-grid-spatial
description: Hex grid spatial utilities for offset coordinate systems. Use when working with hexagonal grids, calculating distances, finding neighbors, or spatial queries on hex maps.
---
# Hex Grid Spatial Utilities
Utilities for hexagonal grid coordinate systems using **odd-r offset coordinates** (odd rows shifted right).
## Coordinate System
- Tile 0 is at bottom-left
- X increases rightward (columns)
- Y increases upward (rows)
- Odd rows (y % 2 == 1) are shifted right by half a hex
## Direction Indices
```
2 1
\ /
3 - * - 0
/ \
4 5
0=East, 1=NE, 2=NW, 3=West, 4=SW, 5=SE
```
## Core Functions
### Get Neighbors
```python
def get_neighbors(x: int, y: int) -> List[Tuple[int, int]]:
"""Get all 6 neighboring hex coordinates."""
if y % 2 == 0: # even row
directions = [(1,0), (0,-1), (-1,-1), (-1,0), (-1,1), (0,1)]
else: # odd row - shifted right
directions = [(1,0), (1,-1), (0,-1), (-1,0), (0,1), (1,1)]
return [(x + dx, y + dy) for dx, dy in directions]
```
### Hex Distance
```python
def hex_distance(x1: int, y1: int, x2: int, y2: int) -> int:
"""Calculate hex distance using cube coordinate conversion."""
def offset_to_cube(col, row):
cx = col - (row - (row & 1)) // 2
cz = row
cy = -cx - cz
return cx, cy, cz
cx1, cy1, cz1 = offset_to_cube(x1, y1)
cx2, cy2, cz2 = offset_to_cube(x2, y2)
return (abs(cx1-cx2) + abs(cy1-cy2) + abs(cz1-cz2)) // 2
```
### Tiles in Range
```python
def get_tiles_in_range(x: int, y: int, radius: int) -> List[Tuple[int, int]]:
"""Get all tiles within radius (excluding center)."""
tiles = []
for dx in range(-radius, radius + 1):
for dy in range(-radius, radius + 1):
nx, ny = x + dx, y + dy
if (nx, ny) != (x, y) and hex_distance(x, y, nx, ny) <= radius:
tiles.append((nx, ny))
return tiles
```
## Usage Examples
```python
# Find neighbors of tile (21, 13)
neighbors = get_neighbors(21, 13)
# For odd row: [(22,13), (22,12), (21,12), (20,13), (21,14), (22,14)]
# Calculate distance
dist = hex_distance(21, 13, 24, 13) # Returns 3
# Check adjacency
is_adj = hex_distance(21, 13, 21, 14) == 1 # True
# Get all tiles within 3 of city center
workable = get_tiles_in_range(21, 13, 3)
```
## Key Insight: Even vs Odd Row
The critical difference is in directions 1, 2, 4, 5 (the diagonal directions):
| Direction | Even Row (y%2==0) | Odd Row (y%2==1) |
|-----------|-------------------|------------------|
| NE (1) | (0, -1) | (1, -1) |
| NW (2) | (-1, -1) | (0, -1) |
| SW (4) | (-1, +1) | (0, +1) |
| SE (5) | (0, +1) | (1, +1) |
East (0) and West (3) are always (1, 0) and (-1, 0).
© benchflow-ai · Apache-2.0 · benchflow-ai/skillsbench