v-modal/vmodal_mcp / skills/vmodal-find
vmodal-find
VerifiedFind moments in VModal video collections and verify every detail of the query on the actual frames before reporting a match. Use when the user asks to find, search, locate or show something (an object, scene, person, place, "a beautiful shot") in a VModal collection or sub-collection, e.g. "Find a red car. Collection: city" or "a beautiful scene in Kyoto". Requires the vmodal MCP (dev branch, with the `find` tool).
vmodal-find
Search a VModal collection, group near-duplicate hits into scenes, look at a frame from each scene, and check every detail of the query on it. A search score is a similarity rank, not proof: never report a match you have not looked at.
Tool details, timestamp math and a worked example are in reference.md.
<skill_dir> below means the folder this SKILL.md is in.
1. Parse the request
- Collection (required). If missing or unclear, call
collection_listand ask. - Sub-collection (optional). A place or source name in the query ("in Kyoto",
"Rome") may be a sub-collection. Call
collection_subcollections_list(collection_name=...)and use an exact listed name only. If nothing matches, search all sub-collections and keep the place as a context spec. - Query: what to find.
2. Build the spec checklist
Split the query into atomic specs and tag each one:
| Tag | Meaning | Example | Rule |
|---|---|---|---|
| core | the subject itself | car, taxi, lantern | must pass |
| attribute | color, state, count, action | red, parked, two, driving | must pass |
| context | setting, time of day, nearby thing | at night, near a shrine, FamilyMart | must pass |
| subjective | taste words | beautiful, best, nice | judged, never a hard fail |
| unverifiable | can't be seen in a still frame | someone says X, music, smell | reported, never guessed |
- Keep specs small: "red taxi with a white roof" →
red·taxi·white roof. - For subjective specs, judge on stated criteria: lighting, composition, a clear view of the subject, nothing blocking it (people, poles), no burned-in subtitles.
- Search is image-only (
search_sourcesis fixed to["image"]), so speech and audio specs are always unverifiable. On-screen text can be read off the frame if visible.
Show the checklist to the user in one line before searching, e.g.
Checking: red (attribute) · taxi (core) · parked (attribute) · night (context).
3. Search for recall
Run two find calls (in parallel), both with the same collection and sub-collection:
- the full query,
limit=20 - the core spec alone (e.g. "a taxi"),
limit=20
The MCP returns at most 20 rows per call, whatever limit says. Also fetch the full
query's next page (offset=20) in the same parallel batch; when widening (step 8),
fetch further pages (offset=40, 60, …) as needed.
Do not pass version_id or mode; find picks a working index (newest first, falling back to an older one; the result reports version_lancedb). Do not use
save_images here (it saves top hits, which are mostly duplicates of one scene).
Merge the two result lists: full-query hits first in their returned order, then
core-only hits not already present. De-duplicate on (stream_name, filename,
ts_unix_13digits). Use the returned order as the rank; don't reason about what the
score number means.
4. Group hits into scenes
Hits with the same stream_name + filename whose timestamps are within 3 s of the
previous hit in that group form one scene. Frames are sampled about once a second, so a
car passing by usually yields 5–10 hits.
For each scene keep: video, sub-collection, time range (first–last hit), the best-ranked hit as its representative frame, and the hit count. Rank scenes by their best hit's rank.
5. Verify the top 8 scenes
image_get_url_bulk(records=[...representative hits...]). Search rows can be passed as-is.image_get_bulk_from_urls(urls=[...url_pre_signed...], collection_name=...).- Convert the saved frames for viewing:
bash <skill_dir>/scripts/frames_to_png.sh ${TMPDIR:-/tmp}/vmodal-find/<collection> <saved_path>...It prints one PNG path per input (orFAIL <path>). Saved paths may be relative to the MCP server's working directory, which is the folder Claude Code was started in. The script looks in$VMODAL_MCP_CWD, the current directory, then$HOME, so run it from that folder (shell working directories can reset between calls) or prefix the call withVMODAL_MCP_CWD=<that folder>. Don't browseztmp/yourself. - Read each PNG and mark every spec pass, fail or unclear, with a few words of visual evidence ("white roof visible", "sky dark, street lights on").
Be strict. Dusk is not night. Maroon is not red unless the user would call it red.
A car partly cut off by the frame edge still passes car, but its color may be unclear.
6. Second look
For a scene that is PARTIAL only because of unclear specs (blocked, blurred,
cut off, too small), fetch one more frame from inside its time range, preferably a
different hit from the scene, and re-check. Keep the better result. Don't re-look at
scenes with a clear fail.
7. Verdict
- PASS: every core, attribute and context spec is
pass. - PARTIAL: core passes; at least one attribute or context spec is
failorunclear. - FAIL: a core spec fails.
Subjective specs never change the verdict; use them to order PASS scenes (best first). Unverifiable specs never change the verdict; list them in the footer.
8. Widen if needed
If fewer than 3 scenes PASS, verify the next 8 scenes. Stop after 24 scenes viewed in total, or when the scenes run out. If nothing passes, say so plainly: "No verified match" is a correct answer. Don't relax the specs without telling the user.
9. Report
**Checking:** red · taxi · parked · night
### Verified matches
| # | Video | Sub-collection | Time (best / range) | Checks | Frame |
|---|---|---|---|---|---|
| 1 | Exploring Downtown Kyoto… | Street_Visit_in_Kyoto | 1:57 (1:54–1:58) | red ✓ taxi ✓ parked ✓ night ✓ | /abs/path/frame.png |
### Close, but not matching
| # | Video | Sub-collection | Time (best / range) | Checks | Missed | Frame |
|---|---|---|---|---|---|---|
Viewed 8 scenes: 1 pass, 2 partial, 5 fail. Not verifiable: none. Index version: v0.
- Video titles: replace
_with spaces and shorten long ones. - Times use
m:ss(orh:mm:ss); see reference.md for live-stream timestamps. - Frame paths are absolute PNG paths so the user can open them.
- Give a one-sentence description of what is in each PASS frame under the table.
- Leave a table out if it is empty, but always keep the footer line.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |