Sea Route Navigation Skill

Generate the shortest sea route between two points on the globe. Returns navigation waypoints (coordinates) and an interactive HTML map visualization.

When to Use

• User asks for a sea/shipping/maritime route between two locations
• User wants port-to-port distance or travel time estimate
• User needs navigation waypoints for maritime routing
• User wants a visual map of a shipping lane

How It Works

This skill uses a Python script (scripts/sea_route.py) powered by the searoute library. It computes the shortest path over ocean, avoids land masses, and outputs:

1. Waypoint coordinates (longitude, latitude) printed to stdout as JSON
2. An interactive HTML map saved to a user-specified path (default: ./sea_route_map.html)

The script uses uv for dependency management — no manual pip install needed.

Usage

Step 1 — Resolve user input to coordinates

The user may provide:

• City / port names (e.g., "天津" and "大阪", "Rotterdam" and "Singapore")
• Coordinates directly (e.g., [117.75, 38.99])

If the user provides city or port names, you MUST convert them to [longitude, latitude] coordinates yourself before calling the script. Use well-known port coordinates:

For ports not listed above, look up reasonable coordinates for the port area.

Step 2 — Run the script

Run with uv:

uv run --script /path/to/skills/sea-route/scripts/sea_route.py \
  --origin-lon <LON> --origin-lat <LAT> \
  --dest-lon <LON> --dest-lat <LAT> \
  --origin-name "Port A" --dest-name "Port B" \
  --output ./sea_route_map.html

Parameters:

Step 3 — Present results to user

The script prints a JSON object to stdout with this structure:

{
  "origin": {"name": "Tianjin", "lon": 117.75, "lat": 38.99},
  "destination": {"name": "Osaka", "lon": 135.25, "lat": 34.65},
  "distance_km": 1891,
  "duration_hours": 42.5,
  "waypoints": [
    {"seq": 1, "lon": 118.1725, "lat": 38.7726},
    ...
  ],
  "html_map": "./sea_route_map.html"
}

Present to the user:

1. A summary: origin → destination, distance, estimated time
2. The waypoint coordinate table
3. Tell them the HTML map file path and offer to open it

Step 4 — Open the map (optional)

If the user wants to see the map:

open ./sea_route_map.html    # macOS
xdg-open ./sea_route_map.html  # Linux

Example Interaction

User: 帮我生成从天津到大阪的海运航线

Agent:

1. Resolve: 天津港 → [117.75, 38.99], 大阪港 → [135.25, 34.65]
2. Run:

uv run --script ~/.agents/skills/sea-route/scripts/sea_route.py \
  --origin-lon 117.75 --origin-lat 38.99 \
  --dest-lon 135.25 --dest-lat 34.65 \
  --origin-name "天津港" --dest-name "大阪港" \
  --output ./tianjin_osaka_route.html

3. Parse JSON output, present waypoints and summary
4. Open the HTML map

Notes

• The searoute library generates approximate maritime routes suitable for visualization and distance estimation. It is NOT intended for real navigation.
• Coordinates use [longitude, latitude] order (GeoJSON convention).
• The script requires uv to be installed. It uses inline script dependencies — no virtual environment setup needed.
• Estimated speed is ~25 knots (typical cargo vessel cruising speed).