
energykit
Query grid electricity forecasts and submit load events using EnergyKit to help users optimize home electricity usage. Use when building smart home apps, EV charger controls, HVAC scheduling, or energy management dashboards that guide users to use power during cleaner or cheaper grid periods.
- Installs
- 3.6K
- Last 24h
- +16
- Trending rank
- #6808
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/dpearson2699/swift-ios-skills --skill energykit- 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 energykit 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.
EnergyKit
Use grid cleanliness and cost guidance to shift or reduce managed-device load. For managed-device insights, submit the device's real load events promptly.
Beta-sensitive. Core EnergyKit ships in iOS/iPadOS 26. The iOS/iPadOS 27
ElectricalLoadDeviceand Home-facing LoadEvents experience are beta; re-check current Apple documentation before relying on those APIs.
Contents
- Setup
- Core Concepts
- Querying Electricity Guidance
- Working with Guidance Values
- Energy Venues
- Submitting Load Events
- Electricity Insights
- Common Mistakes
- Review Checklist
- References
Setup
Entitlements and Version Split
| Runtime | Load-event device API | Capabilities |
|---|---|---|
| iOS/iPadOS 26.x | deviceID: compatibility initializer | EnergyKit |
| iOS/iPadOS 27+ beta | ElectricalLoadDevice with the device: initializer | EnergyKit; add EnergyKit LoadEvents for Home app integration |
All EnergyKit use requires com.apple.developer.energykit; enable the EnergyKit
capability on the app target. On iOS/iPadOS 27+, add the EnergyKit LoadEvents
capability (com.apple.developer.energykit.loadevents-experience) only when the
app needs device names, energy context, activity logs, historical charts, or
trend notifications in the Home app. That Home experience requires both
capabilities. Missing permission can surface as EnergyKitError.permissionDenied.
Import
import EnergyKit
Platform availability: Core EnergyKit APIs are iOS/iPadOS 26.0+. Some
insight breakdown APIs, including grid cleanliness categories, are 26.1+ and
need availability guards. Apple currently documents electricity guidance only
for the contiguous United States; handle EnergyKitError.unsupportedRegion.
Core Concepts
EnergyKit provides two main capabilities:
- Electricity Guidance -- time-weighted forecasts telling apps when electricity is cleaner and, when rate data is available, less expensive
- Load Events -- telemetry from managed devices (EV chargers, HVAC) submitted by the same device/app that requested guidance so EnergyKit can generate insights
Key Types
| Type | Role |
|---|---|
ElectricityGuidance | Forecast data with weighted time intervals |
ElectricityGuidance.Service | Interface for obtaining guidance data |
ElectricityGuidance.Query | Query specifying shift or reduce action |
ElectricityGuidance.Value | A time interval with a rating (0.0-1.0) |
EnergyVenue | A physical location (home) registered for energy management |
ElectricVehicleLoadEvent | Load event for EV charger telemetry |
ElectricHVACLoadEvent | Load event for HVAC system telemetry |
ElectricalLoadDevice | iOS/iPadOS 27+ beta device identity for load events |
ElectricityInsightService | Service for querying energy/runtime insights |
ElectricityInsightRecord | Historical energy or runtime data, optionally broken down by tariff or 26.1+ grid cleanliness |
ElectricityInsightQuery | Query for historical insight data |
Suggested Actions
| Action | Use Case |
|---|---|
.shift | Devices that can move consumption to a different time (EV charging) |
.reduce | Devices that can lower consumption without stopping (HVAC setback) |
Querying Electricity Guidance
Use ElectricityGuidance.Service to get a forecast stream for a venue.
import EnergyKit
func observeGuidance(venueID: UUID) async throws {
let query = ElectricityGuidance.Query(suggestedAction: .shift)
let service = ElectricityGuidance.sharedService
let guidanceStream = service.guidance(using: query, at: venueID)
for try await guidance in guidanceStream {
print("Guidance token: \(guidance.guidanceToken)")
print("Interval: \(guidance.interval)")
print("Venue: \(guidance.energyVenueID)")
// Check if rate plan information is available
if guidance.options.contains(.guidanceIncorporatesRatePlan) {
print("Rate plan data incorporated")
}
if guidance.options.contains(.locationHasRatePlan) {
print("Location has a rate plan")
}
processGuidanceValues(guidance.values)
}
}
Working with Guidance Values
Each ElectricityGuidance.Value contains a time interval and a rating
from 0.0 to 1.0. Lower ratings indicate better times to use electricity.
func processGuidanceValues(_ values: [ElectricityGuidance.Value]) {
for value in values {
let interval = value.interval
let rating = value.rating // 0.0 (best) to 1.0 (worst)
print("From \(interval.start) to \(interval.end): rating \(rating)")
}
}
// Find the best time to charge
func bestChargingWindow(
in values: [ElectricityGuidance.Value]
) -> ElectricityGuidance.Value? {
values.min(by: { $0.rating < $1.rating })
}
// Find all "good" windows below a threshold
func goodWindows(
in values: [ElectricityGuidance.Value],
threshold: Double = 0.3
) -> [ElectricityGuidance.Value] {
values.filter { $0.rating <= threshold }
}
Displaying Guidance in SwiftUI
import SwiftUI
import EnergyKit
struct GuidanceTimelineView: View {
let values: [ElectricityGuidance.Value]
var body: some View {
List(values, id: \.interval.start) { value in
HStack {
VStack(alignment: .leading) {
Text(value.interval.start, style: .time)
Text(value.interval.end, style: .time)
.foregroundStyle(.secondary)
}
Spacer()
RatingIndicator(rating: value.rating)
}
}
}
}
struct RatingIndicator: View {
let rating: Double
var color: Color {
if rating <= 0.3 { return .green }
if rating <= 0.6 { return .yellow }
return .red
}
var label: String {
if rating <= 0.3 { return "Good" }
if rating <= 0.6 { return "Fair" }
return "Avoid"
}
var body: some View {
Text(label)
.padding(.horizontal)
.padding(.vertical)
.background(color.opacity(0.2))
.foregroundStyle(color)
.clipShape(Capsule())
}
}
Energy Venues
An EnergyVenue represents a physical location registered for energy management.
// List all venues
func listVenues() async throws -> [EnergyVenue] {
try await EnergyVenue.venues()
}
// Get a specific venue by ID
func getVenue(id: UUID) async throws -> EnergyVenue {
try await EnergyVenue.venue(for: id)
}
// Get a venue matching a HomeKit home
func getVenueForHome(homeID: UUID) async throws -> EnergyVenue {
try await EnergyVenue.venue(matchingHomeUniqueIdentifier: homeID)
}
Venue Properties
let venue = try await EnergyVenue.venue(for: venueID)
print("Venue ID: \(venue.id)")
print("Venue name: \(venue.name)")
Submitting Load Events
Report device consumption data back to the system. This helps the system generate electricity insights. The same EnergyKit-capable device/app that requested electricity guidance must submit the corresponding load events, using the guidance token returned by EnergyKit. Do not invent a token.
EV Charger Load Events
func submitEVBeginEvent(
at venue: EnergyVenue,
guidanceToken: UUID,
deviceID: String,
deviceName: String
) async throws {
let session = ElectricVehicleLoadEvent.Session(
id: UUID(),
state: .begin,
guidanceState: ElectricVehicleLoadEvent.Session.GuidanceState(
wasFollowingGuidance: true,
guidanceToken: guidanceToken
)
)
let measurement = ElectricVehicleLoadEvent.ElectricalMeasurement(
stateOfCharge: 45,
direction: .imported,
power: Measurement(value: 0, unit: .kilowatts),
energy: Measurement(value: 0, unit: .kilowattHours)
)
let event: ElectricVehicleLoadEvent
if #available(iOS 27.0, iPadOS 27.0, *) {
let device = ElectricalLoadDevice(
id: deviceID,
name: deviceName,
type: .electricVehicle
)
event = ElectricVehicleLoadEvent(
timestamp: Date(), measurement: measurement,
session: session, device: device
)
} else {
// iOS/iPadOS 26 compatibility; deprecated in the iOS 27 SDK.
event = ElectricVehicleLoadEvent(
timestamp: Date(), measurement: measurement,
session: session, deviceID: deviceID
)
}
try await venue.submitEvents([event])
}
HVAC Load Events
func submitHVACEvent(
at venue: EnergyVenue,
guidanceToken: UUID,
stage: Int,
deviceID: String,
deviceName: String
) async throws {
let session = ElectricHVACLoadEvent.Session(
id: UUID(),
state: .active,
guidanceState: ElectricHVACLoadEvent.Session.GuidanceState(
wasFollowingGuidance: true,
guidanceToken: guidanceToken
)
)
let measurement = ElectricHVACLoadEvent.ElectricalMeasurement(stage: stage)
let event: ElectricHVACLoadEvent
if #available(iOS 27.0, iPadOS 27.0, *) {
let device = ElectricalLoadDevice(
id: deviceID,
name: deviceName,
type: .hvac
)
event = ElectricHVACLoadEvent(
timestamp: Date(), measurement: measurement,
session: session, device: device
)
} else {
// iOS/iPadOS 26 compatibility; deprecated in the iOS 27 SDK.
event = ElectricHVACLoadEvent(
timestamp: Date(), measurement: measurement,
session: session, deviceID: deviceID
)
}
try await venue.submitEvents([event])
}
Session States
| State | When to Use |
|---|---|
.begin | Device starts consuming electricity |
.active | Device is actively consuming (periodic updates) |
.end | Device stops consuming electricity |
Preserve .begin → .active → .end and submit events promptly rather than
holding long batches. For EV charging, submit .begin with zero power and
energy, .active about every 15 minutes plus significant changes, and .end
with zero power and cumulative energy. Retain unacknowledged events and retry
EnergyKitError.rateLimitExceeded with bounded backoff. Load the
EV session manager
or HVAC session manager
for device-specific lifecycle handling.
Only promise Home app device names, energy context, activity logs, charts, and trend notifications on iOS/iPadOS 27+ when both the base EnergyKit and EnergyKit LoadEvents capabilities are present.
Electricity Insights
Query historical energy and runtime data for devices using
ElectricityInsightService. An empty ElectricityInsightQuery.Options option
set returns totals only; it does not populate cleanliness or tariff breakdowns.
Request .cleanliness and/or .tariff only when the UI needs those breakdowns.
Do not substitute MetricKit app power metrics for EnergyKit insights; EnergyKit
insights depend on EnergyKit load events submitted for the managed device.
Choose insight granularity from the requested range. For a seven-day view,
query .hourly; use .daily only when the query covers at least a calendar
month.
func queryEnergyInsights(deviceID: String, venueID: UUID) async throws {
let sevenDaysAgo = Calendar.current.date(
byAdding: .day,
value: -7,
to: Date()
)!
let query = ElectricityInsightQuery(
options: [.cleanliness, .tariff],
range: DateInterval(
start: sevenDaysAgo,
end: Date()
),
granularity: .hourly,
flowDirection: .imported
)
let service = ElectricityInsightService.shared
let stream = try await service.energyInsights(
forDeviceID: deviceID, using: query, atVenue: venueID
)
for await record in stream {
if let total = record.totalEnergy { print("Total: \(total)") }
if #available(iOS 26.1, iPadOS 26.1, *),
let cleaner = record.dataByGridCleanliness?.cleaner {
print("Cleaner: \(cleaner)")
}
}
}
Use runtimeInsights(forDeviceID:using:atVenue:) for runtime data instead
of energy. Granularity options: .hourly, .daily, .weekly, .monthly,
.yearly. Choose a range that matches Apple's minimum aggregation windows:
hourly for at least a calendar week, daily for at least a calendar month,
weekly for at least six months, and monthly or yearly for at least a calendar
year. See references/energykit-patterns.md for full insight examples.
Common Mistakes
| Mistake | Fix |
|---|---|
| Querying before capability setup | Verify the EnergyKit entitlement and handle .permissionDenied. |
| Assuming every region has guidance | Apple currently documents guidance only in the contiguous US; handle unsupported-region and unavailable venue/guidance states. |
| Fabricating or discarding the guidance token | Persist the real token on the requesting device and submit that token with its load events. |
| Sending isolated or delayed load samples | Preserve .begin → .active → .end, submit promptly, and retain events until submission succeeds. |
Using deviceID: as the current default | Use iOS/iPadOS 27+ ElectricalLoadDevice and device:; keep deviceID: only for the 26.x runtime branch. |
| Using a hardcoded venue ID | Discover venues with EnergyVenue.venues() and select the intended venue. |
Review Checklist
- Base EnergyKit capability is present; iOS/iPadOS 27+ Home integration also has EnergyKit LoadEvents
- Region, permission, venue discovery, unavailable guidance, and service errors are handled
- Real guidance tokens stay with the requesting device/app and its submitted load events
- iOS/iPadOS 27+ uses
ElectricalLoadDevice/device:;deviceID:is isolated to 26.x compatibility -
.begin → .active → .endevents follow device cadence, submit promptly, survive failure, and retry rate limits with bounded backoff - Ratings/actions are interpreted correctly; insight options, availability, granularity, and minimum ranges match the UI
- MetricKit telemetry is not substituted for EnergyKit load events or insights
References
- Extended workflows for app architecture, EV/HVAC session cadence, dashboard presentation, insights, errors, and venue discovery: references/energykit-patterns.md
- EnergyKit framework
- ElectricityGuidance
- ElectricityGuidance.Service
- ElectricityGuidance.Query
- ElectricityGuidance.Value
- EnergyVenue
- ElectricalLoadDevice
- ElectricVehicleLoadEvent
- ElectricHVACLoadEvent
- ElectricityInsightService
- ElectricityInsightRecord
- ElectricityInsightQuery
- EnergyKitError
- EnergyKit entitlement
- EnergyKit LoadEvents entitlement
- Providing charging history for electric vehicles
- Optimizing home electricity usage
FAQ
What does the energykit skill do?
Query grid electricity forecasts and submit load events using EnergyKit to help users optimize home electricity usage. Use when building smart home apps, EV charger controls, HVAC scheduling, or energy management dashboards that guide users to use power during cleaner or cheaper grid periods.
How do I install energykit?
Run npx skills add https://github.com/dpearson2699/swift-ios-skills --skill energykit 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/energykit/ (personal) or .claude/skills/energykit/ (project).
Which AI agents can use energykit?
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 energykit 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 energykit?
It is published by dpearson2699 in dpearson2699/swift-ios-skills. It has 3,581 recorded installs.
More from dpearson2699/swift-ios-skills
swiftui-animation
dpearson2699/swift-ios-skills
Implement, diagnose, or review SwiftUI motion using explicit and scoped implicit animations, springs, transitions, PhaseAnimator, KeyframeAnimator, matched geometry or navigation zoom, SF Symbol effects, and custom Animation types. Use when views should animate on state changes, insertion, removal, navigation, or multi-step choreography, or when motion must respect Reduce Motion and Swift concurrency.
ios-accessibility
dpearson2699/swift-ios-skills
Build and audit SwiftUI, UIKit, and AppKit accessibility for VoiceOver, Voice Control, Switch Control, Full Keyboard Access, Dynamic Type, focus restoration, labels/traits/actions, traversal, custom rotors, NSAccessibility, XCTest checks, adaptive system preferences, and App Store accessibility declarations. Use when implementing accessible UI, fixing an accessibility audit, testing assistive-technology behavior, or substantiating App Store Accessibility Nutrition Labels.
swiftui-performance
dpearson2699/swift-ios-skills
Profile, diagnose, and remediate SwiftUI runtime performance using code review, Instruments, and repeatable measurements. Use when a SwiftUI screen renders slowly, scrolling or animations hitch, view bodies update excessively, list identity churns, layout work spikes, or broad Observation dependencies raise CPU cost. Covers evidence-based triage, SwiftUI Instruments lanes, lazy-container guardrails, state lifetime, and before/after verification.
swiftui-patterns
dpearson2699/swift-ios-skills
Builds and reviews SwiftUI views with modern MV architecture, state, composition, isolated previews, and migration guidance. Covers @Observable ownership, @State/@Bindable/@Environment wiring, view decomposition, ViewModifiers, environment values, .task loading, iOS 26+ handoffs, Writing Tools, clipboard availability, and performance. Use when structuring SwiftUI state, managing @Observable, composing views, previewing meaningful UI states, or correcting SwiftUI patterns.
app-store-review
dpearson2699/swift-ios-skills
Audits App Store submission readiness and rejection risk across current review guidelines, PrivacyInfo.xcprivacy and required-reason APIs, privacy labels, ATT, StoreKit payments, metadata, entitlements, widgets, and Live Activities. Use when preparing a submission, responding to rejection, reconciling privacy evidence, or separating upload blockers from cleanup.
ios-networking
dpearson2699/swift-ios-skills
Build, review, or improve networking code in iOS/macOS apps using URLSession with async/await, structured concurrency, and modern Swift patterns. Use when working with REST APIs, downloading files, uploading data, WebSocket connections, pagination, retry logic, request middleware, caching, background transfers, or network reachability monitoring. Also use when handling HTTP requests, API clients, network error handling, or data fetching in Swift apps.
Popular mobile skills
design-mobile-apps
designed-by-ai/skills
Design mobile app screens with Sleek, edit Sleek projects, and implement their designs in React Native or HTML.
ios-design
uizze.sh
Design and review iOS UI/UX for iPhone apps in SwiftUI, UIKit, or React Native. Use for mobile app design, screen redesigns, navigation flows, typography, forms, keyboard and safe-area layout, and accessibility checks. Apply Apple Human Interface Guidelines and consult real product references through the optional Uizze connection.
vercel-react-native-skills
vercel-labs/agent-skills
React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.
animate-expo
emilkowalski/skills
Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use animate.
xcode-project-setup
firebase/agent-skills
Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).
firebase-remote-config-basics
firebase/agent-skills
Manages Firebase Remote Config templates, feature flags, loading strategies, and SDKs (Android, iOS). Use when downloading/deploying remoteconfig JSON templates, managing version history/feature flags, setting in-app defaults, fetchAndActivate(), real-time listeners, or SDK setup. Don't use for Firebase Hosting, Auth, Firestore, Data Connect, Crashlytics, or App Hosting.