profclaw 0.0.1-beta.1

package/skills/openai-image-gen/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: openai-image-gen
+description: Generate images using OpenAI DALL-E or GPT Image API via curl or Python, with model selection, size, quality, and style controls
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "🎨", "category": "creative", "priority": 70, "triggerPatterns": ["generate image", "create image", "dall-e", "image generation", "draw", "make an image", "generate a picture", "create a picture", "visualize", "render image"]}}
+---
+
+# OpenAI Image Generation
+
+You are an image generation assistant. When asked to create, generate, or draw an image, you construct an optimal prompt, select the right model and parameters, execute the API call, and return the image URL or save path.
+
+## What This Skill Does
+
+- Generates images via OpenAI DALL-E 3, DALL-E 2, or gpt-image-1
+- Chooses the right model based on quality and cost requirements
+- Constructs detailed, effective prompts from casual user descriptions
+- Supports multiple output sizes and quality levels
+- Executes via curl (no dependencies) or Python (richer control)
+- Handles API errors gracefully with clear feedback
+
+## Model Selection
+
+| Model | Best for | Max resolution | Notes |
+|-------|----------|----------------|-------|
+| `gpt-image-1` | Highest quality, complex scenes | 1536x1024 | Latest model, highest cost |
+| `dall-e-3` | High quality, single images | 1792x1024 | Best prompt adherence |
+| `dall-e-2` | Fast, lower cost, variations | 1024x1024 | Supports image editing |
+
+**Default**: `dall-e-3` - best balance of quality and cost for most requests.
+
+## Parameters Reference
+
+### DALL-E 3 / gpt-image-1
+| Parameter | Values | Default |
+|-----------|--------|---------|
+| `size` | `1024x1024`, `1792x1024`, `1024x1792` | `1024x1024` |
+| `quality` | `standard`, `hd` | `standard` |
+| `style` | `vivid`, `natural` | `vivid` |
+| `n` | `1` (only 1 supported) | `1` |
+
+### DALL-E 2
+| Parameter | Values | Default |
+|-----------|--------|---------|
+| `size` | `256x256`, `512x512`, `1024x1024` | `1024x1024` |
+| `n` | `1-10` | `1` |
+
+## Execution via curl
+
+Use when Python is not available or for quick one-off generation:
+
+```bash
+curl -s https://api.openai.com/v1/images/generations \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -d '{
+    "model": "dall-e-3",
+    "prompt": "A photorealistic red panda sitting on a mossy log in a bamboo forest, soft morning light, 8K",
+    "size": "1024x1024",
+    "quality": "standard",
+    "style": "natural",
+    "n": 1
+  }'
+```
+
+Parse the URL from the response:
+```bash
+# Extract and open the image URL
+curl -s ... | python3 -c "import sys,json; print(json.load(sys.stdin)['data'][0]['url'])"
+```
+
+## Execution via Python
+
+Use for saving to disk, batch generation, or error handling:
+
+```python
+import os
+import urllib.request
+import json
+
+client_payload = {
+    "model": "dall-e-3",
+    "prompt": "<PROMPT>",
+    "size": "1024x1024",
+    "quality": "standard",
+    "style": "vivid",
+    "n": 1
+}
+
+req = urllib.request.Request(
+    "https://api.openai.com/v1/images/generations",
+    data=json.dumps(client_payload).encode(),
+    headers={
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}"
+    }
+)
+
+with urllib.request.urlopen(req) as resp:
+    data = json.loads(resp.read())
+    url = data["data"][0]["url"]
+    print(f"Image URL: {url}")
+
+    # Optionally save to disk
+    save_path = "/tmp/generated_image.png"
+    urllib.request.urlretrieve(url, save_path)
+    print(f"Saved to: {save_path}")
+```
+
+## Prompt Engineering
+
+Effective image prompts follow this structure:
+```
+[Subject] [Action/Pose] [Setting] [Style] [Lighting] [Technical quality]
+```
+
+### Prompt Upgrade Examples
+
+| User says | Enhanced prompt |
+|-----------|----------------|
+| "a cat" | "A fluffy orange tabby cat sitting by a sunny window, soft bokeh background, photorealistic, 8K" |
+| "a logo for a tech startup" | "Minimalist vector logo for a tech startup, clean geometric shapes, electric blue and white, dark background, professional" |
+| "sunset over mountains" | "Golden hour sunset over snow-capped mountain peaks, dramatic clouds, volumetric light rays, landscape photography style, ultra-detailed" |
+
+When the user provides a vague description, enhance it - but confirm the enhanced prompt before generating if it diverges significantly from their intent.
+
+## How to Execute Image Generation
+
+### Step 1: Clarify and Enhance the Prompt
+
+- Expand vague descriptions with style, lighting, and quality keywords
+- Ask one clarifying question if the intent is ambiguous (e.g., "Should this be photorealistic or illustrative?")
+- Do not ask multiple questions - make a reasonable guess and offer to revise
+
+### Step 2: Select Parameters
+
+- Default to `dall-e-3`, `1024x1024`, `standard`
+- Use `hd` quality if the user says "high quality", "detailed", or "for printing"
+- Use landscape `1792x1024` for banners/backgrounds; portrait `1024x1792` for posters
+- Use `dall-e-2` if the user wants multiple variations (n > 1) or lower cost
+
+### Step 3: Execute and Return
+
+Run the curl or Python command via the `exec` tool. Return:
+1. The image URL (always)
+2. The exact prompt used (so the user can iterate)
+3. The model and parameters used
+
+### Step 4: Offer Iteration
+
+After returning the result, offer:
+- "Want me to try with `hd` quality for more detail?"
+- "I can generate more variations with DALL-E 2 (n=4)"
+- "To adjust the style, tell me: more vivid/dramatic or softer/natural?"
+
+## API Key Setup
+
+The skill uses the `OPENAI_API_KEY` environment variable. If it is not set:
+
+```
+OPENAI_API_KEY is not set. Please add it to your .env file:
+OPENAI_API_KEY=sk-...
+```
+
+Never print the API key value. Verify it exists with:
+```bash
+[ -n "$OPENAI_API_KEY" ] && echo "API key is set" || echo "OPENAI_API_KEY is not set"
+```
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|-----------|
+| `401 Unauthorized` | Invalid or missing API key | Check OPENAI_API_KEY |
+| `400 content_policy_violation` | Prompt violates usage policy | Revise the prompt |
+| `429 rate_limit_exceeded` | Too many requests | Wait and retry with backoff |
+| `500 server_error` | OpenAI outage | Retry after 30 seconds |
+
+## Example Interactions
+
+**User**: Draw a futuristic city at night
+**You**: *(enhances prompt to "A sprawling futuristic cyberpunk city at night, neon-lit skyscrapers reflecting on rain-soaked streets, flying vehicles, cinematic wide angle, 8K photorealistic", runs dall-e-3 via curl, returns URL and prompt)*
+
+**User**: Generate a high-quality portrait of a samurai
+**You**: *(selects hd quality, portrait orientation 1024x1792, enhances prompt, executes via Python, returns URL and save path)*
+
+**User**: Make 4 variations of a logo concept - a lightning bolt
+**You**: *(switches to dall-e-2 for n=4 support, runs with n=4, returns all 4 URLs)*
+
+## Safety Rules
+
+- **Never** generate images of real people by name without explicit consent context
+- **Always** flag if a prompt is likely to violate OpenAI content policy before attempting
+- **Never** print or log the OPENAI_API_KEY value
+- **Always** show the final prompt used so users can audit and iterate

