video-searching

# Video Searching Skill Use this skill when the user asks to find, compare, or analyze social videos (YouTube, TikTok, Instagram, Twitter/X), or explicitly invokes `/video_search`. This skill calls the Memories.ai Video Searching API — a managed, token-authenticated endpoint that searches across platforms and returns structured results via SSE. ## Triggering Run this workflow when either condition is true: 1. Message starts with `/video_search`. 2. The user asks for video sourcing/trend/creator/brand analysis and wants concrete video links. If `/video_search` is used with no query body, ask for the missing query. ## Execution contract 1. Resolve query text: - `/video_search ...` → strip `/video_search` and use remaining text. - Free-form → use user message as query. 2. Build the API request JSON body: - `query` (required): the user's search query - `platforms` (optional): array of `youtube`, `tiktok`, `instagram`, `twitter` — only set if user specifies platforms - `max_results` (optional, default 10): number of video results - `time_frame` (optional): `past_24h`, `past_week`, `past_month`, `past_year` — only set if user specifies recency - `max_steps` (optional, default 10): max agent iterations - `enable_clarification` (optional, default false): set to true if user query is vague 3. Call the runner script: ``` <skill_dir>/scripts/run_video_query.sh \ --query "<query>" \ [--platforms "youtube,tiktok"] \ [--max-results 10] \ [--time-frame past_week] \ [--enable-clarification] ``` 4. Start with `exec` using `background: true`. 5. Poll with `process` using `action: "poll"` every 2–4 seconds until process exits. 6. Parse NDJSON output and render only these events: - `started` → send: `🔍 Starting video search...` - `progress` → send concise progress update from `message` field (throttle: skip if last update was < 3s ago) - `complete` → send final formatted response (see below) - `clarification` → ask the clarification question directly; treat as final response - `error` → send concise failure reason with one actionable next step 7. Do not forward raw `tool_call` or `tool_result` events to the user. ## Final response format When terminal event is `complete`: 1. One short paragraph conclusion (from `answer` field). 2. Top video references (up to 5 by default): - `title` - `url` - `platform` badge (e.g. 🎬 YouTube, 🎵 TikTok, 📸 Instagram, 🐦 X) - one-line `relevance_note` - key metrics: views, likes, engagement rate (if available) 3. Footer: `⏱ {execution_time_seconds}s · {steps_taken} steps · {tools_used}` If fewer videos exist, show all available references. When terminal event is `clarification`: 1. Ask the clarification question directly. 2. Present options if provided. 3. Treat as final response for the current run. When terminal event is `error`: 1. Send concise failure reason. 2. Include one actionable next step. ## Safety and fallback 1. If `MEMORIES_API_KEY` is not set, tell the user: > ⚠️ Missing `MEMORIES_API_KEY`. Set it in your OpenClaw environment variables to use this skill. > Get your API key at https://api-tools.memories.ai 2. If the API returns a non-SSE error (HTTP 4xx/5xx), display the error message. 3. Never fabricate video URLs or metrics. 4. If the API is unreachable, suggest checking network connectivity and API status.