ouraclaw_skill

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.