battery-stats

Files (3)

• SKILL.md
• openai.yaml · agents/
• battery-stats.py · scripts/

SKILL.md (first lines)

# Battery Stats

Use this skill to answer battery-status questions directly from the local Mac. Do not ask the user to run commands unless they explicitly want the commands.

## Quick Start

Run the bundled script from this skill directory:

```bash
python3 scripts/battery-stats.py
```

Use JSON when another tool or follow-up calculation needs structured data:

```bash
python3 scripts/battery-stats.py --json
```

## Workflow

1. Confirm the current machine is macOS. If `pmset`, `ioreg`, or `system_profiler` is missing, report that the skill only supports macOS battery telemetry.
2. Run `scripts/battery-stats.py`.
3. Read the `Current Battery` section first:
   - `current_drain_w` is the current whole-battery drain in watts, computed from battery voltage and amperage.
   - `battery_power_telemetry_w` is the battery telemetry rail when available. Treat it as secondary because it can diverge from the direct voltage/current reading.
   - These values are instantaneous and can move quickly with CPU, display brightness, network, browser, and background work.
4. Read the `Health` section:
   - Prefer health calculated from nominal capacity divided by design capacity.
   - Include cycle count and macOS condition when available.
5. Read the `Runtime Estimate` section:
   - Prefer the human `Screen-on weighted full runtime` line, or `runtime.screen_on_robust.weighted_full_runtime` in JSON, for "how long does the battery last during use?"
   - Treat the human `Wall-clock battery runtime including sleep` line, or `runtime.wall_clock_usable.weighted_full_runtime` in JSON, as standby-inclusive context because it includes sleep and maintenance wakes.
   - If the current discharge session is included, call it provisional.
6. Read the `Power Usage Estimate` section:
   - Use `Average screen-on draw`, or `screen_on_robust.weighted_avg_power_w` in JSON, as the best single number for typical watts during real screen-on use.
   - Use `Median session draw` and `Typical range (25-75%)` to describe normal variation.
   - Use `Heavier sessions (90%)` and `Session draw range` to describe heavier workloads without overreacting to one noisy session.
   - Prefer the longer stored history when available; otherwise use the regular `pmset` history.
7. Answer with concrete numbers and a short interpretation. Include the log span so the user knows what period the average covers.

## Interpretation Rules

- macOS does not provide a Windows-style generated `batteryreport`; the useful local sources are `pmset -g batt`, `ioreg -rn AppleSmartBattery -r`, `system_profiler SPPowerDataType`, and `pmset -g log`.
- Do not overstate precision. Report current drain to about one decimal watt and runtime to the nearest 5-15 minutes.
- When current macOS "time remaining" and wattage-derived projections differ, explain that both are estimates and current drain changes second by second.
- Explain average watt usage as an estimate derived from observed battery-percent drop, elapsed screen-on time, and current usable battery energy in Wh. It is useful for describing the user's real workflow, not for hardware benchmarking.
- A good wording pattern is: "During real screen-on use, this Mac averages about X W. Normal sessions are roughly A-B W, heavier sessions are around C W, and that lines up with about Y hours of practical runtime."
- Do not include battery serial numbers or other hardware identifiers unless the user explicitly asks for them.
- If recent history has too few meaningful discharge sessions, say that the average is not reliable and fall back to the current macOS estimate plus health and drain.

From kjendrzyca/public-skills, MIT.

More from kjendrzyca/public-skills