Skill: poisondminds/fitbit-insights (version 1.0.0)

--- name: fitbit description: Fitbit fitness data integration. Use when the user wants fitness insights, workout summaries, step counts, heart rate data, sleep analysis, or to ask questions about their Fitbit activity data. Provides AI-powered analysis of fitness metrics. --- # Fitbit Fitness Insights Get AI-powered insights from your Fitbit data. Query your fitness metrics, analyze trends, and ask questions about your activity. ## Features - 📊 Daily activity summaries (steps, calories, distance, active minutes) - 💓 Heart rate data and zones - 😴 Sleep tracking and analysis - 🏃 Workout/activity logs - 📈 Weekly and trend analysis - 🤖 AI-powered insights and Q&A ## Prerequisites **Requires:** Fitbit OAuth access token Setup steps in `references/fitbit-oauth-setup.md` ## Commands ### Get Profile ```bash FITBIT_ACCESS_TOKEN="..." python3 scripts/fitbit_api.py profile ``` ### Daily Activity ```bash python3 scripts/fitbit_api.py daily [date] # Examples: python3 scripts/fitbit_api.py daily # Today python3 scripts/fitbit_api.py daily 2026-02-08 # Specific date ``` Returns: steps, distance, calories, active minutes (very/fairly/lightly/sedentary), floors ### Steps Range ```bash python3 scripts/fitbit_api.py steps <start_date> <end_date> ``` Example: ```bash python3 scripts/fitbit_api.py steps 2026-02-01 2026-02-07 ``` Returns: total steps, average steps, daily breakdown ### Heart Rate ```bash python3 scripts/fitbit_api.py heart [date] ``` Returns: resting heart rate, heart rate zones with minutes in each zone ### Sleep Data ```bash python3 scripts/fitbit_api.py sleep [date] ``` Returns: duration, efficiency, start/end times, sleep stages ### Logged Activities ```bash python3 scripts/fitbit_api.py activities [date] ``` Returns: workouts/activities logged (name, duration, calories, distance) ### Weekly Summary ```bash python3 scripts/fitbit_api.py weekly ``` Returns: 7-day summary of steps and key metrics ## AI Insights Usage When user asks fitness questions, use the API to fetch relevant data, then provide insights: **Example queries:** - "How did I sleep last night?" → fetch sleep data, analyze quality - "Did I hit my step goal this week?" → fetch weekly summary, compare to goals - "What was my average heart rate during workouts?" → fetch heart + activities, analyze - "Am I more active on weekdays or weekends?" → fetch range data, compare patterns **Analysis approach:** 1. Identify what data is needed 2. Fetch via appropriate API command 3. Analyze the data 4. Provide insights in conversational format ## Example Responses **User:** "How did I do this week?" **Agent:** 1. Fetch weekly summary 2. Fetch recent sleep data 3. Respond: "You had a solid week! Averaged 8,234 steps/day (up 12% from last week). Hit your 10k step goal 4 out of 7 days. Sleep averaged 7.2 hours with 85% efficiency. CrossFit sessions on Mon/Wed/Fri looking consistent!" **User:** "Did I exercise today?" **Agent:** 1. Fetch daily activities 2. Fetch daily activity summary (active minutes) 3. Respond: "Yes! You logged a CrossFit session this morning (45 min, 312 calories). Plus 28 very active minutes total for the day." ## Data Insights to Look For - **Trends:** Week-over-week changes, consistency patterns - **Goals:** Compare to 10k steps, exercise frequency, sleep targets - **Correlations:** Sleep quality vs activity, rest days vs performance - **Anomalies:** Unusual spikes or drops - **Achievements:** Personal bests, streaks, milestones ## Token Management The skill automatically loads tokens from `/root/clawd/fitbit-config.json` and refreshes them when expired (every 8 hours). **Auto-refresh:** Tokens are refreshed automatically - no manual intervention needed! **Manual refresh (if needed):** ```bash python3 scripts/refresh_token.py force ``` **Override with environment variable:** ```bash export FITBIT_ACCESS_TOKEN="manual_token" ``` ## Error Handling - **Missing token:** Prompt user to set FITBIT_ACCESS_TOKEN - **API errors:** Check token validity, may need refresh - **No data:** Some days may have no logged activities or missing metrics See `references/fitbit-oauth-setup.md` for token management.

