Oura Ring Data

Access Oura Ring health data using the ouracli CLI tool. Use when user asks about "oura data", "sleep stats", "activity data", "heart rate", "readiness score", "stress levels", or wants health metrics from their Oura Ring.

Security Scan

The skill's instructions say it needs an Oura personal access token and the ouracli CLI, but the package metadata does not declare those requirements and there are code files present without an install spec — the pieces don't line up.

Purpose & Capability

The SKILL.md clearly describes running the ouracli CLI and requires a PERSONAL_ACCESS_TOKEN, which is coherent with the described purpose. However, the registry metadata lists no required binaries and no required environment variables, which under-declares the actual needs. The presence of packaged ouracli source files but no install instructions increases the mismatch.

Instruction Scope

Instructions explicitly tell the agent to run ouracli via Bash and to check for a PERSONAL_ACCESS_TOKEN stored in secrets/oura.env or ~/.secrets/oura.env. That means the agent will be expected to read local secret files and run shell commands — appropriate for a CLI but sensitive. The SKILL.md does not instruct any unrelated data access, but it does assume and require access to local secret paths that the metadata does not declare.

Install Mechanism

No install spec is provided (instruction-only), yet the skill bundle contains full ouracli source files and tests. Either the skill expects ouracli to already be on PATH or the package forgot to include installation steps. This is an inconsistency and may cause runtime failures or unexpected behavior if the environment differs from the author's assumptions.

Credentials

The SKILL.md requires a PERSONAL_ACCESS_TOKEN (from secrets/oura.env or ~/.secrets/oura.env), which is proportionate to accessing the Oura API. But the declared requirements list no environment variables and no primary credential — the credential requirement is missing from metadata. Asking the agent to read local secret files is sensitive and should be explicitly declared.

Persistence & Privilege

No 'always: true' or other elevated persistence flags are set, and model invocation flags are default. The skill does not request permanent inclusion or explicit autonomous invocation privileges beyond the platform defaults.

What to consider before installing

This skill's README/instructions require the ouracli CLI and an Oura PERSONAL_ACCESS_TOKEN stored in a secrets file, but the registry metadata doesn't declare those needs and there is no install step. Before installing or enabling it: (1) confirm how ouracli is expected to be provided (is it preinstalled or should the package install it?), (2) do not place your token in a plaintext file unless you trust the environment — prefer supplying a token through the platform's secure secret mechanism, (3) ask the publisher to update metadata to list PERSONAL_ACCESS_TOKEN as a required credential and to add a clear install spec, and (4) review the included source (client.py) to verify network behavior and that no unexpected data exfiltration occurs. If you cannot verify these things, treat the skill as untrusted.

Oura Ring Data Access

Retrieves health and fitness data from the Oura Ring using the ouracli command-line interface.

CRITICAL: Authentication Required

ALWAYS check for authentication before running ouracli commands. The tool requires a PERSONAL_ACCESS_TOKEN environment variable.

• Token location: secrets/oura.env or ~/.secrets/oura.env
• If commands fail with authentication errors, inform the user to obtain a token from: https://cloud.ouraring.com/personal-access-tokens

Available Data Types

Core Health Metrics

• activity - Daily activity (steps, MET values, calories)
• sleep - Sleep data (stages, efficiency, heart rate)
• readiness - Readiness scores and contributors
• heartrate - Time-series heart rate data (5-minute resolution)
• spo2 - Blood oxygen saturation data
• stress - Daily stress levels

Additional Data

• workout - Workout sessions
• session - Activity sessions
• tag - User-added tags
• rest-mode - Rest mode periods
• personal-info - User profile information
• all - All available data types

Date Range Specification

✅ SUPPORTED FORMATS (Use These!)

# Single date (no quotes needed)
ouracli activity 2025-12-25
ouracli sleep today
ouracli heartrate yesterday

# Relative ranges from today (MUST use quotes)
ouracli activity "7 days"      # Last 7 days including today
ouracli sleep "30 days"        # Last 30 days
ouracli readiness "2 weeks"    # Last 2 weeks
ouracli stress "1 month"       # Last month

# Date + duration (MUST use quotes)
ouracli activity "2025-12-01 28 days"    # 28 days starting Dec 1
ouracli sleep "2025-09-23 7 days"        # Week starting Sept 23

⚠️ CRITICAL: Use quotes when the date range contains spaces!

❌ UNSUPPORTED FORMATS (DO NOT USE)

