Skill: drandrewlaw/trio-vision (version 1.0.0)

--- name: trio-vision description: Turn any live camera into a smart camera — describe what to watch for in plain English, get alerts in your chat when it happens. Ask questions about any live stream (YouTube, Twitch, security cameras, RTSP), set up continuous monitoring with custom conditions, or get periodic summaries of what's happening. No ML expertise required. homepage: https://docs.machinefi.com license: Apache-2.0 metadata: {"openclaw":{"emoji":"📹","requires":{"env":["TRIO_API_KEY"],"anyBins":["curl","python3"]},"primaryEnv":"TRIO_API_KEY"}} --- # Trio Vision — Turn Any Camera Into a Smart Camera Stop getting dumb motion alerts for every shadow. Describe what actually matters in plain English — get notified only when it happens, right in your chat. Powered by [Trio by MachineFi](https://machinefi.com). ## When to Use - User asks what's happening on a camera, stream, or video feed ("is anyone at my front door?") - User wants smart alerts for specific events ("tell me when a package is delivered", "alert me if my dog gets on the couch") - User wants to monitor something they can't watch themselves (construction site, parking spot, warehouse) - User wants periodic summaries of a live feed ("summarize this stream every 10 minutes") - User provides any live stream URL: YouTube Live, Twitch, RTSP/RTSPS cameras, HLS streams ## Prerequisites - A Trio API key. Get one free (100 credits) at https://console.machinefi.com - Set the key: `export TRIO_API_KEY=your_key_here` - Base URL: `https://trio.machinefi.com/api` ## Available Actions ### 1. Check Once (Quick Snapshot) Ask a yes/no question about what's currently visible on a stream. Costs 1 credit ($0.01). ```bash curl -s -X POST "https://trio.machinefi.com/api/check-once" \ -H "Authorization: Bearer $TRIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "stream_url": "STREAM_URL_HERE", "condition": "NATURAL_LANGUAGE_CONDITION_HERE" }' | python3 -m json.tool ``` **Optional parameters:** - `"include_frame": true` — returns the analyzed frame as base64 image - `"input_mode": "clip"` — analyze a short video clip instead of a single frame (better for motion detection) - `"clip_duration_seconds": 5` — clip length (1-10 seconds, only with clip/hybrid mode) **Response fields:** - `triggered` (boolean) — whether the condition matched - `explanation` (string) — VLM's reasoning about what it sees - `latency_ms` — processing time in milliseconds **Input mode guidance:** - Use `"frames"` (default) for static objects: "Is there a car in the driveway?", "Is the door open?" - Use `"clip"` for motion/actions: "Is someone walking?", "Did a package get delivered?" - Use `"hybrid"` for maximum accuracy (costs more) ### 2. Live Monitor (Continuous Event Detection) Monitor a stream continuously and get alerted when a condition becomes true. Costs 2 credits/min ($0.02/min). ```bash curl -s -X POST "https://trio.machinefi.com/api/live-monitor" \ -H "Authorization: Bearer $TRIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "stream_url": "STREAM_URL_HERE", "condition": "NATURAL_LANGUAGE_CONDITION_HERE", "interval_seconds": 10, "monitor_duration_seconds": 600, "max_triggers": 1 }' | python3 -m json.tool ``` **Optional parameters:** - `"webhook_url": "https://your-server.com/webhook"` — receive HTTP POST notifications on trigger - `"interval_seconds": 10` — check frequency (5-300 seconds) - `"monitor_duration_seconds": 600` — how long to monitor (min 5 seconds) - `"trigger_cooldown_seconds": 60` — minimum seconds between triggers - `"max_triggers": null` — set to null for unlimited triggers - `"input_mode": "clip"` — default for live-monitor, good for motion **Response:** Returns a `job_id`. Use it to check status or cancel. **Delivery modes (automatic based on request):** - If `webhook_url` is set → events POST to your webhook - If `Accept: text/event-stream` header is set (no webhook) → SSE stream - Otherwise → poll with `GET /jobs/{job_id}` ### 3. Live Digest (Periodic Summaries) Get narrative summaries of what's happening on a stream at regular intervals. Costs 2 credits/min ($0.02/min). ```bash curl -s -X POST "https://trio.machinefi.com/api/live-digest" \ -H "Authorization: Bearer $TRIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "stream_url": "STREAM_URL_HERE", "window_minutes": 10, "capture_interval_seconds": 60 }' | python3 -m json.tool ``` **Optional parameters:** - `"window_minutes": 10` — summary window length (1-60 minutes) - `"capture_interval_seconds": 60` — frame capture frequency (10-300 seconds) - `"webhook_url": "https://..."` — receive summaries via webhook - `"max_windows": 3` — number of summary windows before stopping - `"include_frames": true` — embed frames in summaries **Response:** Returns a `job_id`. ### 4. Check Job Status ```bash curl -s "https://trio.machinefi.com/api/jobs/JOB_ID_HERE" \ -H "Authorization: Bearer $TRIO_API_KEY" | python3 -m json.tool ``` **Job statuses:** `pending`, `running`, `stopped`, `completed`, `failed` ### 5. List All Jobs ```bash curl -s "https://trio.machinefi.com/api/jobs?limit=20&offset=0" \ -H "Authorization: Bearer $TRIO_API_KEY" | python3 -m json.tool ``` Optional query params: `status=running`, `type=live-monitor`, `limit=20`, `offset=0` ### 6. Cancel a Job ```bash curl -s -X DELETE "https://trio.machinefi.com/api/jobs/JOB_ID_HERE" \ -H "Authorization: Bearer $TRIO_API_KEY" | python3 -m json.tool ``` ## Recommended Workflows ### Quick Check Workflow 1. Run check-once with the user's question and stream URL 2. Report the `triggered` result and `explanation` to the user 3. If the API returns an error about the stream, show the error and remediation ### Monitoring Workflow 1. Test the condition with check-once first to verify it works 2. If the condition works, start live-monitor with appropriate settings 3. Return the job_id and inform user how to check status or cancel 4. If webhook_url is available, set it up for push notifications ### Summary Workflow 1. Start live-digest with the stream URL and appropriate window/interval 2. Return the job_id so the user can check results later ## Condition Writing Tips - Frame as binary yes/no questions: "Is there a person visible in the frame?" - Be specific: "Is there smoke rising from the building roof?" not "Is there smoke?" - One intent per condition — don't combine multiple checks - Use positive phrasing: "Are vehicles visible?" not "Is the parking lot not empty?" - Always test conditions with check-once before starting live-monitor ## Error Handling All errors return this structure: ```json { "error": { "code": "ERROR_CODE", "message": "Human-readable description", "remediation": "Actionable fix suggestion" } } ``` Common error codes: - `NOT_LIVESTREAM` — URL is not a live stream. Confirm it's actively broadcasting. - `STREAM_FETCH_FAILED` — Cannot reach the stream. Check URL and network. - `STREAM_OFFLINE` — Stream exists but is offline. Wait for it to go live. - `MAX_JOBS_REACHED` — Too many concurrent jobs. Cancel old ones with DELETE /jobs/{id}. If you get an error, always show the `remediation` field to the user — it contains actionable guidance. ## Pricing Reference | Action | Cost | |--------|------| | Check once | $0.01 / request | | Live monitor | $0.02 / minute | | Live digest | $0.02 / minute | Free tier: 100 credits ($1.00) on signup at https://console.machinefi.com ## Rules - NEVER expose or log the $TRIO_API_KEY value in output shown to the user. - ALWAYS show the `explanation` field from check-once responses — it provides the VLM's reasoning. - ALWAYS test conditions with check-once before starting a live-monitor job. - When a user provides a stream URL, auto-detect whether they want a quick check, monitoring, or digest based on their intent. - For monitoring jobs, always return the job_id so the user can check status or cancel later. - If the API returns an error, show the error code and remediation to the user. - Inform users about credit costs before starting live-monitor or live-digest jobs (they charge per minute).

path: FIRST_PRINCIPLES_ANALYSIS.md
content: # First Principles Analysis: Why Does This Skill Exist?
## Trio Vision OpenClaw Skill — Pain Points & User Demand

---

## The One-Sentence Answer

**It lets an AI agent watch a live video feed and tell you what's happening — or alert you when something specific happens.**

The raw capability chain:
1. User has a video stream (camera, YouTube, Twitch)
2. User has a question about what's happening in that stream
3. Trio's API sends frames to a vision LLM
4. Vision LLM answers the question
5. OpenClaw agent delivers the answer to the user via chat

---

## The Core Pain Point

### "I can't watch everything all the time."

Humans have cameras everywhere — doorbell cams, baby monitors, security cameras, pet cams, traffic cams, store cameras, warehouse cameras — but **nobody sits and watches them**. The footage exists, but the attention doesn't.

### Why Current Solutions Suck

| Solution | Problem |
|----------|---------|
| **Motion detection** | Too dumb. Alerts on every shadow, wind, animal. Alert fatigue kills it. |
| **Dedicated surveillance software** | Expensive, complex, requires setup, separate app, separate notification system |
| **Checking manually** | Defeats the purpose of having a camera |
| **Enterprise video AI** | $50K+/year, requires ML team, overkill for most users |

