Enhance skill docs with version checks and data-vintage guidance

skills/docs/SKILL.md

@@ -8,6 +8,9 @@ argument-hint: "[search-query]"
 
 Look up: $ARGUMENTS
 
+> Use `docs` for *EnergyPlus object* documentation (fields, algorithms, behavior) via the MCP server;
+> use `developing-with-idfkit` for *writing idfkit Python* against the library.
+
 ## Steps
 
 1. **Quick reference** — If the query is an object type name, read the `idfkit://docs/{object_type}` resource to get direct URLs to:

skills/load-model/SKILL.md

@@ -28,6 +28,16 @@ Load the model at: $ARGUMENTS
 
 4. **Visual inspection** — Use `view_geometry` to show an interactive 3D view of the building for quick spatial orientation.
 
-5. **Highlight issues** — If anything looks incomplete or unusual (e.g., no HVAC, no weather file, missing output variables), mention it proactively.
-
-6. **Suggest next steps** — Based on the model state, suggest what the user might want to do next (validate, simulate, add systems, etc.).
+5. **Version check** — If the model's `Version` differs from the installed/supported EnergyPlus, flag it
+   and suggest `migrate_model` (the `upgrade-version` skill) before simulating — running against a
+   mismatched version can fail or silently misbehave.
+
+6. **Highlight issues** — If anything looks incomplete or unusual, mention it proactively. Surface
+   simulation-readiness gaps you can already see from the summary, e.g.:
+   - autosized HVAC but no `SizingPeriod:DesignDay` (or `SimulationControl` sizing flags off) — sizing
+     can't run, so capacities resolve to zero
+   - no weather file or `Site:Location` assigned
+   - missing `Site:GroundTemperature:*` for models with ground-coupled surfaces
+   - no output variables/meters requested
+
+7. **Suggest next steps** — Based on the model state, suggest what the user might want to do next (validate, simulate, migrate, add systems, etc.).

skills/weather/SKILL.md

@@ -14,6 +14,10 @@ Search for weather data near: $ARGUMENTS
    - For text queries (city names): pass the `query` parameter
    - For coordinate-based: pass `latitude` and `longitude`
    - Optionally filter by `country` (ISO code) or `state` (US state code)
+   - **Data vintage** — the default files are typical-year (TMY/IWEC/etc.), the right choice for design
+     and code-compliance work. For calibration or measurement & verification (M&V) against metered
+     energy, the user instead needs actual-year (AMY) data for the specific year being matched, which
+     these stations do not provide — flag this so they source an AMY EPW separately.
 
 2. **Present results** — Show the top matches with:
    - Station name and location (city, state, country)
@@ -28,3 +32,6 @@ Search for weather data near: $ARGUMENTS
    - Weather file location on disk
    - Key climate characteristics (if available from the station metadata)
    - Remind that the weather file can be used with `run_simulation`
+   - **Site:Location** — the model's `Site:Location` (latitude, longitude, elevation, time zone) should
+     match the chosen EPW header; a mismatch silently skews solar position and run-period results. If a
+     model is loaded, suggest aligning `Site:Location` to the downloaded station's coordinates.