Skill: ivangdavila/thermostat (version 1.0.0)

--- name: Thermostat description: Adjust temperatures, diagnose comfort issues, calculate energy savings, and automate schedules through voice commands or smart home integration. --- ## What the Agent Can Do | User Request | Agent Action | |--------------|--------------| | "Make it warmer/cooler" | Adjust setpoint ±2-3°F or to specific temp | | "Why is my bedroom cold?" | Diagnose: sensor location, vent issues, zone problems | | "Set up a schedule" | Gather wake/leave/return/sleep times → configure | | "Am I wasting money?" | Calculate setback savings, identify inefficiencies | | "I'm going on vacation" | Set freeze protection (55°F) or vacancy mode | | "Something's wrong with my heat" | Troubleshoot: cycles, error codes, aux heat issues | --- ## Before Adjusting Temperature **Gather context:** - Current temp and setpoint - Heating or cooling mode? - Smart thermostat or basic? - Any specific room complaints? **Smart thermostats:** Adjust via voice, app command, or API integration. **Basic thermostats:** Guide user to physical adjustment, suggest smart plug workarounds if relevant. --- ## Diagnosing Comfort Problems When user says "it's too hot/cold": 1. **Check location mismatch** — Thermostat in hallway but complaint is bedroom? Sensor measures wrong place. Solution: remote sensors or door management. 2. **Check system behavior** — Running constantly? Short cycling (<5 min)? Not turning on? Each has different diagnosis path. See `troubleshooting.md`. 3. **Check settings** — Wrong mode? Hold preventing schedule? Eco mode active unexpectedly? --- ## Energy Calculations When user asks about savings: **Setback rule of thumb:** 1°F setback for 8 hours = ~1% savings. | Scenario | Estimated savings | |----------|-------------------| | 10°F night setback (8h) | 5-15% | | 10°F work setback (8h) | 5-15% | | Both combined | 10-25% | **Heat pump exception:** Deep setbacks may trigger expensive aux heat. Recommend 3-5°F max for heat pumps. **Myth to debunk:** "Costs more to reheat" is false except heat pumps in extreme cold. --- ## Vacation/Away Configuration **Short away (hours):** Set 62°F heat / 82°F cool. **Extended vacation:** - Minimum 55°F (pipe freeze protection) - Maximum 85°F (humidity/mold prevention) - Enable leak sensor alerts if available **Remind user:** Set return date or use geofencing to avoid coming home to extreme temps. --- ## Load Detailed Reference | Situation | Reference | |-----------|-----------| | Mode explanations, holds, fan settings | `basics.md` | | System not responding, error codes, HVAC issues | `troubleshooting.md` | | Cost calculations, efficiency tips, renter workarounds | `efficiency.md` | | HomeKit, Alexa, Google, Home Assistant, Matter | `integration.md` | | Vacation settings, freeze protection, humidity | `away.md` |

path: away.md
content: # Away & Vacation — Agent Configuration Guide

## Short Away (Hours to Days)

**When user says "I'm going out":**

| Season | Recommended Setpoint |
|--------|---------------------|
| Winter | 62-65°F (saves ~10% vs occupied) |
| Summer | 82-85°F (saves AC cycles) |

**Don't go extreme:** Coming home to 85°F means 1-2 hour recovery. Balance savings vs comfort based on user preference.

---

## Extended Vacation Configuration

**When user says "I'm going away for a week":**

### Critical Limits — Explain These

| Limit | Reason |
|-------|--------|
| Minimum 55°F | Pipe freeze protection |
| Maximum 85°F | Humidity/mold prevention |

**Insurance note:** Many policies require minimum temp to cover freeze damage. Ask if user has checked their policy.

### Vacation Mode Setup

| Thermostat | How to Enable |
|------------|---------------|
| Nest | Settings → Vacation (agent can guide) |
| Ecobee | Main Menu → Vacation (set temps + dates) |
| Honeywell | "Away" → Extended Away |

**Always set return date:** Remind user or geofencing won't help if they forget to exit vacation mode.

---

## Freeze Prevention Checklist

When user is leaving in cold weather, remind them:

- [ ] Thermostat set to minimum 55°F
- [ ] Open cabinet doors under sinks (exposes pipes to warm air)
- [ ] Consider slow faucet drip if very cold expected
- [ ] Smart leak sensors active? Alert configured?
- [ ] Someone checking property weekly if extended absence?

---

## Rental Property Between Guests

**When user is Airbnb/rental host:**

**Vacancy settings:**
- Heat: 58-60°F (pipe protection + cleaner comfort)
- Cool: 80-85°F (humidity control)

**Pre-check-in conditioning:**
- Start 1-2 hours before arrival
- Target: 68°F heat / 76°F cool
- Can automate via calendar integration

**Post-checkout:**
- Wait 30-60 min (guest may return for forgotten items)
- Then switch to vacancy mode

---

## Coming Home

**Smart recovery options:**

| Method | How It Works |
|--------|--------------|
| Geofencing | System detects approach, starts conditioning |
| Scheduled | User sets return date/time, pre-conditions automatically |
| Manual remote | User adjusts via app 1-2 hours before arrival |

**After long absence, recommend user:**
- Check/change filter (dust settles even without use)
- Run system 15-30 min to verify normal operation
- Check for any error codes or unusual behavior

---

## Humidity Considerations

**Summer vacation:**
- Even with high AC setpoint, humidity can climb
- Above 60% = mold risk starts
- Consider dehumidifier on timer if very humid climate

**Winter vacation:**
- Very low humidity (<30%) can crack wood floors/furniture
- Less common issue, but mention if relevant to user's climate


path: basics.md
content: # Thermostat Basics — Reference for Agent

## Modes (When User Asks "What Mode Should I Use?")

| Mode | Use When | Agent Recommendation |
|------|----------|---------------------|
| Heat | Winter, heating only needed | Default for cold months |
| Cool | Summer, cooling only needed | Default for warm months |
| Auto | Shoulder seasons, variable temps | When daily high/low span >15°F |
| Off | Mild weather, windows open | When outdoor temp 65-75°F |

**Auto mode requires deadband** — Minimum 2-3°F gap between heat and cool setpoints. If user tries heat:72 cool:73, explain this won't work.

---

## Holds — Explaining to Users

| Hold Type | What Happens | When to Recommend |
|-----------|--------------|-------------------|
| Permanent | Stays until manually changed | "Keep it 70 until I say otherwise" |
| Temporary | Reverts at next schedule period | "Just for this afternoon" |
| Until time | Holds until specific time | "Until I get home at 6pm" |

**Common user confusion:** Manual adjustment may create permanent hold when they wanted temporary. If user complains schedule isn't working, check hold status first.

---

## Fan Settings — When Asked

| Setting | Recommend When |
|---------|----------------|
| Auto | Default, most efficient |
| Circulate | Hot/cold spots between rooms, multi-story homes |
| Always On | Rarely — only if air quality concerns |

**Circulation mode** (Nest, Ecobee): Runs fan 15-20 min/hour without heating/cooling. Explain this uses ~$5-10/month extra electricity but evens temperatures.

---

## Remote Sensors — Setup Guidance

When user has or is considering remote sensors:

**Placement recommendations:**
- 4-5 feet height (breathing level)
- Away from vents, windows, exterior doors
- In rooms they actually occupy (bedroom for sleep, office for work)

**Priority/weighting:** Most thermostats let user prioritize rooms by time of day. Ask: "Which room matters most at night? During the day?"

---

## Schedule Setup — Information to Gather

When user wants a schedule, collect:

1. **Wake time** — When do you get up? What temp feels comfortable?
2. **Leave time** — When do you leave? (Can setback 8-10°F)
3. **Return time** — When are you usually home? (Pre-heat 30-60 min before)
4. **Sleep time** — When do you go to bed? (Most people sleep better 65-68°F)

**Pre-conditioning note:** Explain that "7am = 68°F" means REACH 68 by 7am, so system starts 30-60 min earlier depending on house and outdoor temp.


path: efficiency.md
content: # Energy Efficiency — Calculations & Recommendations

## Savings Calculations for User Questions

**Base formula:** 1°F setback × 8 hours = ~1% savings on heating/cooling.

| User Scenario | Calculation | Estimated Monthly Savings |
|---------------|-------------|---------------------------|
| 10°F night setback | 10 × 1% = 10% | $15-30 on $150-300 bill |
| 10°F work setback | 10 × 1% = 10% | $15-30 on $150-300 bill |
| Both combined | ~20% | $30-60 on $150-300 bill |

**When user asks "Is this worth it?"** — Frame in monthly dollars, not percentages.

---

## Common Myths to Correct

### "It costs more to reheat the house"

**Debunk:** Almost always false. Energy saved during setback exceeds recovery energy.

**Exception:** Heat pumps in extreme cold. If 10°F setback triggers 2+ hours of aux heat to recover, savings may be minimal. Recommend smaller setbacks (3-5°F) for heat pumps.

**Why myth persists:** People feel the system "working hard" and assume it's expensive. It's just compressed energy use, not extra.

### "Smart thermostats don't really save money"

**Reality:** Typical savings 10-15% IF actually using the features (schedule, geofencing, setbacks). Users who override constantly or keep constant temps see no savings.

---

## Hourly Cost Estimates

When user asks "How much does this cost to run?":

| System | Cost per Hour Running (US avg) |
|--------|-------------------------------|
| Gas furnace | $1.50-2.50 |
| Electric furnace | $2.00-4.00 |
| Heat pump (normal) | $0.50-1.50 |
| Heat pump (aux heat) | $2.00-4.00 |
| Central AC | $0.50-1.00 |

**Quick estimate:** Hours running × hourly cost = daily cost.

---

## Recommendations by User Type

### Work from Home
- No "away" setback needed — you're there
- Focus on sleep setback only
- Consider zone heating (space heater in office) if home is large

### Variable Schedule
- Enable geofencing if smart thermostat supports it
- Or set conservative "away" (65°F) with manual boost when home
- Avoid learning mode if schedule is truly unpredictable

### Airbnb/Rental Host
- Set guest limits (68-76°F range)
- Vacancy mode between bookings (58-60°F heat, 80-85°F cool)
- Calendar integration for auto pre-conditioning before check-in

---

## Renter Workarounds (No Smart Thermostat)

When user can't install smart thermostat:

**Manual discipline:**
- Phone reminders to adjust before leaving/sleeping
- Write down schedule on sticky note near thermostat

**Portable solutions:**
- Smart plug + space heater for zone heating (⚠️ safety: never unattended)
- Weatherstripping (removable)
- Thermal curtains (close at night, open for solar gain)

**Landlord persuasion:**
- Utility rebates often cover 50-100% of smart thermostat
- Increases property value
- Reduces tenant complaints


path: integration.md
content: # Smart Home Integration — Agent Capabilities

## What Agent Can Do Per Platform

| Platform | Agent Capabilities |
|----------|-------------------|
| HomeKit | Set temp, change mode, query status via Siri/shortcuts |
| Alexa | Set temp, change mode, query status, set schedules via routines |
| Google Home | Set temp, change mode, query status, schedule via routines |
| Home Assistant | Full control: temps, modes, schedules, automations, sensor data |
| Matter | Cross-platform control, but advanced features need native app |

---

## Voice Command Patterns

**Teach user these work:**

| Action | Say This |
|--------|----------|
| Set exact temp | "Set thermostat to 70" |
| Relative adjust | "Turn up the heat" / "Make it warmer" |
| Change mode | "Set thermostat to cool" |
| Check status | "What's the thermostat set to?" |
| Activate scene | "Set home to away mode" |

**Gotcha:** "What's the temperature?" may return room sensor reading, not setpoint. Be specific about what user wants to know.

---

## Home Assistant Automations Agent Can Help Configure

**Auto-away when everyone leaves:**
```yaml
automation:
  trigger:
    - platform: state
      entity_id: group.family
      to: "not_home"
  action:
    - service: climate.set_temperature
      target:
        entity_id: climate.thermostat
      data:
        temperature: 62
```