path: CLAWHUB-SUBMISSION.md
content: # Fitbit Fitness Insights - ClawHub Submission

## Basic Info

**Skill Name:** Fitbit Fitness Insights  
**Category:** Health & Fitness / Productivity  
**Version:** 1.0.0  
**Author:** Ryan Burns (@poisondminds)  
**License:** MIT

## Short Description (1 line)

AI-powered Fitbit insights with natural language Q&A - ask about your fitness, get intelligent answers.

## Long Description

Fitbit Fitness Insights brings AI-powered analysis to your fitness data. Instead of checking graphs and numbers in the Fitbit app, simply ask questions and get conversational insights.

**Key Features:**
- 🤖 Natural language Q&A - "How did I sleep?" "Did I hit my goals?"
- 📊 Activity insights - Steps, calories, active minutes, distance
- 💓 Heart rate analysis - Resting HR, zones, workout intensity
- 😴 Sleep tracking - Duration, efficiency, wake-ups, sleep stages
- 🏃 Workout analysis - Logged activities, duration, calories
- 📈 Trend detection - Week-over-week, patterns, achievements

**How It Works:**
1. Ask your AI assistant fitness questions
2. Skill fetches data from Fitbit API
3. AI analyzes and generates insights
4. Get conversational answers, not just numbers

**Example Conversations:**

*"How did I sleep last night?"*
→ "You slept 7.9 hours with 96% efficiency. Only woke up twice for 2 minutes total. That's excellent sleep quality! 😴"

*"How active was I this week?"*
→ "You averaged 8,234 steps/day (up 12% from last week!). Hit your 10k goal 4/7 days. CrossFit 3x with 156 very active minutes. Solid week! 💪"

**Perfect for:**
- Fitness enthusiasts who want deeper insights
- People tracking health goals
- Anyone tired of checking the Fitbit app constantly
- Those who prefer conversational data over charts

## Screenshots/Demo

(Text example conversation - see Long Description above)

## Requirements

**Platform:**
- Clawdbot with messaging integration

**Dependencies:**
- Fitbit account with syncing device
- Fitbit OAuth credentials (free developer account)
- Python 3 (standard library only)

**Setup Time:** ~5 minutes (one-time OAuth setup)

## Installation Instructions

1. **Install skill:**
   ```bash
   clawdbot skills install fitbit.skill
   ```

2. **Set up Fitbit OAuth:**
   - Register app at https://dev.fitbit.com/apps (2 minutes)
   - Get OAuth tokens
   - Configure `fitbit-config.json`

3. **Start asking:**
   - "How did I do this week?"
   - "Did I exercise today?"
   - "What was my sleep like?"

Full setup guide included in download (SETUP.md).

## Tags/Keywords

fitbit, fitness, health, sleep, activity, heart-rate, workouts, ai-insights, oauth, wellness, tracking, goals, natural-language, qa, conversational

## Technical Details

**Data Accessed:**
- Activity (steps, distance, calories, active minutes)
- Heart rate (resting, zones)
- Sleep (duration, efficiency, stages)
- Workouts (logged activities)

**Security:**
- OAuth 2.0 authentication
- Read-only access
- Auto-refreshing tokens
- No data storage/caching
- Queries on-demand only

**Performance:**
- Real-time data fetching
- 1-2 second response time
- 150 requests/hour limit (Fitbit API)

## Support

**Documentation:** Included in skill package  
**Issues:** https://github.com/poisondminds/clawdbot-fitbit-insights  
**Community:** https://discord.com/invite/clawd  

