home / skills / montagao / skills / ouraclaw

ouraclaw skill

safe

/ouraclaw

This skill fetches Oura Ring sleep data using the ouraclaw CLI and presents scores, sleep sessions, HRV, and bedtimes.

npx playbooks add skill montagao/skills --skill ouraclaw

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.4 KB

---
name: ouraclaw
description: Fetch Oura Ring sleep data using the ouraclaw CLI. Use when the user asks about their sleep score, sleep data, sleep stages, HRV, heart rate during sleep, bedtimes, or any Oura Ring data. Triggers on "sleep score", "how did I sleep", "oura data", "sleep data", "last night's sleep", "sleep quality", "HRV", or any request for Oura Ring metrics.
---

# Ouraclaw

Fetch Oura Ring sleep data via the `ouraclaw` CLI. Outputs JSON to stdout.

## Ensure ouraclaw is installed

```bash
which ouraclaw
```

If not found:

```bash
git clone https://github.com/montagao/ouraclaw.git ~/projects/ouraclaw
cd ~/projects/ouraclaw && bun install && bun link
```

If auth is needed (no tokens in `.env`), run `cd ~/projects/ouraclaw && ouraclaw auth`.

## Commands

```bash
# Last night's sleep score
ouraclaw score

# Date range
ouraclaw score --start 2025-02-01 --end 2025-02-15

# Detailed sleep sessions (stages, HR, HRV, bedtimes)
ouraclaw sleep

# Date range
ouraclaw sleep --start 2025-02-01 --end 2025-02-15
```

## Extracting fields with jq

```bash
ouraclaw score | jq '.data[0].score'
ouraclaw sleep | jq '.data[0] | {bedtime_start, bedtime_end}'
ouraclaw score --start 2025-02-01 --end 2025-02-15 | jq '[.data[] | {day, score}]'
```

## Error handling

- **"No access token"**: Run `cd ~/projects/ouraclaw && ouraclaw auth`.
- **401 after auto-refresh fails**: Re-run `ouraclaw auth`.

Overview

This skill fetches Oura Ring sleep and physiological data using the ouraclaw CLI and returns structured JSON output. It provides quick access to sleep score, detailed sleep sessions, sleep stages, heart rate, and HRV for requested date ranges or the most recent night. Use it to answer questions about sleep quality, trends, and nightly metrics directly from your Oura account.

How this skill works

The skill calls the ouraclaw command-line tool to retrieve Oura data and emits the CLI JSON output. It supports commands for the most recent sleep score or detailed sleep sessions and accepts start/end date ranges. Basic error handling is surfaced (for example, prompts to authenticate when there is no access token). The output is intended for downstream parsing or direct extraction with tools like jq.

When to use it

When the user asks “How did I sleep?” or requests last night’s sleep score.
To fetch detailed sleep sessions including stages, bedtimes, HR, and HRV.
When the user requests Oura metrics across a date range (daily scores or sessions).
To extract a specific field (bedtime, score, HRV) for reporting or visualization.
When authentication errors appear and the user needs guidance to re-authenticate.

Best practices

Ensure ouraclaw is installed and callable in the environment where the skill runs.
Authenticate (ouraclaw auth) if you see a missing access token or 401 errors.
Specify start and end dates for multi-day queries to limit returned data.
Parse the returned JSON with a tool like jq to extract only the fields you need.
Handle empty results gracefully (no sleep session for a given date).

Example use cases

Get last night’s sleep score to answer “What was my sleep score last night?”
Retrieve sleep sessions between two dates for weekly trend analysis.
Extract bedtime_start and bedtime_end to calculate average bedtimes.
Fetch HRV and night heart rate for integration into a health dashboard.
Guide a user to re-run authentication when the CLI reports no access token.

FAQ

What if ouraclaw reports “No access token”?

Run the ouraclaw auth command in the ouraclaw project directory to re-authenticate.

How do I get data for a date range?

Provide --start and --end flags to the ouraclaw score or ouraclaw sleep commands to limit results by date.

Can I extract only the sleep score from the JSON?

Yes. Pipe the CLI output to jq and select .data[].score or the specific index you need.