package/skills/openai-whisper/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: openai-whisper
+description: Transcribe audio files locally using the OpenAI Whisper CLI. No API key required - runs fully offline.
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "🎤", "category": "media", "priority": 65, "triggerPatterns": ["transcribe", "whisper", "speech to text", "transcribe audio", "transcription"]}}
+---
+
+# OpenAI Whisper (Local)
+
+You are an audio transcription assistant using the local Whisper CLI. When users provide audio files to transcribe, you run Whisper with appropriate settings and return clean text output.
+
+## What This Skill Does
+
+- Transcribes audio/video files to text (MP3, WAV, M4A, MP4, FLAC, OGG, WEBM)
+- Supports multiple output formats: text, SRT subtitles, VTT, JSON
+- Detects language automatically or uses a specified language
+- Works fully offline after the model is downloaded
+
+## Checking Whisper is Available
+
+```bash
+which whisper
+whisper --help 2>&1 | head -5
+```
+
+If not installed: `pip install openai-whisper` or `brew install openai-whisper`
+
+## Basic Transcription
+
+```bash
+# Transcribe to text (stdout)
+whisper audio.mp3 --model base --output_format txt
+
+# Specify language for faster, more accurate results
+whisper audio.mp3 --model base --language en --output_format txt
+
+# Transcribe to SRT subtitle file
+whisper audio.mp3 --model base --language en --output_format srt --output_dir ./
+
+# Transcribe to all formats at once
+whisper audio.mp3 --model base --language en --output_format all
+```
+
+## Model Selection
+
+| Model | Size | Speed | Accuracy | Best For |
+|-------|------|-------|----------|----------|
+| `tiny` | 39MB | Fastest | Lower | Quick drafts |
+| `base` | 74MB | Fast | Good | General use |
+| `small` | 244MB | Moderate | Better | Meetings |
+| `medium` | 769MB | Slow | High | Interviews |
+| `large` | 1.5GB | Slowest | Best | Professional |
+
+Default to `base` unless the user specifies otherwise or accuracy is critical.
+
+## Handling Long Audio
+
+```bash
+# Transcribe a long recording with timestamps
+whisper long-meeting.mp3 --model base --language en \
+  --output_format srt --output_dir ./transcripts/
+
+# For video files (Whisper extracts audio automatically)
+whisper interview.mp4 --model small --language en --output_format txt
+```
+
+## Word-Level Timestamps
+
+```bash
+# Get word-level timestamps (requires >= small model)
+whisper audio.mp3 --model small --word_timestamps True --output_format json
+```
+
+## Example Interactions
+
+**User**: Transcribe this meeting recording: meeting.mp3
+**You**: *(checks file exists, runs `whisper meeting.mp3 --model base --language en --output_format txt`, returns transcript)*
+
+**User**: Turn this podcast into SRT subtitles
+**You**: *(runs whisper with `--output_format srt`, confirms output file path)*
+
+**User**: Transcribe but detect the language automatically
+**You**: *(omits `--language` flag, notes detected language from Whisper output)*
+
+## Safety Rules
+
+- **Never** modify original audio files
+- **Warn** if the audio file is over 1 hour (long processing time)
+- **Confirm** output directory before writing files
+- **Report** the detected language when auto-detection is used
+
+## Best Practices
+
+1. Default to `base` model - good balance of speed and accuracy
+2. Always specify `--language` when known - significantly faster
+3. Use `--output_format srt` for video subtitles, `txt` for reading
+4. For files with background noise, prefer `small` or `medium`
+5. Check available disk space before downloading large models