# ❌ WRONG - Two separate dates
ouracli activity 2025-09-23 2025-09-30

# ❌ WRONG - "to" syntax
ouracli activity "2025-09-23 to 2025-09-30"

# ❌ WRONG - Range operators
ouracli activity "2025-09-23..2025-09-30"

# ❌ WRONG - Relative past expressions
ouracli activity "3 months ago"

Converting Date Ranges

If user requests data between two specific dates:

Step 1: Calculate the number of days (inclusive)

Example: Sept 23 to Sept 30 = 7 days
         Dec 1 to Dec 31 = 30 days

Step 2: Use the "date + duration" format

# ✅ CORRECT
ouracli activity "2025-09-23 7 days"
ouracli activity "2025-12-01 30 days"

Output Formats

ALWAYS use --json for programmatic data analysis. This is the most reliable format for parsing.

# ✅ RECOMMENDED for AI analysis
ouracli activity "7 days" --json

# Other formats (human-readable)
ouracli activity today --tree        # Default: tree structure
ouracli activity "7 days" --markdown # Markdown with charts
ouracli activity "7 days" --html > activity.html  # Interactive HTML charts
ouracli activity "7 days" --dataframe  # Pandas DataFrame format

Common Usage Patterns

Quick Data Check

# Today's activity
ouracli activity today --json

# Recent sleep data
ouracli sleep "7 days" --json

# Current readiness
ouracli readiness today --json

Detailed Analysis

# Weekly health summary
ouracli all "7 days" --json

# Monthly activity report
ouracli activity "30 days" --json

# Heart rate for specific date
ouracli heartrate "2025-12-15 1 days" --json

Multi-Day Reports

# All data grouped by day (HTML report)
ouracli all "7 days" --by-day --html > weekly-report.html

# All data grouped by type
ouracli all "7 days" --by-method --json

Key Notes

Readiness Contributors Warning

⚠️ IMPORTANT: The contributors.resting_heart_rate field in readiness data is a SCORE (0-100), NOT actual BPM:

• Low score (19, 47) = RHR elevated vs. baseline (negative impact)
• High score (95, 100) = RHR optimal vs. baseline (positive impact)
• Actual BPM values are in the heartrate command output

DO NOT interpret contributor scores as actual heart rate measurements.

Oura API Quirks

• Single-day queries sometimes return empty results due to timezone issues
• Use date ranges (e.g., "YYYY-MM-DD 2 days") for more reliable results
• When querying specific dates, consider adding a buffer day

Data Availability

• Ring must be synced recently for current data
• Historical data availability depends on user's Oura subscription
• If no data is returned, suggest broader date range or check sync status

Troubleshooting

Error: "Got unexpected extra argument"

Cause: Used two separate date arguments instead of one quoted range

# ❌ WRONG
ouracli activity 2025-09-23 2025-09-30

# ✅ CORRECT
ouracli activity "2025-09-23 7 days"

Error: "Invalid date specification"

Cause: Used unsupported syntax like "to", "..", or relative expressions

# ❌ WRONG
ouracli activity "2025-09-23 to 2025-09-30"

# ✅ CORRECT
ouracli activity "2025-09-23 7 days"

No Data Returned

Solutions:

1. Try a broader date range: ouracli activity "7 days" --json
2. Add buffer days: ouracli activity "2025-12-25 2 days" --json
3. Check if Ring has synced recently
4. Verify date is within available data range

Example Responses to User Queries

"Show me my activity for the last week"

ouracli activity "7 days" --json

"What was my sleep like last night?"

ouracli sleep today --json

"How was my readiness in December?"

ouracli readiness "2025-12-01 30 days" --json

"Get all my data from Sept 23 to Sept 30"

# Calculate: Sept 30 - Sept 23 = 7 days
ouracli all "2025-09-23 7 days" --json

"Show my heart rate from yesterday"

ouracli heartrate yesterday --json

Quick Reference

User Intent	Command
Today's activity	ouracli activity today --json
Last week's sleep	ouracli sleep "7 days" --json
Current readiness	ouracli readiness today --json
Heart rate today	ouracli heartrate today --json
Monthly summary	ouracli all "30 days" --json
Specific date range	ouracli [TYPE] "YYYY-MM-DD N days" --json
All data types	ouracli all "7 days" --json

Notes

• Always prefer --json format for AI analysis
• Use quotes for all date ranges with spaces
• Calculate day counts for specific date ranges
• Check authentication if commands fail
• Consider timezone quirks when querying specific dates