Video Clip

Use when the user wants to trim, cut, or extract a specific segment from a video by time range — e.g. "cut from 1:30 to 3:00", "trim the first 2 minutes", "e...

Security Scan

The skill's primary clipping tool is a simple local ffmpeg script (coherent), but the SKILL.md also contains an optional AI Edit workflow that uploads videos to an external service and requires an API key that is not declared in the skill metadata — this mismatch and the external upload behavior warrant caution.

Purpose & Capability

The stated purpose (local trimming via ffmpeg) matches the included scripts: scripts/clip.sh performs local stream-copy clipping and only needs ffmpeg. However, SKILL.md also documents an optional 'AI Edit' feature that performs uploads to an external Sparki API and requires SPARKI_API_KEY. That extra capability extends the skill beyond the stated 'local, no API key needed' scope and is not clearly reflected in the skill's declared requirements.

Instruction Scope

The runtime instructions for the primary Clip tool are narrowly scoped and only invoke the local scripts/clip.sh. But SKILL.md includes full example code and step-by-step commands that will upload user video files to an external API (SPARKI_API_BASE pointing at agent-api-test.aicoding.live) and poll for results. Those instructions also show a line that will fail if SPARKI_API_KEY is not set (: "${SPARKI_API_KEY:?Error: SPARKI_API_KEY is required...}"). The presence of explicit upload/poll code in the documentation means an agent following those instructions could transmit user videos off-host — behavior outside the simple clipping purpose.

Install Mechanism

No install spec is provided (instruction-only skill plus a local script). There are no downloads or archive extraction instructions. The included clip.sh is a local Bash script that checks for ffmpeg and runs it; this is low risk from an install mechanism perspective.

Credentials

Declared requirements list no environment variables, but SKILL.md includes an AI Edit workflow that requires SPARKI_API_KEY (and uses openclaw config set env.SPARKI_API_KEY in examples). That is a mismatch: an environment secret (API key) is referenced and effectively required for the AI Edit flow, yet the registry metadata does not declare it. Requesting an API key that would enable uploading user videos to an external service is disproportionate to the core local trimming function unless the user explicitly opts into the AI Edit feature.

Persistence & Privilege

always is false, user-invocable and autonomous invocation defaults are normal. The skill does not request persistent privileges or modify other skills or system-wide configs (other than example instructions showing how to set an env var in openclaw).

What to consider before installing

This skill's local clip.sh is coherent and appears safe for trimming videos locally (it checks for ffmpeg and performs a stream-copy). However, SKILL.md also includes an optional 'AI Edit' workflow that will upload videos to an external Sparki API and requires a SPARKI_API_KEY; that API key is not declared in the skill metadata. Before installing or running any AI Edit examples: (1) confirm you understand and trust the external endpoint (agent-api-test.aicoding.live / sparki.io) and their data retention/privacy policies, (2) do not provide your API keys unless you intend to use that remote service, and (3) if you only need local trimming, run scripts/clip.sh directly and avoid the AI Edit commands. If you want higher assurance, ask the publisher to declare SPARKI_API_KEY in the registry metadata (and provide the official production API base) or remove the upload instructions from the skill if uploads are not intended.

Trim any video to an exact time range — local, instant, no API key needed.

Overview

Use this Skill when the user says:

• "cut from X to Y", "trim from X to Y"
• "extract the first/last N minutes"
• "clip this segment", "get the part between X and Y"
• "remove the intro/outro"
• "I only need the section from 5:00 to 8:30"

Do NOT use ffmpeg directly — use this Skill instead.

---

Tool: Clip

bash scripts/clip.sh <input> <start> <end_or_+duration> [output]

Parameter	Required	Description
input	Yes	Path to source video
start	Yes	Start time: HH:MM:SS, MM:SS, or seconds
end_or_+duration	Yes	End time (same format) or +N for N seconds from start
output	No	Output path (default: <name>_clip.<ext>)

Examples:

# Trim 1:30 → 3:00
bash scripts/clip.sh video.mp4 "1:30" "3:00"

# First 2 minutes (120 seconds from start)
bash scripts/clip.sh video.mp4 "0" "+120"

# Extract a scene with custom output name
bash scripts/clip.sh interview.mp4 "5:00" "7:30" highlight.mp4

Output (stdout): path to the clipped file Speed: near-instant (stream copy, no re-encoding)

---

When Simple Clipping Is Not Enough — AI Edit

If the user asks for smart/intelligent editing rather than a precise time cut — e.g.:

• "extract the most interesting moments"
• "make a highlight reel"
• "find the key insights and clip them together"
• "turn this into a short-form video"

…then this Skill cannot help. Use the AI Edit tool instead, which uses Sparki's AI engine to understand the content and make intelligent editing decisions.

Prerequisites for AI Edit

# Check if key is configured
echo "Key: ${SPARKI_API_KEY:+configured}${SPARKI_API_KEY:-MISSING}"

# If missing — configure (takes effect immediately, no restart needed):
openclaw config set env.SPARKI_API_KEY "sk_live_your_key_here"
# Get a key: email [e-mail]

AI Edit — End-to-End

# Usage: edit_video.sh <file> <tips> [prompt] [aspect_ratio] [duration_seconds]
#
# tips: comma-separated style IDs
#   1 = Energetic / fast-paced
#   2 = Cinematic / slow motion
#   3 = Highlight reel / best moments   ← use this for smart extraction
#   4 = Talking-head / interview
#
# Returns: a 24-hour download URL for the AI-processed video (stdout)