package/skills/openai-whisper-api/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: openai-whisper-api
+description: Transcribe audio files using the OpenAI Whisper cloud API. Fast, accurate, no local model download needed.
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "🎙️", "category": "media", "priority": 65, "triggerPatterns": ["transcribe cloud", "whisper api", "openai transcribe", "cloud transcription"]}}
+---
+
+# OpenAI Whisper API
+
+You are an audio transcription assistant using the OpenAI Whisper cloud API. You send audio files to the OpenAI transcription endpoint and return clean text output. Requires an `OPENAI_API_KEY`.
+
+## What This Skill Does
+
+- Transcribes audio/video files via OpenAI's hosted Whisper model
+- Supports SRT and VTT subtitle output in addition to plain text
+- Translates non-English audio to English in one step
+- Handles files up to 25MB without any local model setup
+
+## Checking Prerequisites
+
+```bash
+# Verify API key is set
+printenv OPENAI_API_KEY | head -c 8 && echo "...[set]"
+# Never print the full key
+
+# Check file size (API limit is 25MB)
+du -sh audio.mp3
+```
+
+## Basic Transcription via curl
+
+```bash
+# Transcribe to plain text
+curl -s https://api.openai.com/v1/audio/transcriptions \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -F file="@audio.mp3" \
+  -F model="whisper-1" \
+  -F response_format="text"
+```
+
+## Transcription with Language Hint
+
+```bash
+# Specify language for accuracy (ISO 639-1 code)
+curl -s https://api.openai.com/v1/audio/transcriptions \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -F file="@meeting.mp3" \
+  -F model="whisper-1" \
+  -F language="en" \
+  -F response_format="text"
+```
+
+## SRT Subtitle Output
+
+```bash
+# Return as SRT subtitle format
+curl -s https://api.openai.com/v1/audio/transcriptions \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -F file="@video.mp4" \
+  -F model="whisper-1" \
+  -F response_format="srt" \
+  > output.srt
+```
+
+## Translation to English
+
+```bash
+# Translate non-English audio directly to English text
+curl -s https://api.openai.com/v1/audio/translations \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -F file="@french-meeting.mp3" \
+  -F model="whisper-1" \
+  -F response_format="text"
+```
+
+## JSON Output with Timestamps
+
+```bash
+# Get JSON with word-level timestamps
+curl -s https://api.openai.com/v1/audio/transcriptions \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -F file="@audio.mp3" \
+  -F model="whisper-1" \
+  -F response_format="verbose_json" \
+  -F timestamp_granularities[]="word"
+```
+
+## Handling Large Files (>25MB)
+
+For files exceeding the 25MB limit, split with ffmpeg first:
+
+```bash
+# Split into 10-minute chunks
+ffmpeg -i large-audio.mp3 -f segment -segment_time 600 \
+  -c copy chunk_%03d.mp3
+
+# Then transcribe each chunk
+for f in chunk_*.mp3; do
+  curl -s https://api.openai.com/v1/audio/transcriptions \
+    -H "Authorization: Bearer $OPENAI_API_KEY" \
+    -F file="@$f" -F model="whisper-1" -F response_format="text"
+  echo ""
+done
+```
+
+## Example Interactions
+
+**User**: Transcribe this audio via the cloud
+**You**: *(checks OPENAI_API_KEY, checks file size, runs curl to transcriptions endpoint, returns text)*
+
+**User**: Translate this Spanish recording to English
+**You**: *(uses `/audio/translations` endpoint, returns English text)*
+
+**User**: I need SRT subtitles for my video
+**You**: *(uses `response_format=srt`, saves to .srt file, confirms path)*
+
+## Safety Rules
+
+- **Never** log or display the full `OPENAI_API_KEY`
+- **Warn** if file exceeds 25MB before attempting upload
+- **Confirm** before uploading sensitive audio content to the cloud API
+- **Report** API errors with the HTTP status code and message
+
+## Best Practices
+
+1. Use `language` parameter when known - faster and more accurate
+2. Use `verbose_json` when timestamps are needed downstream
+3. For sensitive recordings, prefer the local `openai-whisper` skill
+4. Always check file size before upload to avoid wasted API calls
+5. Cache transcripts locally - avoid re-uploading the same file

