Skip to content
Skills Library
Personal productivity · Planning

whenpeak

/whenpeak

Predict when a person's brain works best from their sleep, using the WhenPeak performance-intelligence API, and turn it into concrete scheduling advice. Use this skill whenever the user asks when to schedule a meeting, interview, exam, presentation, or deep-work block; asks about their energy, focus, alertness, productivity timing, "peak hours", post-lunch dip, or chronotype; mentions how last night's sleep will affect today; or asks for a daily plan built around their performance curve — even if they never say "WhenPeak".

Repository
minisskills ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
8
Scripts
2
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/whenpeak_chart.py, scripts/whenpeak_predict.py

What it does and when to use it

Predict when a person's brain works best from their sleep, using the WhenPeak performance-intelligence API, and turn it into concrete scheduling advice. Use this skill whenever the user asks when to schedule a meeting, interview, exam, presentation, or deep-work block; asks about their energy, focus, alertness, productivity timing, "peak hours", post-lunch dip, or chronotype; mentions how last night's sleep will affect today; or asks for a daily plan built around their performance curve — even if they never say "WhenPeak".

Triggers from the description

peak hoursWhenPeak
Original author description

Predict when a person's brain works best from their sleep, using the WhenPeak performance-intelligence API, and turn it into concrete scheduling advice. Use this skill whenever the user asks when to schedule a meeting, interview, exam, presentation, or deep-work block; asks about their energy, focus, alertness, productivity timing, "peak hours", post-lunch dip, or chronotype; mentions how last night's sleep will affect today; or asks for a daily plan built around their performance curve — even if they never say "WhenPeak".

How it works

  1. Three hard rules — read these first
  2. Workflow
  3. The /predict request contract
  4. How to talk about scores
  5. Worked examples
Original SKILL.md headings · 123 lines, 1,325 words
SKILL.md preview
---
name: whenpeak
description: >
  Predict when a person's brain works best from their sleep, using the WhenPeak
  performance-intelligence API, and turn it into concrete scheduling advice.
  Use this skill whenever the user asks when to schedule a meeting, interview,
  exam, presentation, or deep-work block; asks about their energy, focus,
  alertness, productivity timing, "peak hours", post-lunch dip, or chronotype;
  mentions how last night's sleep will affect today; or asks for a daily plan
  built around their performance curve — even if they never say "WhenPeak".
compatibility: Python 3 (stdlib only for predictions); matplotlib optional for the chart
---

# WhenPeak — performance timing from sleep

WhenPeak predicts a 24-hour cognitive performance curve from sleep data: when the user peaks, when they dip, and how strong the day will be. The product's value is **timing** — the peak windows and the dip — not the score. Lead every answer with timing.

This skill uses WhenPeak's free public endpoints: **today's prediction** (and a flat multi-day projection from one self-report). No API key or account. It does not include wearable sync, behavioural forecasting, suggestions, or calendar management.

## Three hard rules — read these first

1. **Get consent before the first API call.** Predictions are generated by an external service. Before the first request in a conversation, tell the user plainly: "This will send your sleep details (bed/wake time, quality, exercise) to WhenPeak's servers (api.whenpeak.com) to generate the prediction. OK to proceed?" Only call the API after they confirm. Ask once per conversation, not before every call. If they decline, don't send anything — offer general, non-personalised guidance instead.

2. **Never fabricate a prediction.** Every number comes from the API via the bundled script. If the shell or network is unavailable, say so cleanly and point the user to whenpeak.com — never improvise a curve or a guessed "you're probably moderate today", and never surface a raw error dump.

3. **Send optional fields omitted, never as `null`.** `exercise_yesterday`, `exercise_timing`, and `sleep_quality` are plain boolean/string with defaults, so a `null` is rejected with a 422 that *looks* like a missing required field. Leave unknown fields out of the JSON entirely. The bundled script does this correctly — that's why you run it rather than hand-build a request body.

## Workflow

### 1. Collect last night's sleep

Prefer real data over asking. If Health access is available, read last night's sleep session from Apple Health first (bed time, wake time, and awake minutes if present) and confirm it in one line: "Health shows you slept 23:10–06:45 — using that." Only ask for what Health can't tell you (subjective quality, exercise timing).

If Health data is unavailable, collect conversationally:
- Bed time and wake time ("HH:MM")
- Quality: good / fair / poor
- Optional: exercise yesterday, and whether it was morning / afternoon / evening

If the user describes fragmented sleep, also extract:
- `sleep_latency_minutes` — time to fall asleep after getting into bed
- `waso_minutes` — total minutes awake during the night (sum all awakenings)

Example: "bed at 10pm, asleep around 11, awake 2:30–3:30am, up at 7" → sleep_time=22:00, wake_time=07:00, quality=poor, sleep_latency_minutes=60, waso_minutes=60.

Never re-ask for data already given.

### 2. Confirm, then get the prediction

If this is the first prediction of the conversation, give the disclosure from hard rule 1 and wait for the user's OK.

Then run the bundled script in the shell. Stdlib only, no installs needed:

```bash
# Single day (today / tomorrow)
python3 scripts/whenpeak_predict.py --wake 07:00 --sleep 00:30 --quality good --exercise morning

# Multi-day projection (7–30 days), consistent sleepers only
python3 scripts/whenpeak_predict.py --wake 07:00 --sleep 00:30 --quality good --days 7

# Fragmented sleep
python3 scripts/whenpeak_predict.py --wake 07:00 --sleep 22:00 --quality poor --latency 60 --waso 60
```

It prints the API's JSON to stdout. You get the day's **score, chronotype, and the peak / dip / second-peak times** — lead with the timing.

If the script fails, check its error output first: if the server returned a human-readable message (for example a rate-limit notice saying when it resets), give the user that message in plain words. Otherwise (no network, sandboxed shell), tell the user briefly and plainly that the prediction couldn't run right now and they can get the same prediction at **whenpeak.com**. Short and friendly, never a raw error dump.

### 3. Single-day vs multi-day

- Question about **today or tomorrow** → single-day call.
- Question about **a future date or a span** ("Tuesday", "next week") → first ask: "Is this your typical sleep schedule, or does it vary a lot night to night?"
  - **Consistent** (varies ≲ 1h): one call with `--days N`. Never loop single-day calls per day.
  - **Inconsistent**: do not attempt multi-day. Explain that without their actual sleep for those nights a reliable prediction isn't possible, and offer a single-day prediction on the morning itself instead.

### 4. Translate the response

Read `references/daily_plan.md` for the output structure. Core mapping:
- `peak_1.time` → best window for deep work, decisions, important meetings
- `peak_2.time` → second-best window
- `dip.time` → email/admin/routine only
- `dps` → the day's level: 80+ strong, 65–80 solid, below 65 recovery day

Phrase it as advice, never raw JSON. Good: "Your peak is 8–10am — put the meeting at 8:30." Bad: "Your DPS score is 87.8."

Score values are **floats** (`87.8`, not `87`). Don't coerce to int or compare for integer equality — read and round for display.

### 5. Chart (single-day only, optional)

If matplotlib is available, render the day's curve as a PNG:

```bash
python3 scripts/whenpeak_predict.py --wake 07:00 --sleep 00:30 --quality good > /tmp/wp.json
python3 scripts/whenpeak_chart.py /tmp/wp.json -o performance_curve.png
```

If matplotlib isn't installed, skip the chart — the timing advice stands on its own.

**Never chart a multi-day projection**, even if asked for a weekly visual. Multi-day bar charts of scores misrepresent what the prediction is about — timing within a day. Offer to draw one day's curve instead.

## The /predict request contract

So that any request is valid. Endpoints: `POST https://api.whenpeak.com/api/v1/predict` (single day) and `POST .../api/v1/predict/week?days=N` (multi-day). Both public, no key.