**Pre-heat on approach:**
```yaml
automation:
  trigger:
    - platform: zone
      entity_id: device_tracker.phone
      zone: zone.home
      event: enter
  action:
    - service: climate.set_temperature
      data:
        temperature: 68
```

When user describes desired automation, help construct the YAML or guide through UI setup.

---

## Integration Troubleshooting

| Problem | Agent Diagnosis |
|---------|-----------------|
| "Alexa can't find my thermostat" | Re-discover devices, check skill is enabled and linked |
| "Voice command doesn't work" | Check exact phrasing, verify device name matches |
| "Shows wrong temperature" | Sensor vs setpoint confusion, or stale cache |
| "Automation didn't trigger" | Check condition logic, verify entities online |
| "Matter device won't pair" | Factory reset, ensure hub supports Matter, proximity during pairing |

---

## Multi-Zone Systems

**When user has multiple zones:**
- Each zone may appear as separate climate entity
- Or single entity with zone attributes (depends on integration)
- Help user understand which zone controls which rooms
- Schedule can differ per zone (sleep zone cooler at night)

**Common confusion:** "I set 70 but it shows 68" — Likely looking at different zone. Clarify which zone they're adjusting vs reading.


path: troubleshooting.md
content: # Troubleshooting — Agent Diagnosis Guide

## "It's Too Hot/Cold in [Room]"

**Diagnosis flowchart:**

1. **Where is the thermostat?** 
   - If different room than complaint → sensor location mismatch
   - Solution: Remote sensors OR strategic door management

2. **Is system running?**
   - Not running but should be → Check mode, check hold, check breaker
   - Running constantly → Undersized system OR extreme outdoor temps OR dirty filter

3. **Are vents open and unblocked?**
   - Closed/blocked vents redistribute air → Open problem room, partially close comfortable rooms

4. **Multi-story home?**
   - Heat rises → Upper floors hotter
   - Solution: Circulation fan mode, OR different setpoints if zoned

---

## "System Isn't Working"

**Quick checks to run through:**

| Symptom | Likely Cause | Agent Recommendation |
|---------|--------------|---------------------|
| No display | Power issue | Check breaker, check batteries if applicable |
| Display works, nothing happens | Wrong mode or hold | Verify mode matches season, clear holds |
| Runs but no heat/cool | Equipment issue | Check outdoor unit, filter, call HVAC if persists |
| Short cycles (<5 min) | Oversized system or dirty components | Needs HVAC service |
| Runs constantly | Undersized, extreme temps, or refrigerant issue | Check filter first, then HVAC if persists |

---

## Error Codes — Quick Reference

| Code Pattern | Meaning | Agent Action |
|--------------|---------|--------------|
| E1/E2 | Sensor failure | Likely needs replacement, recommend HVAC call |
| E3/E4/E5 | Communication error | Power cycle, then HVAC if persists |
| AUX or EM | Aux/emergency heat active | Normal below 35°F outdoor, problem above 40°F |
| Filter | Filter change reminder | Remind user to change, show how to reset |

---

## Heat Pump Specific

**Aux heat running — is this a problem?**

| Outdoor Temp | Aux Heat Normal? |
|--------------|------------------|
| Below 35°F | Yes, expected |
| 35-40°F | Sometimes, during recovery |
| Above 40°F | No — investigate |

**If aux dominates above 40°F:** Possible issues: low refrigerant, defrost problem, wrong balance point setting. Recommend HVAC service.

**Cold air during heat cycle:** This is defrost mode — normal for 5-10 min in cold weather. Explain to user this is the system protecting itself from ice buildup.

---

## When to Recommend HVAC Technician

Always recommend professional when:
- Short cycling persists after filter change
- System runs 24/7 without reaching setpoint
- Strange smells (burning, gas)
- Water leaks around equipment
- Error codes don't clear after power cycle
- Energy bills spike 30%+ unexpectedly
- Aux heat dominates above 40°F outdoor temp


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)