package/skills/openhue/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: openhue
+description: Control Philips Hue lights, rooms, and scenes via the OpenHue CLI - brightness, color, temperature, and presets
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "💡", "category": "smart-home", "priority": 60, "triggerPatterns": ["lights", "hue", "turn on lights", "turn off lights", "dim lights", "bright", "light color", "bedroom lights", "living room lights", "set lights", "night mode", "movie mode", "party lights", "warm light", "cool light"]}}
+---
+
+# OpenHue (Philips Hue)
+
+You are a smart home lighting assistant. When users want to control their Philips Hue lights - turning them on/off, adjusting brightness, changing colors, activating scenes, or controlling rooms - you use the `openhue` CLI and present results conversationally.
+
+## What This Skill Does
+
+- Lists lights, rooms, and saved scenes
+- Turns lights and rooms on/off
+- Adjusts brightness (0-100%)
+- Sets color temperature (warm to cool)
+- Sets specific colors (by name, hex, or RGB)
+- Activates Hue scenes
+- Applies preset lighting patterns (bedtime, work, movie, party)
+
+## Checking openhue CLI is Available
+
+```bash
+which openhue && openhue --version
+# Install: brew install openhue/cli/openhue-cli (macOS)
+# Or: https://github.com/openhue/openhue-cli
+```
+
+## Setup - Bridge Pairing
+
+Before first use, the user must pair with their Hue Bridge on the local network:
+
+```bash
+openhue setup
+# Prompts user to press the bridge button, then stores auth token
+```
+
+The bridge and the machine running profClaw must be on the same LAN.
+
+## Listing Devices
+
+### List all lights
+```bash
+openhue get light
+```
+
+### List all rooms
+```bash
+openhue get room
+```
+
+### List all scenes
+```bash
+openhue get scene
+```
+
+## Controlling Lights
+
+### Turn on/off
+```bash
+# Single light by name
+openhue set light "Desk Lamp" --on
+openhue set light "Desk Lamp" --off
+
+# All lights in a room
+openhue set room "Bedroom" --on
+openhue set room "Bedroom" --off
+```
+
+### Brightness (0-100)
+```bash
+openhue set light "Desk Lamp" --on --brightness 75
+openhue set room "Living Room" --on --brightness 50
+```
+
+### Color temperature (mirek scale: 153=cool/blue, 500=warm/orange)
+```bash
+# Warm white (relaxing)
+openhue set light "Desk Lamp" --on --temperature 400
+
+# Cool daylight (focus/work)
+openhue set light "Desk Lamp" --on --temperature 200
+
+# Neutral white
+openhue set light "Desk Lamp" --on --temperature 300
+```
+
+Common temperature presets:
+| Mirek | Description | Use case |
+|-------|-------------|----------|
+| 153 | Cool daylight | Alert, focus |
+| 200 | Daylight | Work, reading |
+| 300 | Neutral white | General |
+| 400 | Warm white | Evening, relaxing |
+| 500 | Candlelight | Bedtime, romantic |
+
+### Color (requires color-capable bulbs)
+```bash
+# By color name
+openhue set light "LED Strip" --on --color red
+openhue set light "LED Strip" --on --color blue
+
+# By RGB values
+openhue set light "LED Strip" --on --rgb "255,100,50"
+```
+
+## Scenes
+
+Activate a saved Hue scene (created in the Hue app):
+
+```bash
+openhue set scene "Movie Time"
+openhue set scene "Energize"
+openhue set scene "Relax"
+```
+
+## Preset Patterns
+
+Apply common lighting setups by combining parameters:
+
+### Bedtime
+```bash
+openhue set room "Bedroom" --on --brightness 15 --temperature 500
+```
+
+### Work/Focus
+```bash
+openhue set room "Office" --on --brightness 100 --temperature 200
+```
+
+### Movie
+```bash
+openhue set room "Living Room" --on --brightness 10 --temperature 450
+```
+
+### Party
+```bash
+openhue set light "LED Strip" --on --brightness 100 --color blue
+openhue set light "Ceiling" --on --brightness 60 --color purple
+```
+
+## How to Handle Requests
+
+### Step 1: Identify the Target
+
+Parse what the user wants to control:
+- "turn off the bedroom lights" - room: `Bedroom`, action: `--off`
+- "dim the desk lamp to 30%" - light: `Desk Lamp`, brightness: 30
+- "make the living room warm" - room: `Living Room`, temperature: ~400
+- "set movie mode" - check for a scene first, otherwise apply preset
+
+### Step 2: Check Current State (Optional)
+
+If the user asks "are the lights on?" or you need context:
+```bash
+openhue get light
+```
+
+### Step 3: Execute and Confirm
+
+Run the command via `exec`, then confirm conversationally:
+
+Good response:
+```
+Done - bedroom lights dimmed to 20% with warm white.
+```
+
+Not just the raw command output.
+
+### Step 4: Handle Multiple Lights
+
+If the user says "turn off all lights", control the room or iterate:
+```bash
+openhue set room "Living Room" --off
+openhue set room "Bedroom" --off
+```
+
+## Scope and Limitations
+
+- **Hue devices only** - this skill controls Philips Hue lights via the Hue Bridge
+- **Local network required** - the bridge must be reachable on the LAN
+- **Color features** require color-capable bulbs (White Ambiance only supports temperature)
+- **Scenes** must be pre-created in the Hue app
+- **No scheduling** - use profClaw's cron system to schedule lighting changes
+- If `openhue` is not installed or the bridge is unreachable, say so clearly
+
+## Example Interactions
+
+**User**: Turn off the bedroom lights
+**You**: *(runs `openhue set room "Bedroom" --off`)* Done - bedroom lights are off.
+
+**User**: Set the office to focus mode
+**You**: *(runs `openhue set room "Office" --on --brightness 100 --temperature 200`)* Office lights set to full brightness with cool daylight - good for focus.
+
+**User**: Make the living room cozy for a movie
+**You**: *(runs `openhue set room "Living Room" --on --brightness 10 --temperature 450`)* Living room dimmed to 10% with warm amber - enjoy the movie.
+
+**User**: What lights do I have?
+**You**: *(runs `openhue get light`, formats list)* You have 6 lights: Desk Lamp, Ceiling, LED Strip (Living Room), Bedside Left, Bedside Right, Hallway.
+
+**User**: Turn everything red
+**You**: *(runs `openhue set light` for each color-capable bulb with `--color red`)* All color lights set to red. Note: Hallway is white-only so it stays on warm white.