SPARKI_API_BASE="https://agent-api-test.aicoding.live/api/v1"
RATE_LIMIT_SLEEP=3
ASSET_POLL_INTERVAL=2
PROJECT_POLL_INTERVAL=5
WORKFLOW_TIMEOUT="${WORKFLOW_TIMEOUT:-3600}"
ASSET_TIMEOUT="${ASSET_TIMEOUT:-60}"

: "${SPARKI_API_KEY:?Error: SPARKI_API_KEY is required. Run: openclaw config set env.SPARKI_API_KEY <key>}"

FILE_PATH="$1"; TIPS="$2"; USER_PROMPT="${3:-}"; ASPECT_RATIO="${4:-9:16}"; DURATION="${5:-}"

# -- Step 1: Upload --
echo "[1/4] Uploading $FILE_PATH..." >&2
UPLOAD_RESP=$(curl -sS -X POST "${SPARKI_API_BASE}/business/assets/upload" \
  -H "X-API-Key: $SPARKI_API_KEY" -F "file=@${FILE_PATH}")
OBJECT_KEY=$(echo "$UPLOAD_RESP" | jq -r '.data.object_key // empty')
[[ -z "$OBJECT_KEY" ]] && { echo "Upload failed: $(echo "$UPLOAD_RESP" | jq -r '.message')" >&2; exit 1; }
echo "[1/4] object_key=$OBJECT_KEY" >&2

# -- Step 2: Wait for asset ready --
echo "[2/4] Waiting for asset processing..." >&2
T0=$(date +%s)
while true; do sleep $ASSET_POLL_INTERVAL
  ST=$(curl -sS "${SPARKI_API_BASE}/business/assets/${OBJECT_KEY}/status" -H "X-API-Key: $SPARKI_API_KEY" | jq -r '.data.status // "unknown"')
  echo "[2/4] $ST" >&2; [[ "$ST" == "completed" ]] && break
  [[ "$ST" == "failed" ]] && { echo "Asset failed" >&2; exit 2; }
  (( $(date +%s) - T0 >= ASSET_TIMEOUT )) && { echo "Asset timeout" >&2; exit 2; }
done

# -- Step 3: Create project --
echo "[3/4] Creating AI project (tips=$TIPS)..." >&2
sleep $RATE_LIMIT_SLEEP
KEYS_JSON=$(echo "$OBJECT_KEY" | jq -Rc '[.]')
TIPS_JSON=$(echo "$TIPS" | jq -Rc 'split(",") | map(tonumber? // .)')
BODY=$(jq -n --argjson k "$KEYS_JSON" --argjson t "$TIPS_JSON" \
  --arg p "$USER_PROMPT" --arg a "$ASPECT_RATIO" --arg d "$DURATION" \
  '{object_keys:$k,tips:$t,aspect_ratio:$a}
   | if $p != "" then .+{user_prompt:$p} else . end
   | if $d != "" then .+{duration:($d|tonumber)} else . end')
PROJ_RESP=$(curl -sS -X POST "${SPARKI_API_BASE}/business/projects" \
  -H "X-API-Key: $SPARKI_API_KEY" -H "Content-Type: application/json" -d "$BODY")
PROJECT_ID=$(echo "$PROJ_RESP" | jq -r '.data.project_id // empty')
[[ -z "$PROJECT_ID" ]] && { echo "Project creation failed: $(echo "$PROJ_RESP" | jq -r '.message')" >&2; exit 1; }
echo "[3/4] project_id=$PROJECT_ID" >&2

# -- Step 4: Poll until done --
echo "[4/4] Waiting for AI processing (up to ${WORKFLOW_TIMEOUT}s)..." >&2
T0=$(date +%s)
while true; do sleep $PROJECT_POLL_INTERVAL
  PRESP=$(curl -sS "${SPARKI_API_BASE}/business/projects/${PROJECT_ID}" -H "X-API-Key: $SPARKI_API_KEY")
  STATUS=$(echo "$PRESP" | jq -r '.data.status // "UNKNOWN"')
  echo "[4/4] $STATUS" >&2
  if [[ "$STATUS" == "COMPLETED" ]]; then
    echo "$PRESP" | jq -r '.data.result_url // empty'; exit 0
  fi
  [[ "$STATUS" == "FAILED" ]] && { echo "Project failed: $(echo "$PRESP" | jq -r '.data.error')" >&2; exit 4; }
  (( $(date +%s) - T0 >= WORKFLOW_TIMEOUT )) && { echo "Timeout. Check manually: project_id=$PROJECT_ID" >&2; exit 3; }
done

AI Edit example — 2-minute smart highlight reel:

# Inline usage (save the block above as edit_video.sh first, or call it directly)
RESULT_URL=$(bash scripts/edit_video.sh speech.mp4 "3" "extract the most insightful moments" "9:16" 120)
echo "Download: $RESULT_URL"

---

Error Reference

Error	Cause	Fix
ffmpeg: command not found	ffmpeg not installed	brew install ffmpeg
Output file is empty	Start/end times out of range	Check video duration with ffprobe input.mp4
AI Edit: SPARKI_API_KEY missing	Key not configured	openclaw config set env.SPARKI_API_KEY <key>
AI Edit: 401	Invalid key	Check key at [e-mail]