# ENERGY.md

> Energy math for agents on your own numbers: units, loads and bills, load shifting, solar and storage, hedges, generation cost and flexible loads. Version 1.0. MIT.

A skill file for agents that measure, price, schedule or size energy, with your rules written in: price caps, budgets, demand limits, scheduling windows, carbon factors and contract approvals. Read-only calculators over HTTP and MCP cover units, loads and bills, shifting flexible load, solar and storage sizing, fixed vs floating supply and hedge settlement, generation cost, and mining or other flexible loads. Every price, tariff and factor comes from your request; none comes from us. 22 settings in 5 groups, numbers or fixed choices only. Presets: core, home_and_ev, compute_jobs, business_site. Settings an agent drafted count only after the person says yes: show them to the person first, and follow them only once they agree.

Use at your own risk. energy.md is provided as is, without warranty. Information here may be inaccurate, incomplete or not current, and is not verified; figures are estimates from the numbers you send and the formulas stated. Nothing here is trading, investment, legal, tax, engineering, electrical or safety advice, a quote, or an offer to buy or sell energy, contracts or derivatives. energy.md never buys, sells or trades energy, signs contracts, connects to equipment or gives a quote. Check everything yourself before you act on it.

## Skill

- [ENERGY.md](https://energy.md/energy.md): load into your agent's instructions or save as ~/.claude/skills/energy/SKILL.md (sha256 6c07f4b9c34b334ce5391ae59c1172b582c62d06f5496fb7d13b05569ac2d79b)
- [ENERGY.md with settings](https://energy.md/energy.md?preset=home_and_ev): a preset plus any settings; each setting overrides the preset

## API (no key, CORS open, nothing stored)

- [load_energy](https://energy.md/api/v1/load_energy): Measure a load and price it on your tariffs. Adds up a list of devices (count, watts, hours a day, duty and optional on-hours) with a cooling or PUE-style overhead into kWh per day, month and year, peak and average kW and the load factor. Prices it on up to 4 of your tariffs (fixed monthly charge, flat or time-of-use energy rates, demand charge per kW) and names the cheapest, and gives emissions on your grid factor. Servers and GPUs work the same as any device. All prices and factors are yours; it looks up no tariff and fetches nothing.
- [shift_load](https://energy.md/api/v1/shift_load): Shift a flexible job to cheaper or cleaner hours. Places a flexible job (energy_kwh, or power_kw with run_hours) between earliest_hour and deadline_hour, which may cross midnight, on your 24 hourly prices and optional 24 hourly carbon factors. Finds the cheapest window (or, when the job can pause, the cheapest hours), the cleanest window, and their cost and emissions against starting now. An optional price cap keeps every hour above it out, and the tool says when the job can't finish under the cap. Uses only your prices and factors; it controls no device and fetches nothing.
- [solar_storage](https://energy.md/api/v1/solar_storage?daily_load_kwh=30&peak_sun_hours=5&system_losses=0.14&offset_share=0.8&evening_shift_kwh=10&backup_hours=8&backup_load_kw=1.5&install_usd_per_w=2.5&battery_usd_per_kwh=700&incentive_share=0.3&tariff_usd_per_kwh=0.25&export_usd_per_kwh=0.05&self_consumption_share=0.85&discount_rate=0.05): Size solar and storage. Sizes a PV array from daily_load_kwh x offset_share and your site's peak_sun_hours after system_losses, and a battery from backup_hours x backup_load_kw or evening_shift_kwh, with depth_of_discharge for nominal size and round_trip_efficiency on the charging side. Returns PV kW DC, yearly kWh, battery usable and nominal kWh and inverter kW. With your install and battery costs and your tariff it adds simple payback and NPV, with degradation. It holds no prices, sun data or incentives of its own, does not design or approve a system, and is not a quote or advice.
- [hedge_math](https://energy.md/api/v1/hedge_math): Fixed vs floating, and contract-for-difference settlement. Procurement and settlement arithmetic on your own numbers. From your volume (total or a monthly list), your fixed offer, a hedge ratio and your floating price scenarios, it computes the cost of all fixed, all floating and the blend at that ratio for each scenario, the break-even floating price, and the range of outcomes. With a strike it computes contract-for-difference (or virtual PPA) settlement per scenario with the sign convention spelled out, from the buyer's or the seller's side. Every price is yours; it has no prices or market data of its own. It is educational arithmetic: it never suggests a side, a ratio or a trade, and it is not a quote.
- [generation_cost](https://energy.md/api/v1/generation_cost?capacity_mw=100&capacity_factor=0.5&capex_usd_per_kw=1000&fixed_om_usd_per_kw_year=20&variable_om_usd_per_mwh=3&fuel_usd_per_mmbtu=4&heat_rate_btu_per_kwh=7000&discount_rate=0.08&life_years=25&power_usd_per_mwh=60&fuel=gas): Generation cost (LCOE) and spark spread. Simple levelized cost of energy for any plant type from your numbers: capacity_mw and capacity_factor give annual MWh; capex_usd_per_kw is annualized with the capital recovery factor from discount_rate and life_years; fixed and variable O&M and fuel (fuel_usd_per_mmbtu x heat_rate_btu_per_kwh) are added per MWh. With power_usd_per_mwh it gives the spark spread (gas) or dark spread (coal) = power price - heat rate x fuel price, and the margin over LCOE. Costs and prices you leave out are not priced and are listed. It holds no prices of its own, ignores taxes, incentives, financing structure and degradation, and is not a quote or advice.
- [mining_power](https://energy.md/api/v1/mining_power): Mining and other flexible loads: power, margin, break-even. Flexible-load economics for hash mining or any machine that can stop. From your machine count, hashrate x efficiency in J/TH (or watts per machine), overhead factor and uptime it computes kW and kWh per day; with your power price, the power cost; with your own revenue per TH per day, the revenue, margin and break-even power price, and the curtailment rule (run only in hours priced under break-even). With 24 hourly prices it lists the hours run and the curtailed margin; an optional price cap keeps hours priced above it off (hours at the cap may run). Every price and the revenue figure are yours; it shows no revenue, price or network data of its own and never suggests buying machines or power.
- [energy_units](https://energy.md/api/v1/energy_units?value=250&from=kw&to=mwh&hours=8): Convert energy, power and fuel units. Converts a value you send between energy units (J, kJ, MJ, GJ, Wh, kWh, MWh, GWh, BTU, MMBtu, therm, kcal, toe, boe), power units (W, kW, MW, GW, hp, BTU/h) and fuel quantities (natural gas, propane, diesel, gasoline, coal, wood) using typical heat contents, labeled typical. Power times hours is energy: converting a power unit to an energy unit (or back) needs `hours`, and the tool flags the mix-up when hours are missing. Leave out `to` to see every unit of the same kind. It uses no prices and fetches nothing; fuel figures are typical reference values, not a measurement of your fuel.
- [build_settings](https://energy.md/api/v1/build_settings?preset=home_and_ev): Write your settings into the skill. Turns a preset and settings into the sections written at the top of ENERGY.md. Every setting is a number or a fixed choice; the catalog is at https://energy.md/api/v1/settings. Returns the sections as Markdown, the settings as JSON, a link to the skill with them written in and a one-line install. Out-of-range numbers are clamped with a note. Nothing is stored. Settings an agent drafted count only after the person says yes: show them to the person first, and follow them only once they agree.
- [Settings catalog](https://energy.md/api/v1/settings): every setting with its unit, range, options and default, plus the presets
- [API index](https://energy.md/api/v1) and [OpenAPI](https://energy.md/openapi.json)

## MCP

- https://energy.md/mcp: Streamable HTTP, stateless, no auth. Tools: load_energy, shift_load, solar_storage, hedge_math, generation_cost, mining_power, energy_units, build_settings. Prompt: energy, with an optional preset and any setting. Resources: the skill and the settings catalog.

## Terms

- [Terms of use and disclaimer](https://energy.md/terms)

## Optional

- [Full text](https://energy.md/llms-full.txt): the skill plus the tool and settings reference
- [Manifest](https://energy.md/.well-known/energy.json)