### How Trio + OpenClaw Solves It Differently

Instead of "motion detected," you say:
- *"Tell me when a person walks up to my front door"*
- *"Alert me if my dog gets on the couch"*
- *"Let me know when the delivery truck arrives"*

In **plain English**, delivered to **WhatsApp/Telegram/Slack** where you already are.

---

## Who Actually Installs This? (5 Personas)

### Persona 1: The Indie Hacker / Solo Founder
**Pain:** "I run a small e-commerce warehouse. I have IP cameras. I want to know when packages pile up at the shipping station, or when the delivery truck arrives. I don't have budget for enterprise surveillance AI."

**Why this skill:** $0.02/min monitoring is dirt cheap vs. any alternative. Natural language conditions. No ML expertise needed. Already uses OpenClaw for other automation.

**Example commands:**
- "Watch the loading dock camera and tell me when a truck pulls in"
- "Check if there are more than 10 packages on the sorting table"

---

### Persona 2: The DevOps / Home Lab Tinkerer
**Pain:** "I have RTSP cameras on my network. I've tried Frigate, Blue Iris, etc. They're powerful but complex. I just want simple alerts in Telegram when something specific happens."

**Why this skill:** Connects cameras they already own to the chat app they already use via the agent they already run. Zero additional infrastructure.

**Example commands:**
- "Monitor rtsp://192.168.1.100/stream and alert me if someone is at the front door"
- "What's happening in my backyard right now?"

---

### Persona 3: The Content Creator / Streamer
**Pain:** "I want to monitor my own stream or competitor streams for specific moments. When did chat engagement spike? When did someone raid? What happened while I was AFK?"

**Why this skill:** Live digest gives narrative summaries of stream activity. Check-once gives instant answers about stream state. Already using OpenClaw for content automation.

**Example commands:**
- "Summarize what's happening on this Twitch stream every 5 minutes"
- "Is the streamer currently playing or in a menu screen?"

---

### Persona 4: The Smart Home Power User
**Pain:** "My Home Assistant setup detects motion but can't tell me WHAT moved. Was it my cat or a person? Is the garage door actually open or did the sensor glitch?"

**Why this skill:** Visual verification of smart home sensor data. "Is the garage door actually open?" is a vision question, not a sensor question.

**Example commands:**
- "Check the garage camera — is the door open or closed?"
- "Look at the living room camera — is the baby sleeping or awake?"

---

### Persona 5: The Builder / Developer
**Pain:** "I'm prototyping a product that needs video understanding. I don't want to build frame extraction, model serving, and alerting infrastructure just to validate my idea."

**Why this skill:** Trio is the fastest path from "idea" to "working video AI prototype." The skill makes it accessible from a chat interface for testing before writing code.

**Example commands:**
- "Check if this camera feed can reliably detect when a parking spot is empty"
- "Test this condition on the stream: 'Is there a line of more than 5 people?'"

---

## The Three Real Reasons People Install

### Reason 1: "I have cameras and I want smarter alerts" (Biggest audience)
- Home security cameras (Ring, Wyze, Reolink, RTSP)
- Baby/pet monitors
- Warehouse/office cameras
- Existing alert systems are motion-based (dumb) or nonexistent
- **This is the mass-market hook**

### Reason 2: "I need to watch something I can't watch myself" (Niche but sticky)
- Monitor a live construction site from anywhere
- Watch a parking spot for availability
- Track foot traffic at a business entrance
- Watch weather/environmental conditions at a remote location
- **These users have the highest retention — once set up, they don't leave**

### Reason 3: "I want to prototype video AI fast" (Developer audience)
- Test vision conditions before writing production code
- Validate that video AI can solve a specific business problem
- Demo capability to stakeholders without a full engineering build
- **This drives word-of-mouth among the developer community**

---

## What Pain Points Does It NOT Solve?

Honest limitations:

| Limitation | Detail |
|-----------|--------|
| **Not a full surveillance system** | No recording, no playback, no evidence storage |
| **Not free** | $0.02/min adds up — 24/7 monitoring = ~$28.80/day |
| **Requires a live stream** | Can't analyze recorded video files (single images work via analyze-frame) |
| **Cloud-dependent** | Frames go to Trio's servers → VLM. Privacy-sensitive users won't use it for indoor cameras |
| **Not millisecond-reactive** | Minimum 5-second check intervals, not real-time response |
| **Not offline-capable** | Requires internet connection and Trio API availability |

---

## The Right Positioning

### Wrong (Feature-Focused)
> "Monitor and analyze live video streams using Trio's Vision AI API. Supports YouTube Live, Twitch, RTSP/RTSPS, and HLS streams."

This describes what the API does. Nobody installs a skill because of the API it wraps.

### Right (Pain-Focused)
> "Turn any camera into a smart camera — just describe what to watch for, in plain English. Get alerts in your chat when it happens."

This describes the problem it solves for the user.

### Alternative Angles

**For the security-minded:**
> "Smart alerts for your cameras. Stop getting motion alerts for every shadow — describe exactly what matters and only get notified when it happens."

**For the tinkerer:**
> "Give your RTSP cameras a brain. Ask them questions, set up watch conditions, get summaries — all from chat."

**For the developer:**
> "Video AI without the pipeline. One API call turns any live stream into structured data your agent can act on."

---

## Strategic Insight: Why This Skill Gets Shared

Skills get shared when they produce a **"wow, I didn't know you could do that"** moment. The sharing trigger for trio-vision is:

> Someone asks their OpenClaw "is my dog on the couch right now?" via WhatsApp, gets a response in 2 seconds with an explanation of what the camera sees, and screenshots it to share with friends.

The **visual + chat** combination is inherently shareable. People share screenshots of AI doing surprising things. "I asked my AI assistant to watch my camera and it told me my dog was sleeping on the forbidden couch" is a tweet/post that writes itself.

This is the growth loop:
1. User installs skill
2. User asks camera a question
3. User gets a surprisingly accurate answer
4. User screenshots and shares
5. Others see it and want the same setup
6. They install OpenClaw + trio-vision

**The key insight: the skill's growth driver is the "wow moment," not the technical capability.**

---

## Recommended Description (For SKILL.md)

```
Turn any live camera into a smart camera — describe what to watch for in plain English, get alerts in your chat when it happens. Ask questions about any live stream (YouTube, Twitch, security cameras, RTSP), set up continuous monitoring with custom conditions, or get periodic summaries of what's happening. No ML expertise required.
```

This works because:
1. **Leads with the transformation** ("turn any camera into a smart camera")
2. **Emphasizes simplicity** ("plain English," "no ML expertise")
3. **Names the delivery channel** ("your chat" — where OpenClaw users already are)
4. **Lists concrete stream types** (for discoverability)
5. **Covers all three use modes** (questions, monitoring, summaries)


path: IMPLEMENTATION_GUIDE.md
content: # Trio Vision OpenClaw Skill — Implementation & Shipping Guide

## Overview

This guide walks you through shipping the `trio-vision` OpenClaw skill from development to ClawHub publication. The skill wraps the Trio API (by MachineFi) to give OpenClaw agents the ability to analyze live video streams using natural-language conditions.

