ha-energy

Q: How do I install ha-energy?

Run npx skills add https://github.com/nodnarbnitram/claude-code-extensions --skill ha-energy in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/ha-energy/ (personal) or .claude/skills/ha-energy/ (project).

by nodnarbnitramDevOps & Cloud

Set up Home Assistant energy monitoring with dashboards, solar, grid, and device tracking. Use when configuring energy sensors, utility meters, statistics, or analyzing consumption. Activates on keywords: energy dashboard, solar, grid, consumption, kWh, utility meter, power monitoring, stateclass, deviceclass: energy.

Installs: 104
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/nodnarbnitram/claude-code-extensions --skill ha-energy

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads ha-energy automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Home Assistant Energy Skill

Configure Home Assistant energy monitoring with dashboards, solar, grid, and device tracking.

Before You Start

This skill prevents 8 common errors and saves ~45% tokens.

Metric	Without Skill	With Skill
Setup Time	45+ min	15 min
Common Errors	8	0
Token Usage	~10000	~5500

Known Issues This Skill Prevents

Incorrect state_class values (must be total, total_increasing, or measurement)
Missing device_class: energy on energy sensors
Wrong state_class for utility_meter entities (must be total_increasing)
Using unit_of_measurement: kWh without state_class (breaks statistics)
Forgetting to enable statistic collection in configuration.yaml
Configuring solar sensors without battery tracking for self-consumption
Grid monitoring with mismatched sensor pairs (consumption vs return)
Utility meter cycle settings that don't align with billing periods

Quick Start

Step 1: Configure Energy Sensors

# configuration.yaml
template:
  - sensor:
      - name: "Total Energy Consumed"
        unique_id: total_energy_consumed
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.energy_meter') | float(0)) }}"

      - name: "Solar Production"
        unique_id: solar_production
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.solar_meter') | float(0)) }}"

Why this matters: Proper state_class enables Home Assistant to automatically create statistics and energy dashboard integration. Without it, your sensors won't appear in the energy dashboard.

Step 2: Set Up Utility Meter for Billing Cycles

# configuration.yaml
utility_meter:
  daily_energy:
    source: sensor.total_energy_consumed
    cycle: daily
    offset: [hours: 0]

  monthly_energy:
    source: sensor.total_energy_consumed
    cycle: monthly
    offset: [days: 0]

  daily_solar:
    source: sensor.solar_production
    cycle: daily
    offset: [hours: 0]

Why this matters: Utility meters automatically reset at specified intervals and track consumption periods for billing analysis.

Step 3: Enable Statistics Recorder

# configuration.yaml
recorder:
  db_url: !secret database_url  # Optional but recommended
  auto_purge: true
  auto_purge_days: 90           # Adjust retention as needed
  # Include sensors with state_class for statistics
  include:
    entities:
      - sensor.total_energy_consumed
      - sensor.solar_production
      - sensor.grid_consumption
      - sensor.grid_return

Why this matters: Statistics require the recorder to be properly configured. Without explicit inclusion, energy sensors may not generate statistics for long-term analysis.

Critical Rules

Always Do

Use state_class: total_increasing for cumulative meters that only increase
Add device_class: energy to all energy sensors
Set unit_of_measurement: kWh (or appropriate unit) on energy sensors
Configure utility_meter for billing cycle tracking
Include all energy sensors in recorder's include list
Reset cumulative sensors on device restart via template sensor
Use separate sensors for grid consumption and grid return

Never Do

Use state_class: measurement for cumulative meters (breaks statistics)
Forget the offset parameter on utility_meter (may cause midnight resets)
Mix power (W) and energy (kWh) sensors without Riemann sum integration
Create energy sensors without state_class (they won't work in energy dashboard)
Assume solar production should subtract from consumption (energy dashboard handles this)
Configure bidirectional flow on single sensors (use separate consumption/return sensors)
Skip utility_meter configuration if you need consumption tracking by period

Common Mistakes

Wrong:

sensor:
  - platform: template
    sensors:
      total_energy:
        unit_of_measurement: kWh
        value_template: "{{ states('sensor.meter') }}"

Correct:

template:
  - sensor:
      - name: "Total Energy"
        unique_id: total_energy
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.meter') | float(0)) }}"

Why: Template platform is deprecated. Use template integration with proper state_class and device_class to enable energy dashboard integration.

Known Issues Prevention

Issue	Root Cause	Solution
Energy dashboard shows no data	`state_class` missing or wrong	Use `total_increasing` for cumulative meters
Statistics not generated	Sensors not in recorder's include list	Add sensor entities to recorder config
Utility meter not resetting	Wrong `offset` or missing `cycle`	Verify cycle (hourly/daily/monthly) and offset settings
Solar self-consumption not calculated	Battery sensors not configured separately	Create charge/discharge sensors for batteries
Grid consumption incorrect	Using bidirectional sensor instead of separate sensors	Split into grid_consumption and grid_return
Sensor unavailable after restart	Cumulative meter not preserved	Add `availability_template` to template sensor
Statistics showing wrong values	Raw data has negative values or gaps	Use Riemann sum to convert power to energy
Utility meter shows wrong period	Offset set incorrectly for timezone	Align offset with local midnight or billing cycle

Configuration Reference

Energy Sensor Template (YAML)

template:
  - sensor:
      - name: "Main Energy Meter"
        unique_id: main_energy_meter
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        availability_template: "{{ states('sensor.meter_input') not in ['unavailable', 'unknown'] }}"
        state: "{{ (states('sensor.meter_input') | float(0)) }}"

      - name: "Instantaneous Power"
        unique_id: instantaneous_power
        unit_of_measurement: W
        device_class: power
        state_class: measurement
        state: "{{ (states('sensor.power_meter') | float(0)) }}"

Key settings:

device_class: energy - Identifies as energy sensor for energy dashboard
state_class: total_increasing - Cumulative meter that only increases
state_class: measurement - Instantaneous values (power, not energy)
unit_of_measurement: kWh - Energy units; use W for power
availability_template - Prevents unavailable states from breaking statistics

Utility Meter Configuration (YAML)

utility_meter:
  daily_consumption:
    source: sensor.total_energy_consumed
    cycle: daily
    offset:
      hours: 0
    net_consumption: false        # true for solar with self-consumption

  monthly_consumption:
    source: sensor.total_energy_consumed
    cycle: monthly
    offset:
      days: 1                     # Reset on 1st of month
      hours: 0

  peak_consumption:
    source: sensor.total_energy_consumed
    cycle: weekly
    offset:
      days: 0                     # Reset on Monday
      hours: 0

Key settings:

cycle: hourly, daily, weekly, monthly, bimonthly, quarterly, yearly
offset: Time adjustment for billing alignment
net_consumption: Set to true for solar to track self-consumption

Riemann Sum Integration (for Power to Energy)

integration:
  - platform: riemann_sum
    name: "Daily Energy from Power"
    unique_id: daily_energy_riemann
    source: sensor.instantaneous_power
    round: 3
    unit_prefix: k                # Converts W to kWh
    unit_time: h
    method: trapezoidal

Key settings:

source: Power sensor (W) to integrate
unit_prefix: k - Converts watts to kilowatts
method: trapezoidal or left for integration algorithm
round: 3 - Decimal precision

Common Patterns

Grid Monitoring (Consumption + Return)

template:
  - sensor:
      - name: "Grid Consumption"
        unique_id: grid_consumption
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.grid_import') | float(0)) }}"

      - name: "Grid Return"
        unique_id: grid_return
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.grid_export') | float(0)) }}"

Solar Production with Battery

template:
  - sensor:
      - name: "Solar Production"
        unique_id: solar_production
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.solar_meter') | float(0)) }}"

      - name: "Battery Charge"
        unique_id: battery_charge
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.battery_charge_meter') | float(0)) }}"

      - name: "Battery Discharge"
        unique_id: battery_discharge
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.battery_discharge_meter') | float(0)) }}"

Device Power Monitoring (Smart Plug)

template:
  - sensor:
      - name: "Device Energy Today"
        unique_id: device_energy_today
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.device_energy') | float(0)) }}"

utility_meter:
  device_daily_energy:
    source: sensor.device_energy_today
    cycle: daily
    offset:
      hours: 0

Bundled Resources

References

Located in references/:

state-class-guide.md - Comprehensive state_class reference
device-class-reference.md - All energy-related device classes
utility-meter-patterns.md - Billing cycle configurations
energy-dashboard-setup.md - Step-by-step energy dashboard guide
solar-integration.md - Solar panel and battery tracking

Note: For deep dives on specific topics, see the reference files above.

Assets

Located in assets/:

energy-sensors-template.yaml - Complete sensor template
utility-meter-examples.yaml - Meter configurations for all scenarios
energy-dashboard-card.yaml - Dashboard card configuration

Copy these templates as starting points for your implementation.

Context7 Documentation

For current documentation, use these Context7 library IDs:

Library ID	Purpose
`/home-assistant/home-assistant.io`	User docs - energy, solar, grid, utility_meter
`/home-assistant/integrations`	Integration docs for specific devices
`/home-assistant/template`	Template sensor reference

Official Documentation

Troubleshooting

Energy Dashboard Shows No Data

Symptoms: Energy dashboard loads but shows "No data available" or blank graphs.

Solution:

# 1. Verify sensors exist and have state_class
developer-tools > States > Search for energy/solar sensors

# 2. Check recorder includes sensors
# In configuration.yaml:
recorder:
  include:
    entities:
      - sensor.total_energy_consumed
      - sensor.solar_production

# 3. Restart Home Assistant
# 4. Wait 10 minutes for statistics to generate
# 5. Check Developer Tools > Statistics

Utility Meter Not Resetting

Symptoms: Utility meter keeps accumulating without resetting at expected time.

Solution:

# Check offset configuration
utility_meter:
  daily_energy:
    source: sensor.total_energy_consumed
    cycle: daily
    # For midnight reset in your timezone:
    offset:
      hours: 0
    # For reset at 6 AM:
    # offset:
    #   hours: 6

Solar Self-Consumption Not Tracking

Symptoms: Self-consumption percentage is 0% or not shown.

Solution:

# Create separate battery sensors
template:
  - sensor:
      - name: "Battery Charge"
        unique_id: battery_charge
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.battery_charge_meter') | float(0)) }}"

      - name: "Battery Discharge"
        unique_id: battery_discharge
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.battery_discharge_meter') | float(0)) }}"

# In energy dashboard configuration, set:
# - Source: Solar production sensor
# - Battery (optional): Both charge and discharge sensors

Sensor Shows "unknown" or "unavailable"

Symptoms: Sensor state stuck on "unknown" or "unavailable" in Developer Tools.

Solution:

# Add availability_template
template:
  - sensor:
      - name: "Energy Meter"
        unique_id: energy_meter
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        availability_template: "{{ states('sensor.meter_input') not in ['unavailable', 'unknown'] }}"
        state: "{{ (states('sensor.meter_input') | float(0)) }}"

Setup Checklist

Before using this skill, verify:

Home Assistant is running 2023.1 or later
You have access to configuration.yaml (File Editor or VS Code add-on)
You have at least one energy sensor available (grid meter, smart plug, integration sensor)
You've decided on meter types (grid consumption/return, solar, battery, individual devices)
You understand your billing cycle (daily, monthly, etc.)
Recorder is enabled in configuration.yaml
You've identified all devices/meters to monitor

FAQ

What does the ha-energy skill do?

How do I install ha-energy?

Run npx skills add https://github.com/nodnarbnitram/claude-code-extensions --skill ha-energy in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/ha-energy/ (personal) or .claude/skills/ha-energy/ (project).

Which AI agents can use ha-energy?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is ha-energy safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains ha-energy?

It is published by nodnarbnitram in nodnarbnitram/claude-code-extensions. It has 104 recorded installs.