## File

**Filename:** fitbit.skill  
**Size:** 9.6 KB  
**Format:** .skill (Clawdbot skill package)

## Why This Skill?

The Fitbit app shows data, but no AI analysis. This skill:
- Answers questions conversationally
- Identifies trends you'd miss
- Compares week-over-week automatically  
- Provides motivation via insights
- No app checking needed - just ask!

**Result:** Smarter fitness tracking with AI-powered insights! 🏋️✨

---

## Submission Checklist

- [x] Skill file ready (fitbit.skill)
- [x] Description complete
- [x] Demo conversation provided
- [x] Installation instructions clear
- [x] Dependencies listed
- [x] Support links included
- [x] Tags/keywords added
- [x] No sensitive data in package
- [x] Tested and working

**Status:** Ready to submit! ✅


path: OVERVIEW.md
content: # Fitbit Fitness Insights - Overview

## Technical Details

**Version:** 1.0.0  
**Category:** Health & Fitness / Productivity  
**Platform:** Clawdbot  
**API:** Fitbit Web API v1

## Architecture

- **fitbit_api.py** - REST API client with OAuth 2.0
- **refresh_token.py** - Automatic token refresh system
- **fitbit-config.json** - Credential storage (local only, not in skill)

## Features

- Natural language fitness Q&A
- Real-time data fetching from Fitbit
- Auto-refreshing OAuth tokens (8-hour cycle)
- AI-powered insight generation
- Conversational responses

## Data Sources

- Activity metrics (steps, distance, calories, active minutes)
- Heart rate data (resting HR, zones)
- Sleep tracking (duration, efficiency, stages)
- Workout logs (activities, duration, calories)
- Historical trends and comparisons

## Authentication Flow

1. User registers Fitbit OAuth app (one-time)
2. User authorizes app and gets tokens
3. Tokens stored in local config file
4. Access token auto-refreshes every 8 hours
5. No re-authentication needed

## Security

- OAuth 2.0 secure authentication
- Tokens stored locally (never in skill package)
- Read-only API access
- No data stored or cached
- On-demand queries only

## Performance

- API calls: ~1-2 seconds per query
- Token refresh: Automatic, transparent
- Rate limit: 150 requests/hour (Fitbit limit)
- Caching: None (real-time data)

## Dependencies

- Python 3 (standard library only)
- Fitbit account with syncing device
- OAuth credentials (free developer account)

## Use Cases

- Daily fitness check-ins
- Goal tracking and progress
- Sleep quality analysis
- Workout effectiveness
- Trend identification
- Motivation via achievements

## Skill Trigger

Triggers when user asks fitness-related questions:
- "How did I sleep?"
- "Did I exercise today?"
- "Show me my weekly stats"
- "Am I hitting my goals?"

## AI Insight Generation

The skill fetches raw data, then AI analyzes and generates:
- Conversational summaries
- Trend identification
- Week-over-week comparisons
- Pattern recognition
- Goal achievement tracking
- Motivational feedback

## Installation

1. Install skill package
2. Set up Fitbit OAuth (5 minutes)
3. Configure credential file
4. Start asking questions

## Future Enhancements

Potential additions:
- Weight tracking
- Water intake
- Food logging
- Historical comparisons
- Goal setting
- Achievements/badges

---

**Status:** Production ready  
**Tested:** ✅ All features working  
**Documentation:** Complete


path: README.md
content: # Fitbit Fitness Insights - Clawdbot Skill

🏋️ AI-powered insights from your Fitbit data!

## What It Does

Ask your AI assistant questions about your fitness data and get intelligent insights:

- 📊 **Activity insights** - "How did I do this week?"
- 💓 **Heart rate analysis** - "What was my heart rate during workouts?"
- 😴 **Sleep tracking** - "How did I sleep last night?"
- 🏃 **Workout analysis** - "Did I exercise today?"
- 📈 **Trend analysis** - "Am I more active on weekdays or weekends?"
- 🎯 **Goal tracking** - "Did I hit my step goal this week?"