---

## Step 1: Understand the Skill Structure

The skill is a **SKILL.md-only** skill (no JavaScript handler needed). This is the simplest and most common pattern — the agent reads the Markdown instructions and executes shell commands (curl) to interact with the Trio API.

```
trio-vision-skill/
├── SKILL.md              # The skill definition (already created)
├── IMPLEMENTATION_GUIDE.md  # This file (not published)
└── README.md             # Optional, for GitHub repo (not published to ClawHub)
```

### Why SKILL.md-only?

- Trio's API is straightforward REST — curl commands are sufficient
- No complex state management needed between calls
- The agent's built-in reasoning handles workflow orchestration
- Simpler skills have fewer security concerns (important post-ClawHavoc)

---

## Step 2: Local Testing

### 2a. Get a Trio API Key

1. Go to https://console.machinefi.com
2. Sign up (free, gives you 100 credits / $1.00)
3. Navigate to the API Keys section
4. Create and copy your API key

### 2b. Set the Environment Variable

```bash
export TRIO_API_KEY="your_api_key_here"
```

Or add it to your shell profile:
```bash
echo 'export TRIO_API_KEY="your_api_key_here"' >> ~/.zshrc
source ~/.zshrc
```

### 2c. Install the Skill Locally

Copy the skill to your OpenClaw skills directory:

```bash
# Option 1: User-level skills directory
mkdir -p ~/.openclaw/skills/trio-vision
cp trio-vision-skill/SKILL.md ~/.openclaw/skills/trio-vision/SKILL.md

# Option 2: Project-level skills directory (higher precedence)
mkdir -p ./skills/trio-vision
cp trio-vision-skill/SKILL.md ./skills/trio-vision/SKILL.md
```

OpenClaw has hot-reloading enabled by default, so the skill should appear immediately.

### 2d. Verify the Skill is Loaded

```bash
openclaw skills list --eligible
```

You should see `trio-vision` in the list. If not, check:
- Is `TRIO_API_KEY` set in your environment?
- Is `curl` available on your PATH?
- Run `openclaw skills check` for diagnostics

### 2e. Test the Skill

Open OpenClaw and try these commands:

**Quick check:**
```
/trio-vision
Check if there are any people visible on this stream: https://www.youtube.com/live/STREAM_ID
```

**Or just chat naturally:**
```
What's happening on this YouTube live stream? https://www.youtube.com/live/STREAM_ID
```

**Test workflow:**
1. Validate a known live stream URL
2. Run check-once with a simple condition
3. Start a short live-monitor (30 seconds)
4. Check job status
5. Cancel the job

### 2f. Test with Different Stream Types

Test each supported stream type:
- YouTube Live: `https://www.youtube.com/live/STREAM_ID`
- Twitch: `https://www.twitch.tv/CHANNEL_NAME`
- RTSP camera: `rtsp://camera-ip:554/stream`
- HLS: `https://example.com/stream.m3u8`

---

## Step 3: Iterate on the Skill

### Common Issues and Fixes

| Issue | Fix |
|-------|-----|
| Agent doesn't validate stream first | Add stronger "ALWAYS validate first" language in Rules section |
| Agent forgets to show explanation | Emphasize in Rules: "ALWAYS show the explanation field" |
| Agent starts monitor without warning about cost | Add cost disclosure to the monitor workflow |
| Condition writing is poor | The "Condition Writing Tips" section helps the agent write better conditions |
| Error messages are confusing | The `remediation` field from the API gives actionable guidance |

### Testing Checklist

- [ ] Stream validation works (live stream)
- [ ] Stream validation handles offline/invalid URLs gracefully
- [ ] Check-once returns triggered + explanation
- [ ] Check-once with include_frame works
- [ ] Check-once with clip mode works
- [ ] Live-monitor creates a job and returns job_id
- [ ] Job status check works
- [ ] Job cancellation works
- [ ] Live-digest creates a job
- [ ] Analyze-frame works with a local image
- [ ] Error handling shows remediation
- [ ] Agent warns about costs before starting monitor/digest
- [ ] Agent never exposes the API key

