Organise videos

Organize a video folder by cleaning non-video files, removing short/bad videos, and classifying videos into numbered subfolders using AI vision analysis.

Security Scan

The skill's high-level purpose (organise videos) matches the instructions, but the runtime instructions rely on system tools (ffmpeg/ffprobe, bc, find, etc.) that the skill does not declare and include destructive filesystem commands and image uploads that raise privacy and safety concerns if the environment or user consent are not carefully controlled.

Purpose & Capability

The skill says no required binaries or env vars, but the SKILL.md consistently uses ffmpeg, ffprobe, bc, find, mkdir, mv, rm and shell utilities. That is an incoherence: a user running this skill will need those binaries available. Requesting filesystem operations (move/delete) is consistent with 'organise videos', but the missing declared prerequisites is a problem.

Instruction Scope

The instructions instruct the agent to scan a user-supplied folder, list and move or permanently delete files, extract frames into /tmp, and use an AI vision analysis step (Read tool) on images. Deletions are gated by AskUserQuestion in the flow, but many code snippets show unconditional rm/mv commands (no safety flags), placeholders like '[non-video files]' that could be mis-substituted, and use of a fixed /tmp directory (possible symlink/TOCTOU risks). The AI analysis step implies sending extracted frames to the model — the SKILL.md does not state whether image data stays local or is sent to an external service, so there is a privacy risk.

Install Mechanism

This is an instruction-only skill with no install spec, so nothing is written to disk by the skill itself. That reduces installer risk. However, it still depends on external binaries at runtime (see purpose_capability).

Credentials

The skill declares no environment variables or credentials — that matches its stated purpose. There is no request for unrelated secrets or config paths.

Persistence & Privilege

The skill is not forced-always and does not request persistent/global privileges. It is user-invocable and can be run autonomously per platform defaults, which is normal. No evidence it modifies other skills or system-wide agent settings.

What to consider before installing

Before installing or running this skill: (1) Understand it will run shell commands that can permanently delete or move files — make a backup or test on a copy of your folder first. (2) Ensure the runtime environment has ffmpeg and ffprobe (and bc, find, standard shell utilities); the skill fails silently if these are missing but it does not declare them. (3) Ask where the AI vision analysis runs — extracted frames may be sent to an external model or API, which could expose your video content; ask the skill author how images are handled and whether processing is local. (4) Be cautious about the provided shell snippets: they use fixed temp paths (/tmp/video_frames) and plain rm/mv commands without safety checks — consider running interactively or adding safety flags and validation. (5) Prefer installing only if you trust the owner or can inspect/modify the SKILL.md to add explicit binary requirements and safer command usage.

Video Folder Organizer

Intelligently organize a video folder: clean up non-video files, remove bad footage, analyze content with AI, and sort into categorized subfolders.

Usage

User wants to organize a video folder: $ARGUMENTS

If the user has not provided a folder path, ask them to provide one.

Language note: Detect the language the user is writing in and respond in that language throughout the entire session. Category folder names should also be in the user's language.

---

Step 1: Scan the Folder

Scan the folder for all files (non-recursive at root level first):

# List all files with sizes
ls -la "$FOLDER"

# Find video files (common extensions)
find "$FOLDER" -maxdepth 1 -type f \( \
  -iname "*.mp4" -o -iname "*.mov" -o -iname "*.avi" -o -iname "*.mkv" \
  -o -iname "*.m4v" -o -iname "*.wmv" -o -iname "*.flv" -o -iname "*.webm" \
  -o -iname "*.mts" -o -iname "*.m2ts" -o -iname "*.mpg" -o -iname "*.mpeg" \
  -o -iname "*.3gp" -o -iname "*.hevc" -o -iname "*.ts" \
\)

# Find non-video files
find "$FOLDER" -maxdepth 1 -type f ! \( \
  -iname "*.mp4" -o -iname "*.mov" -o -iname "*.avi" -o -iname "*.mkv" \
  -o -iname "*.m4v" -o -iname "*.wmv" -o -iname "*.flv" -o -iname "*.webm" \
  -o -iname "*.mts" -o -iname "*.m2ts" -o -iname "*.mpg" -o -iname "*.mpeg" \
  -o -iname "*.3gp" -o -iname "*.hevc" -o -iname "*.ts" \
\)

Report to user:

• Total files found
• Number of video files
• Number of non-video files (list them)

---

Step 2: Handle Non-Video Files

Use AskUserQuestion to ask what to do with non-video files (only if any exist):

Question: "Found N non-video file(s). How would you like to handle them?" Options:

• "Move to _misc subfolder (Recommended)" — move non-video files into $FOLDER/_misc/
• "Delete all non-video files" — permanently delete them
• "Leave them as-is" — do nothing

If user chooses to move:

mkdir -p "$FOLDER/_misc"
mv [non-video files] "$FOLDER/_misc/"

If user chooses to delete:

rm [non-video files]

---

Step 3: Remove Short Videos

Use AskUserQuestion to ask about short video threshold:

Question: "Would you like to remove very short videos?" Options:

• "Yes, remove videos shorter than 1 second (default)"
• "Yes, let me specify a duration"
• "No, keep all videos"

If user wants to specify duration, ask them to type the threshold in seconds.

Use ffprobe to check each video's duration:

ffprobe -v quiet -show_entries format=duration -of csv=p=0 "$VIDEO_FILE"

List all videos shorter than the threshold, show their filenames and durations, then confirm deletion:

rm "$SHORT_VIDEO"

---

Step 4: Extract Frames and Analyze Videos with AI Vision

For each remaining video file, extract representative frames using ffmpeg:

# Create temp directory for frames
mkdir -p /tmp/video_frames

# Extract 4 evenly-spaced frames from each video
# (at 10%, 30%, 60%, 90% of duration)
DURATION=$(ffprobe -v quiet -show_entries format=duration -of csv=p=0 "$VIDEO")
ffmpeg -ss $(echo "$DURATION * 0.10" | bc) -i "$VIDEO" -frames:v 1 /tmp/video_frames/"${BASENAME}_01.jpg" -y -loglevel quiet
ffmpeg -ss $(echo "$DURATION * 0.30" | bc) -i "$VIDEO" -frames:v 1 /tmp/video_frames/"${BASENAME}_02.jpg" -y -loglevel quiet
ffmpeg -ss $(echo "$DURATION * 0.60" | bc) -i "$VIDEO" -frames:v 1 /tmp/video_frames/"${BASENAME}_03.jpg" -y -loglevel quiet
ffmpeg -ss $(echo "$DURATION * 0.90" | bc) -i "$VIDEO" -frames:v 1 /tmp/video_frames/"${BASENAME}_04.jpg" -y -loglevel quiet

Also detect bad footage quality:

# Check for all-black frames: compute mean brightness of frame
ffmpeg -i "$VIDEO" -ss $(echo "$DURATION * 0.5" | bc) -frames:v 1 -vf "blackdetect=d=0.1:pix_th=0.10" -f null - 2>&1

# Check for excessive shakiness using scene detection / motion vectors
ffmpeg -i "$VIDEO" -vf "select='gt(scene,0.4)',setpts=N/TB" -frames:v 5 /tmp/video_frames/"${BASENAME}_shake_%02d.jpg" -y -loglevel quiet 2>&1

Use the Read tool to load the extracted frame images, then analyze ALL videos together in one AI analysis pass:

Analyze each video's frames and produce for each video:

1. Category: A short label in the user's language describing the content (e.g., highway driving, city street, nature scenery, indoor footage, interview, sports, aerial, food, live event)
2. Quality issues:
   • all_black: frames are mostly black (>80% black pixels)
   • shaky: excessive camera movement/shake visible
   • blurry: extremely out of focus
   • none: no issues

After analyzing all videos, present a summary table to the user:

Filename            Duration  Category         Quality
video001.mp4        00:32     highway driving  none
video002.mp4        01:15     city street      shaky
video003.mp4        00:08     nature scenery   all black
...

---

Step 5: Handle Bad Quality Videos

If any videos were flagged with quality issues (all_black, shaky, blurry):

Use AskUserQuestion:

Question: "The following videos have quality issues: [list filenames and issue types]. How would you like to handle them?" Options:

• "Delete all problematic videos"
• "Move to _rejected subfolder"
• "Keep them, do nothing"
• "Decide one by one"

If "Decide one by one", for each bad video use AskUserQuestion with options: Delete / Move to _rejected / Keep

Execute the chosen action for each video.

---

Step 6: Classify Videos into Numbered Subfolders

Based on the AI analysis categories, propose a folder structure:

1. Collect all unique categories from the analysis
2. Sort categories by number of videos (most videos first)
3. Assign two-digit numbers: 01_, 02_, etc.

Show the proposed structure to the user (folder names in the user's language):

Proposed folder structure:
01_highway_driving  (12 videos)
02_city_street      (8 videos)
03_nature_scenery   (5 videos)
04_indoor           (3 videos)

Use AskUserQuestion:

Question: "Does the proposed folder structure look good?" Options:

• "Looks good, proceed"
• "I need to rename some categories"
• "I need to merge some categories"

If user wants adjustments, ask them to specify changes (use Other input), then update the plan.

Execute the file moves:

mkdir -p "$FOLDER/01_highway_driving"
mv "$VIDEO" "$FOLDER/01_highway_driving/"

After moving all files, confirm completion and show the final structure:

find "$FOLDER" -type d | sort

---

Step 7: Refine a Category (Optional)

Use AskUserQuestion:

Question: "Would you like to further organize any category folder?" Options:

• "No, all done"
• "Yes, let me choose a category"

If user wants to refine, ask which category folder they want to work on (list the created folders as options).

Then ask:

Question: "How would you like to organize this folder?" Options:

• "Group by time of day (morning / afternoon / evening)"
• "Group by quality (picks / normal)"
• "Group by length (short / long)"
• "Let me describe how"

Execute the requested sub-organization using the same AI analysis data already collected, or re-analyze if needed.

After completing, loop back to Step 7 to ask if any other category needs refinement.

---

Technical Notes

Prerequisites

• ffmpeg and ffprobe must be installed (brew install ffmpeg)
• Use which ffmpeg to verify before starting

Performance Tips

• Process frames extraction in batches to avoid overwhelming the system
• For large folders (>50 videos), inform the user this may take a few minutes
• Clean up temp frames after analysis: rm -rf /tmp/video_frames

Error Handling

• If a video file is corrupted and ffprobe fails, mark it as "unreadable" and ask user separately
• If ffmpeg frame extraction fails, skip that video's frames and note in analysis

Folder Safety

• Never delete files without explicit user confirmation
• Always show what will be deleted/moved before executing
• If unsure, prefer moving to a subfolder over permanent deletion