## Example Conversations

**You:** "How did I sleep last night?"

**AI:** "You slept 7.9 hours with 96% efficiency. Only woke up twice for 2 minutes total. That's excellent sleep quality! 😴"

---

**You:** "How active was I this week?"

**AI:** "You averaged 8,234 steps/day this week (up 12% from last week!). Hit your 10k goal 4 out of 7 days. You logged CrossFit 3 times with 156 very active minutes total. Solid week! 💪"

## Features

- **Natural language Q&A** - Ask questions naturally, get conversational answers
- **AI-powered insights** - Smart analysis, not just raw numbers
- **Trend detection** - Spots patterns, week-over-week changes
- **No app needed** - Works via Fitbit API directly
- **Privacy-focused** - Read-only access, your data stays private

## Installation

1. **Install the skill:**
   ```bash
   clawdbot skills install fitbit.skill
   ```

2. **Set up Fitbit OAuth** (takes 5 minutes):
   - Register app at https://dev.fitbit.com/apps
   - Get OAuth tokens
   - Configure `fitbit-config.json`

3. **Start asking questions!**
   - "How did I do this week?"
   - "Did I exercise today?"
   - "What was my sleep like?"

Full setup guide included in the skill package.

## What Data You Can Query

- **Activity:** Steps, distance, calories, active minutes, floors
- **Heart Rate:** Resting HR, heart rate zones, workout intensity
- **Sleep:** Duration, efficiency, wake-ups, sleep stages
- **Workouts:** Logged activities, duration, calories burned
- **Trends:** Week-over-week comparisons, patterns, achievements

## Requirements

- Fitbit account with data syncing
- Fitbit OAuth credentials (free developer account)
- Clawdbot with Telegram or other messaging platform
- Python 3 (included with Clawdbot)

## Security & Privacy

- ✅ **Read-only access** - Never writes to your Fitbit account
- ✅ **OAuth 2.0** - Secure token-based authentication
- ✅ **Auto-refresh** - Tokens refresh automatically
- ✅ **No data storage** - Queries on-demand, nothing saved
- ✅ **Your data** - Stays in your Fitbit account, never shared

## Setup Time

- **5 minutes** for OAuth setup (one-time)
- **Auto-refresh** - Tokens managed automatically
- **Zero maintenance** - Just ask questions!

## Use Cases

- Track fitness goals and progress
- Analyze workout effectiveness
- Monitor sleep quality
- Compare activity patterns
- Spot correlations (sleep vs performance)
- Get motivated by achievements

## Technical Details

- **Fitbit Web API integration**
- **OAuth 2.0 with auto-refresh**
- **Python 3** (standard library only, no pip packages)
- **Config-based** token management
- **AI-powered** insight generation

## What's Included

- `fitbit.skill` - Complete skill package
- `README.md` - This file
- `SETUP.md` - Step-by-step OAuth setup guide
- Inside skill:
  - SKILL.md - Full documentation
  - fitbit_api.py - API client
  - refresh_token.py - Auto-refresh system
  - fitbit-oauth-setup.md - OAuth guide

## Support

- **Issues:** https://github.com/clawdbot/clawdbot/issues
- **Community:** https://discord.com/invite/clawd
- **Docs:** https://docs.clawd.bot
- **Fitbit API:** https://dev.fitbit.com/build/reference/web-api/

---

**Ready to get AI-powered fitness insights?** 🏋️✨

Download `fitbit.skill` and start asking questions about your fitness data!

---

*Made with ❤️ for Fitbit users who want smarter fitness tracking*


path: SETUP.md
content: # Fitbit Skill - Setup Guide

## Quick Setup (5 minutes)

### 1. Register Fitbit App

