Surf Forecast Agent

intent

this skill ranks the top 3 surf spots in a user-specified region by evaluating wave height, wind speed, and wind direction against a defined scoring rubric. use it when a surfer asks for the best breaks in an area right now. the skill fetches live surfline data, scores every valid spot in the region on the agent side (not in the data collection script), and returns ranked recommendations with transparent scoring and reasoning.

inputs

surfline data source:

• surfline API access via surfline_region_report.py script (local python script, no auth required if script is pre-authenticated)
• script location: must be in the agent's execution PATH or specified as absolute path
• supported preset regions: north-orange-county, south-orange-county, san-diego, santa-cruz
• custom regions: user must provide surfline spot IDs (comma-separated string format)

user parameters:

• region (string): preset region name or "custom"
• spots (string, optional): comma-separated surfline spot IDs if region is unsupported
• hours (integer, optional): forecast window in hours; default to 24 if not specified
• local_break_orientation (string, optional): user-provided wind direction preference for a specific break (overrides default directional rubric)

time context:

• current timestamp (for validity checking of forecast data)

procedure

1. validate region input:

   • input: user-provided region string
   • if region matches a preset (north-orange-county, south-orange-county, san-diego, santa-cruz), proceed to step 2
   • if region is unsupported, ask user for surfline spot IDs and jump to step 2b
   • output: confirmed region or spot ID list

2. fetch spot data from surfline:

   • input: region name or spot ID list, hours parameter (default 24)
   • execute: python3 surfline_region_report.py --region <region> --hours <hours> --output json (preset) OR python3 surfline_region_report.py --spots "<spotId1,spotId2,...>" --hours <hours> --output json (custom)
   • output: JSON response containing spots[] array; each spot object includes spotId, avgSurfMinFt, avgSurfMaxFt, avgPrimarySwellFt, avgWindMph, avgWindDirectionDeg, avgTideFt, validHours

2b. handle custom spot IDs:

• input: user-provided spot ID string
• execute same script command as step 2 using --spots flag instead of --region
• output: same JSON structure as step 2

3. parse and validate spot data:

   • input: JSON response from step 2 or 2b
   • iterate spots[] array
   • for each spot, confirm presence of: spotId, avgSurfMaxFt, avgWindMph, avgWindDirectionDeg
   • exclude any spot with missing required fields; note excluded spots in final output
   • output: validated spot list with all required fields

4. compute wave height score (0-10, relative within region):

   • input: validated spot list, avgSurfMaxFt for all spots
   • find minWaveMax and maxWaveMax across all spots
   • if minWaveMax == maxWaveMax (all spots identical wave height), assign waveScore = 5.0 to all spots
   • else: for each spot, compute waveScore = 10 * (avgSurfMaxFt - minWaveMax) / (maxWaveMax - minWaveMax)
   • clamp each score to [0.0, 10.0]
   • round to 1 decimal place
   • output: waveScore for each spot

5. compute wind speed score (0-10, lower is better):

   • input: validated spot list, avgWindMph for all spots
   • for each spot, apply lookup table:
     • <= 4 mph: 10.0
     • > 4 and <= 8: 8.0
     • > 8 and <= 12: 6.0
     • > 12 and <= 16: 4.0
     • > 16 and <= 20: 2.0
     • > 20: 0.0
   • round to 1 decimal place
   • output: windSpeedScore for each spot

6. compute wind direction score (0-10):

   • input: validated spot list, avgWindDirectionDeg for all spots, optional local_break_orientation parameter
   • for each spot, check if user provided local_break_orientation for that specific spot
   • if yes, use user override (user must specify preferred direction range and corresponding score)
   • if no, apply default rubric:
     • 315-360 or 0-45: offshore/cross-offshore -> 9.0
     • 46-90 or 271-314: side-shore -> 6.0
     • 91-270: onshore/cross-onshore -> 2.0
   • round to 1 decimal place
   • output: windDirectionScore and directional label for each spot

7. compute total score:

   • input: waveScore, windSpeedScore, windDirectionScore for all spots
   • for each spot: totalScore = waveScore + windSpeedScore + windDirectionScore
   • max possible = 30.0
   • round to 1 decimal place
   • output: ranked list sorted by totalScore descending

8. select and format top 3:

   • input: ranked spot list
   • select top 3 spots by totalScore (or fewer if fewer than 3 valid spots exist)
   • for each ranked spot, generate explanation (1-3 sentences) covering wave quality, wind conditions, and why it earned its rank
   • format output per output contract (below)
   • output: formatted ranked list

9. generate final recommendation:

   • input: top 3 list with #1 spot at head
   • append single sentence naming the #1 recommendation
   • output: complete response ready for user

decision points

if region is unsupported:

• ask user for surfline spot IDs
• do not guess or invent spot IDs
• proceed with custom spot ID flow (step 2b)

if script fetch fails (network timeout, API error, malformed response):

• log error and exclude affected spots
• mention exclusion in final output
• if fewer than 3 spots remain after exclusion, return all remaining and explain why
• do not retry script automatically unless user explicitly requests retry

if fewer than 3 valid spots exist in the region:

• return all valid spots (1, 2, or fewer)
• include 1-sentence explanation: "only X valid spots found in this region"

if all spots have identical wave height:

• assign waveScore = 5.0 to all (not relative ranking)
• note this in output so user understands tie-breaking is driven by wind factors

if user provides local_break_orientation for a specific spot:

• override default wind direction rubric for that spot only
• user must specify direction range and desired score (0-10)
• other spots in region still use default rubric

if user requests forecast window outside 24 hours (e.g., 48, 72):

• pass --hours <user_value> to script
• do not cap or override user input
• script must support the requested window

if spot data returns validHours < hours_requested:

• include the spot in scoring (use data as-is)
• note reduced forecast confidence in explanation if spot is in top 3

output contract

return a markdown-formatted response containing:

1. ranked spot list (top 3 or fewer):

   • format: ### #N. [Spot Name/ID]
   • wave score line: **Wave:** [score]/10 ([avgSurfMaxFt] ft max)
   • wind direction line: **Wind Direction:** [score]/10 ([avgWindDirectionDeg]°, [label])
   • wind speed line: **Wind Speed:** [score]/10 ([avgWindMph] mph)
   • total score line: **Total Score:** [totalScore]/30
   • explanation paragraph (1-3 sentences)

2. final recommendation (single sentence):

   • format: **#1 Pick:** [Spot Name/ID] is your best bet right now.

3. exclusions note (if applicable):

   • if any spots were excluded due to missing data or script errors, list them with reason

4. metadata (optional but recommended):

   • forecast window: X hours
   • region: region name or custom spot count
   • timestamp: when data was fetched

file location: response is delivered in-channel or to user directly; no file save required unless user specifies export

outcome signal

the skill worked if:

• user receives a ranked list of top 3 (or fewer) spots with transparent scores for each category
• each spot includes both numeric score and explanation connecting data to recommendation
• user can understand why spot A ranked higher than spot B (e.g., "spot A has bigger waves but windier; spot B has cleaner wind but smaller swell")
• the #1 recommendation is clearly flagged and justified
• any excluded spots or data limitations are disclosed
• scores sum correctly: wave + wind direction + wind speed = total (to 1 decimal place)