Oura Ring Analytics

Oura Ring data integration and analytics. Fetch sleep scores, readiness, activity, HRV, and trends from the Oura Cloud API. Generate automated reports, correlations with productivity, and trigger-based alerts for low recovery days. Requires OURA_API_TOKEN (get at cloud.ouraring.com).

Security Scan

The skill's code, instructions, and required environment variables are consistent with an Oura data analytics tool — it only needs a personal Oura token and optional Telegram settings and stores data locally.

Purpose & Capability

Name/description match the implementation: Python scripts implement an Oura API client, analysis, reporting, and Telegram-based alerts. Declared requirement (python3 + OURA_API_TOKEN) is appropriate. Optional env vars (TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID / USER_TIMEZONE / OURA_OUTPUT_DIR) are consistent with alerting, timezone handling, and output location. Minor note: registry lists source as unknown but SKILL.md metadata and README reference a GitHub repo; you may want to verify the upstream repo before installing.

Instruction Scope

SKILL.md instructs running included Python scripts, setting OURA_API_TOKEN, and optionally configuring cron jobs that run local scripts. The runtime instructions reference only the declared env vars and local paths; they do not instruct reading unrelated system files or exfiltrating data. The cron examples invoke OpenClaw gateway commands and local shell scripts — normal for automation, but you should replace placeholder paths and chat IDs before use.

Install Mechanism

No install spec is provided (instruction-only from the registry), but the package does include many Python script files and a requirements.txt (pytz, pyyaml). There are no remote download/install actions or obscure URLs in the install metadata. Installation advice in README (git clone + pip install -r requirements.txt) is standard and proportional.

Credentials

The only required env var is OURA_API_TOKEN, which is necessary for the Oura Cloud API. Optional Telegram tokens/IDs are reasonable for alert delivery. One small concern to review: README suggests creating a token with 'select all scopes' — you should create/limit the token to the minimal read scopes required by the skill if Oura supports scoping. The README and SECURITY.md offer multiple storage suggestions (e.g., ~/.openclaw/.env, systemd user secrets); follow your own secret management policies.

Persistence & Privilege

The skill does not request always:true and does not modify other skills or global agent configs. It stores cached data and reports under ~/.oura-analytics (or OURA_OUTPUT_DIR), which is expected for this functionality. The skill can be invoked autonomously by the agent (default platform behavior); combine that with your agent policies if you want to restrict automatic runs.

Assessment

This package appears to be a legitimate Oura data client and analytics tool. Before installing, verify the upstream repository (SKILL.md points to a GitHub repo) and inspect the code yourself if you can. When creating the Oura personal access token, grant the minimum read scopes necessary rather than 'all scopes.' Protect your tokens (do not commit them to git); the skill stores data locally under ~/.oura-analytics — clear or encrypt this if you are concerned about sensitive health data. If you use Telegram alerts, know that a Telegram bot token and chat ID are required and will be used to send messages. Finally, if you do not want the agent to run this skill autonomously, configure the agent/skill permissions accordingly.

Oura Analytics

Quick Start

# Set Oura API token
export OURA_API_TOKEN="your_personal_access_token"

# Fetch sleep data (last 7 days)
python {baseDir}/scripts/oura_api.py sleep --days 7

# Get readiness summary
python {baseDir}/scripts/oura_api.py readiness --days 7

# Generate weekly report
python {baseDir}/scripts/oura_api.py report --type weekly

When to Use

Use this skill when:

• Fetching Oura Ring metrics (sleep, readiness, activity, HRV)
• Analyzing recovery trends over time
• Correlating sleep quality with productivity/events
• Setting up automated alerts for low readiness
• Generating daily/weekly/monthly health reports

Core Workflows

1. Data Fetching

export PYTHONPATH="{baseDir}/scripts"
python - <<'PY'
from oura_api import OuraClient

client = OuraClient(token="YOUR_TOKEN")
sleep_data = client.get_sleep(start_date="2026-01-01", end_date="2026-01-16")
readiness_data = client.get_readiness(start_date="2026-01-01", end_date="2026-01-16")
print(len(sleep_data), len(readiness_data))
PY

2. Trend Analysis

export PYTHONPATH="{baseDir}/scripts"
python - <<'PY'
from oura_api import OuraClient, OuraAnalyzer

client = OuraClient(token="YOUR_TOKEN")
sleep_data = client.get_sleep(start_date="2026-01-01", end_date="2026-01-16")
readiness_data = client.get_readiness(start_date="2026-01-01", end_date="2026-01-16")

analyzer = OuraAnalyzer(sleep_data, readiness_data)
avg_sleep = analyzer.average_metric(sleep_data, "score")
avg_readiness = analyzer.average_metric(readiness_data, "score")
trend = analyzer.trend(sleep_data, "average_hrv")
print(avg_sleep, avg_readiness, trend)
PY

3. Alerts

python {baseDir}/scripts/alerts.py --days 7 --readiness 60 --efficiency 80

Environment

Required:

• OURA_API_TOKEN

Optional (used for alerts/reports/timezone/output):

• KESSLER_TELEGRAM_BOT_TOKEN (fallback to TELEGRAM_BOT_TOKEN)
• TELEGRAM_CHAT_ID
• USER_TIMEZONE
• OURA_OUTPUT_DIR

Scripts

• scripts/oura_api.py - Oura Cloud API wrapper with OuraAnalyzer and OuraReporter classes
• scripts/alerts.py - Threshold-based notifications (CLI: python {baseDir}/scripts/alerts.py --days 7 --readiness 60)
• scripts/weekly_report.py - Weekly report generator

References

• references/api.md - Oura Cloud API documentation
• references/metrics.md - Metric definitions and interpretations

Automation (Cron Jobs)

Cron jobs are configured in OpenClaw's gateway, not in this repo. Add these to your OpenClaw setup:

Daily Morning Briefing (8:00 AM)

openclaw cron add \
  --name "Daily Oura Health Report (Hybrid)" \
  --cron "0 8 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --wake next-heartbeat \
  --deliver \
  --channel telegram \
  --target "<YOUR_TELEGRAM_CHAT_ID>" \
  --message "Run the daily Oura health report with hybrid format: Execute bash /path/to/your/scripts/daily-oura-report-hybrid.sh"

Weekly Sleep Report (Sunday 8:00 AM)

openclaw cron add \
  --name "Weekly Oura Sleep Report" \
  --cron "0 8 * * 0" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --wake next-heartbeat \
  --deliver \
  --channel telegram \
  --target "<YOUR_TELEGRAM_CHAT_ID>" \
  --message "Run weekly Oura sleep report: bash /path/to/your/oura-weekly-sleep-alert.sh"

Daily Obsidian Note (8:15 AM)

openclaw cron add \
  --name "Daily Obsidian Note" \
  --cron "15 8 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --wake next-heartbeat \
  --message "Create daily Obsidian note with Oura data. Run: source /path/to/venv/bin/activate && python /path/to/daily-note.py"

Note: Replace /path/to/your/ with your actual paths and <YOUR_TELEGRAM_CHAT_ID> with your Telegram channel/group ID.