1. Go to https://dev.fitbit.com/apps
2. Click **"Register an App"**
3. Fill in:
   - **App Name:** "Personal Fitness Assistant" (or whatever you like)
   - **Description:** "AI assistant for fitness data"
   - **Website:** `http://localhost`
   - **OAuth 2.0 Application Type:** **Personal**
   - **Callback URL:** `http://localhost`
   - **Default Access Type:** **Read-Only**
4. Agree to terms and submit
5. Note your **Client ID** and **Client Secret**

### 2. Get OAuth Tokens

**Option A: OAuth Tutorial (Easiest)**

1. On your app page, scroll to **"OAuth 2.0 tutorial page"**
2. Click the link to "access your own data"
3. Authorize the app
4. Copy the **Access Token** and **Refresh Token**

**Option B: Manual OAuth Flow**

1. Visit authorization URL (replace YOUR_CLIENT_ID):
   ```
   https://www.fitbit.com/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost&scope=activity%20heartrate%20sleep%20profile
   ```

2. Authorize and copy the `code` from the redirect URL

3. Exchange code for tokens:
   ```bash
   curl -X POST https://api.fitbit.com/oauth2/token \
     -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=YOUR_CLIENT_ID&grant_type=authorization_code&redirect_uri=http://localhost&code=YOUR_CODE"
   ```

4. Copy `access_token` and `refresh_token` from response

### 3. Configure Skill

Create `fitbit-config.json` in your Clawdbot workspace:

```json
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "access_token": "YOUR_ACCESS_TOKEN",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "expires_at": 0,
  "last_refreshed": ""
}
```

**Location:** `/root/clawd/fitbit-config.json` (or wherever your Clawdbot workspace is)

### 4. Install Skill

```bash
clawdbot skills install fitbit.skill
```

### 5. Test It!

Ask your AI assistant:
- "How did I do this week?"
- "Did I exercise today?"
- "What was my sleep like last night?"

## Token Management

**Auto-Refresh:** Tokens automatically refresh every 8 hours - no manual intervention needed!

**Manual Refresh (if needed):**
```bash
cd /root/clawd/fitbit
python3 scripts/refresh_token.py force
```

**Check Token Status:**
```bash
python3 scripts/refresh_token.py
```

## Scopes Required

The skill needs these Fitbit API scopes:
- `activity` - Steps, distance, calories, active minutes
- `heartrate` - Heart rate data and zones
- `sleep` - Sleep duration and stages  
- `profile` - Basic profile info

All included in the authorization URL above.

## Security Notes

- ✅ **Never commit config to git** - Add `fitbit-config.json` to `.gitignore`
- ✅ **Refresh tokens don't expire** - Keep them secure
- ✅ **Access tokens expire in 8 hours** - Auto-refreshed by skill
- ✅ **Read-only access** - Skill never writes to Fitbit

## Troubleshooting

**"Config file not found"**
- Make sure `fitbit-config.json` is in `/root/clawd/` (or your workspace root)

**"401 Unauthorized"**
- Token expired - run `python3 scripts/refresh_token.py force`
- Or re-authorize and get new tokens

**"Too Many Requests"**
- Fitbit has rate limits (150 requests/hour per user)
- Skill is optimized to minimize API calls

**"Invalid client credentials"**
- Check Client ID and Client Secret are correct in config

## File Locations

- **Config:** `/root/clawd/fitbit-config.json`
- **Skill:** `/root/nodejs/lib/node_modules/clawdbot/skills/fitbit/`
- **Scripts:** Inside skill folder under `scripts/`

## Next Steps

Once configured, just start asking fitness questions! The AI will:
1. Fetch relevant data from Fitbit
2. Analyze trends and patterns
3. Provide conversational insights

No need to check the app - just ask! 🏋️✨

## Support

- Full OAuth guide: See `references/fitbit-oauth-setup.md` in skill package
- Fitbit API docs: https://dev.fitbit.com/build/reference/web-api/
- Clawdbot community: https://discord.com/invite/clawd


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (HIGH)