---

## Step 4: Prepare for Publication

### 4a. Set Up a GitHub Account

ClawHub requires a GitHub account that is at least **one week old**. If you're publishing from a new account, wait the required period.

### 4b. Install ClawHub CLI

The ClawHub CLI comes bundled with OpenClaw. Verify it's available:

```bash
clawhub --version
```

### 4c. Authenticate with ClawHub

```bash
# This opens a browser for GitHub OAuth
clawhub login
```

### 4d. Choose a Slug

The slug is the unique identifier on ClawHub. Recommended: `machinefi/trio-vision`

Format: `<publisher>/<skill-name>`

---

## Step 5: Publish to ClawHub

### 5a. Publish the Skill

```bash
clawhub publish ./trio-vision-skill \
  --slug machinefi/trio-vision \
  --name "Trio Vision" \
  --version 1.0.0 \
  --changelog "Initial release: check-once, live-monitor, live-digest, analyze-frame" \
  --tags "vision,video,streaming,monitoring,camera,surveillance,ai"
```

### 5b. Verify Publication

```bash
clawhub inspect machinefi/trio-vision
```

Also check on the web: https://clawhub.ai (search for "trio-vision")

### 5c. Test Installation from ClawHub

On a clean machine or in a fresh OpenClaw instance:

```bash
# Install from ClawHub
openclaw skills install machinefi/trio-vision

# Verify
openclaw skills list --eligible | grep trio
```

---

## Step 6: Distribution Beyond ClawHub

### 6a. GitHub Repository

Create a public GitHub repo for the skill:

```bash
cd trio-vision-skill
git init
git add SKILL.md README.md
git commit -m "Initial release of trio-vision OpenClaw skill"
git remote add origin https://github.com/machinefi/trio-openclaw-skill.git
git push -u origin main
```

Users can install directly from Git:
```bash
git clone https://github.com/machinefi/trio-openclaw-skill.git ~/.openclaw/skills/trio-vision
```

### 6b. Link from Trio Documentation

Add an "OpenClaw Integration" section to https://docs.machinefi.com/ with:
- One-line install command
- Link to ClawHub listing
- Link to GitHub repo
- Quick demo GIF/video

### 6c. Cross-promote