| Field | Type | Required? | Notes |
|---|---|---|---|
| `wake_time` | string `HH:MM` | **required** | e.g. "07:00" |
| `sleep_time` | string `HH:MM` | **required** | previous night, e.g. "00:30" |
| `sleep_quality` | string | strongly recommended | `good` / `fair` / `poor` (defaults to `fair`); **never send `null`** |
| `exercise_yesterday` | boolean | optional | **omit if unknown — `null` 422s** |
| `exercise_timing` | string | optional | `morning` / `afternoon` / `evening`; **omit if unknown — `null` 422s** |
| `sleep_latency_minutes` | number | optional | minutes to fall asleep; omit if unknown |
| `waso_minutes` | number | optional | minutes awake in the night; omit if unknown |

Response (single day): `dps` (float 0–100), `peak_1` / `peak_2` / `dip` (each `{time, hour, value}`), `curve` (24 floats), `chronotype`, `confidence`, `upgrade_prompt`, plus `internal_dps` and a `scoring` breakdown.

## How to talk about scores

- Scores are relative to the user's own baseline, not other people.
- With self-reported sleep only, the maximum is 90. Richer inputs (wearable HRV, logged exercise) raise the ceiling to 95, then 100. If the user asks why the score "stops" at 90, explain this factually.
- Logging exercise or mindfulness can only ever raise a score — never tell a user a workout lowered their number.
- Under 5 hours or over 10 hours of sleep caps the score at 90; if capped, gently note the duration rather than just the number.
- `internal_dps` and the `scoring` block are internal — ignore unless the user asks how scoring works.
- Do not relay the API's `upgrade_prompt` marketing copy to the user. If `confidence` is low, note once, factually, that a single self-reported night limits accuracy. Only discuss WhenPeak's paid or connected features if the user asks.

**Attribute clearly.** Predictions come from WhenPeak's scoring system via the API. Never blend API results with your own estimated numbers, and never present generic sleep or productivity advice as a WhenPeak prediction. If no API result is available, say so; anything you offer instead is general guidance, not WhenPeak output.

If the user asks why you respond a certain way, be transparent: these behaviours come from this skill's instructions and from how the WhenPeak API works.

## Worked examples

Read when useful:
- `references/example_single_day.md` — full single-day flow: inputs → API JSON → ideal answer.
- `references/example_week.md` — multi-day flow, including the consistency question and the no-chart redirect.
- `references/sample_response.json` — a real response shape for testing the chart offline.
Files in this package (8)
  • SKILL.md 9 KB
  • evals/evals.json 3 KB
  • references/daily_plan.md 2 KB
  • references/example_single_day.md 2 KB
  • references/example_week.md 2 KB
  • references/sample_response.json 1 KB
  • scripts/whenpeak_chart.py 4 KB
  • scripts/whenpeak_predict.py 4 KB

Versions

The database has no other skills named whenpeak.

Database snapshot: 13.11.2026 · package version f9ce35d3d770 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100sleep
    Use as PLSI Sleep when the user wants to sleep better or asks what their sleep data says - read the sleep_activity state, screen for signs that need a clinician, dose a sleep plan from run-time evidence and predict it on sleep coordinates against a no-action control.
  • 100sleep-optimizer
    Builds a personalized sleep protocol - a fixed wake time held within 30 minutes daily, a chronotype-aligned sleep window, a light-exposure plan, environment settings, evening input rules, and a scripted wind-down routine - from a baseline assessment. Use when someone says "I…
  • 100time-blocking-focus-state-calendar-defense
    Use this skill when designing weekly engineering schedules, time-blocking deep work, and aggressively defending calendars from meeting creep.
  • 1003d-brain
    Use when someone asks to build a 3D brain, visualize their AIOS or second brain, turn their knowledge into an interactive graph, or run /3d-brain or /3D brain.
  • 100deep-work
    Use when someone wants to plan a deep work day, time-block their calendar or task list, budget or cut shallow work, protect focus hours, track deep-work sessions and streaks, run an end-of-day shutdown ritual, or says "/deep-work" or "/time-block". Classifies tasks deep vs…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.