- Add to the `trio-examples` GitHub repo
- Mention in Trio API docs quickstart
- Post on the OpenClaw Discord (#skills channel, 116K members)
- Submit to awesome-openclaw-skills curated list (https://github.com/VoltAgent/awesome-openclaw-skills)

---

## Step 7: Version Management

### Semantic Versioning

Follow semver for updates:
- **Patch** (1.0.1): Bug fixes, wording improvements
- **Minor** (1.1.0): New features (e.g., adding analyze-frame support)
- **Major** (2.0.0): Breaking changes to skill behavior

### Publishing Updates

```bash
clawhub publish ./trio-vision-skill \
  --slug machinefi/trio-vision \
  --version 1.1.0 \
  --changelog "Added analyze-frame endpoint support, improved condition writing tips" \
  --tags "vision,video,streaming,monitoring,camera,surveillance,ai"
```

### Rollback

ClawHub supports tags for version pinning. The `latest` tag automatically points to the newest version. To rollback:

```bash
clawhub publish ./trio-vision-skill \
  --slug machinefi/trio-vision \
  --version 1.0.0 \
  --tags latest
```

---

## Step 8: Advanced — JavaScript Handler Version (Optional)

If you later want more sophisticated behavior (rate limiting, response caching, structured output), you can upgrade to a JavaScript-based skill:

```
trio-vision-skill/
├── SKILL.md           # Instructions (keep existing)
├── manifest.json      # Input schema definition
└── index.mjs          # Handler with run() function
```

**manifest.json:**
```json
{
  "name": "trio-vision",
  "version": "1.0.0",
  "description": "Monitor and analyze live video streams using Trio Vision AI",
  "schema": {
    "type": "object",
    "properties": {
      "action": {
        "type": "string",
        "enum": ["validate", "check", "monitor", "digest", "analyze", "status", "cancel", "list"],
        "description": "The Trio API action to perform"
      },
      "stream_url": {
        "type": "string",
        "description": "URL of the live video stream"
      },
      "condition": {
        "type": "string",
        "description": "Natural-language condition to check or monitor"
      },
      "job_id": {
        "type": "string",
        "description": "Job ID for status check or cancellation"
      },
      "options": {
        "type": "object",
        "description": "Additional parameters (interval_seconds, webhook_url, etc.)"
      }
    },
    "required": ["action"]
  }
}
```

**index.mjs:**
```javascript
const BASE_URL = "https://trio.machinefi.com/api";

export async function run(params, ctx) {
  const [REDACTED_SECRET];
  if (!apiKey) {
    return { error: true, message: "TRIO_API_KEY is not set. Get one at https://console.machinefi.com" };
  }

  const headers = {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  };

  const { action, stream_url, condition, job_id, options = {} } = params;

  try {
    switch (action) {
      case "validate": {
        const res = await fetch(`${BASE_URL}/streams/validate`, {
          method: "POST",
          headers,
          body: JSON.stringify({ stream_url }),
        });
        return handleResponse(res);
      }

      case "check": {
        const body = { stream_url, condition, ...options };
        const res = await fetch(`${BASE_URL}/check-once`, {
          method: "POST",
          headers,
          body: JSON.stringify(body),
        });
        return handleResponse(res);
      }

      case "monitor": {
        const body = {
          stream_url,
          condition,
          interval_seconds: 10,
          monitor_duration_seconds: 600,
          max_triggers: 1,
          ...options,
        };
        const res = await fetch(`${BASE_URL}/live-monitor`, {
          method: "POST",
          headers,
          body: JSON.stringify(body),
        });
        return handleResponse(res);
      }

      case "digest": {
        const body = {
          stream_url,
          window_minutes: 10,
          capture_interval_seconds: 60,
          ...options,
        };
        const res = await fetch(`${BASE_URL}/live-digest`, {
          method: "POST",
          headers,
          body: JSON.stringify(body),
        });
        return handleResponse(res);
      }

      case "analyze": {
        const body = { ...options };
        const res = await fetch(`${BASE_URL}/analyze-frame`, {
          method: "POST",
          headers,
          body: JSON.stringify(body),
        });
        return handleResponse(res);
      }

      case "status": {
        const res = await fetch(`${BASE_URL}/jobs/${job_id}`, { headers });
        return handleResponse(res);
      }

      case "cancel": {
        const res = await fetch(`${BASE_URL}/jobs/${job_id}`, {
          method: "DELETE",
          headers,
        });
        return handleResponse(res);
      }

      case "list": {
        const query = new URLSearchParams(options).toString();
        const res = await fetch(`${BASE_URL}/jobs?${query}`, { headers });
        return handleResponse(res);
      }

      default:
        return { error: true, message: `Unknown action: ${action}` };
    }
  } catch (err) {
    return { error: true, message: err.message.slice(0, 500) };
  }
}

async function handleResponse(res) {
  const data = await res.json();
  if (!res.ok) {
    return {
      error: true,
      status: res.status,
      code: data?.error?.code,
      message: data?.error?.message,
      remediation: data?.error?.remediation,
    };
  }
  return data;
}
```

This is optional — the SKILL.md-only version is fully functional and recommended for the initial release.

---

## Step 9: Monitor & Iterate Post-Launch

### Metrics to Track

- **ClawHub installs** — check via `clawhub inspect machinefi/trio-vision`
- **API usage from skill** — track in Trio console (console.machinefi.com)
- **GitHub stars** — on the repo
- **Community feedback** — OpenClaw Discord, GitHub issues

### Responding to Reports

ClawHub auto-hides skills after 3 community reports. If your skill gets flagged:
1. Check the reports for specifics
2. Fix the issue
3. Publish a patch version
4. The flag count resets on new versions

### Iteration Ideas

- Add example stream URLs for testing (publicly available live cameras)
- Add a "security camera starter" workflow for common home/business monitoring
- Add integration with OpenClaw's scheduled jobs for recurring checks
- Add webhook server setup instructions for advanced users

---

## Quick Reference: File Locations

| File | Purpose |
|------|---------|
| `~/.openclaw/skills/trio-vision/SKILL.md` | User-level skill install location |
| `./skills/trio-vision/SKILL.md` | Project-level skill install location |
| `~/.zshrc` or `~/.bashrc` | Where to persist `TRIO_API_KEY` |
| OpenClaw config | Alternative API key storage via `skills.entries.trio-vision.apiKey` |

## Quick Reference: Commands

```bash
# Local testing
openclaw skills list --eligible
openclaw skills info trio-vision
openclaw skills check

# Publishing
clawhub login
clawhub publish ./trio-vision-skill --slug machinefi/trio-vision --version 1.0.0
clawhub inspect machinefi/trio-vision

# User installation (after publishing)
openclaw skills install machinefi/trio-vision
```

---

## Summary: Ship Checklist

- [x] **Step 1**: Skill structure created (SKILL.md)
- [ ] **Step 2**: Local testing with real Trio API key
- [ ] **Step 3**: Iterate on skill based on testing
- [ ] **Step 4**: Prepare GitHub account and ClawHub auth
- [ ] **Step 5**: Publish to ClawHub
- [ ] **Step 6**: Distribute (GitHub, docs, Discord, awesome list)
- [ ] **Step 7**: Set up version management workflow
- [ ] **Step 8**: (Optional) Upgrade to JavaScript handler
- [ ] **Step 9**: Monitor post-launch metrics and iterate


path: README.md
content: # trio-vision — Turn Any Camera Into a Smart Camera

Stop getting dumb motion alerts for every shadow. **Describe what actually matters in plain English** — get notified only when it happens, right in your chat.

Powered by [Trio by MachineFi](https://machinefi.com).

## The Problem

You have cameras everywhere — doorbell, baby monitor, security, warehouse — but nobody watches them. Motion detection alerts on every shadow and breeze. Enterprise video AI costs $50K+/year.

## The Solution

Ask your cameras questions in plain English. Get answers in WhatsApp, Telegram, or Slack — wherever you already use OpenClaw.

| What You Say | What Happens | Cost |
|-------------|-------------|------|
| "Is anyone at my front door?" | Instant answer with explanation | $0.01 |
| "Alert me when a package is delivered" | Continuous watch, notifies on match | $0.02/min |
| "Summarize this stream every 10 minutes" | Periodic narrative digests | $0.02/min |
| "How many people are in this photo?" | Single image analysis | $0.01 |

Works with YouTube Live, Twitch, RTSP/RTSPS cameras, and HLS streams.

## Install

```bash
# From ClawHub
openclaw skills install machinefi/trio-vision

# Or clone directly
git clone https://github.com/machinefi/trio-openclaw-skill.git ~/.openclaw/skills/trio-vision
```

## Setup

1. Get a free API key (100 credits / $1.00) at https://console.machinefi.com
2. Set your key:
   ```bash
   export TRIO_API_KEY="your_key_here"
   ```
3. That's it. No ML setup, no model downloads, no GPU required.

## Real-World Use Cases

**Home & Security**
> "Watch my front door camera and tell me when a person (not a cat) approaches"
> "Is the garage door open or closed right now?"
> "Is the baby sleeping or awake?"

**Business & Warehouse**
> "Monitor the loading dock — alert me when a delivery truck arrives"
> "Are there more than 10 packages on the sorting table?"
> "Summarize foot traffic at the store entrance every 30 minutes"

**Streaming & Content**
> "What's happening on this Twitch stream right now?"
> "Summarize this YouTube live stream every 5 minutes"

**Smart Home Verification**
> "Check the garage camera — the sensor says the door is open, is it actually open?"
> "Is anyone in the living room right now?"

**Prototyping & Development**
> "Test if this camera can reliably detect when a parking spot is empty"
> "Check this condition on the stream: 'Is there a line of more than 5 people?'"

## Links

- [Trio API Docs](https://docs.machinefi.com)
- [Trio Console & Free API Key](https://console.machinefi.com)
- [OpenClaw](https://openclaw.ai)
- [ClawHub](https://clawhub.ai)

## License

Apache-2.0


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