hermes-skills/stock-search/SKILL.md

---
name: stock-search
description: 'Search the web for downloadable stock materials and auto-upload to TrueNAS. Delegates to the research profile for a 3-move flow: search → evaluate → download+classify+upload. Trigger phrases: "stock search for X", "find stock for X", "download stock for X".'
version: 2.3.0
author: Hermes Agent
metadata:
  hermes:
    tags: [research, search, stock, download, truenas, ai-video]
    related_skills: [better-search, ai-vid-stock, deep-research]
---

# stock-search — Stock Material Search + Download Dispatcher

## §1 Overview

`stock-search` is a dispatcher skill that searches the web for downloadable stock
materials (images, audio, video clips) and auto-uploads them to TrueNAS in the
correct directory. It delegates to the research profile for a 3-move flow:
search → evaluate → download+classify+upload.

**Architecture:** Two-skill contract. This dispatcher is installed on all
profiles and owns trigger detection, optional clarifying questions (max 3), the
dispatch command, and session-id capture. The methodology `stock-search-research`
runs ONLY on the research profile and owns the actual 3-move flow with
download+upload. The dispatcher always delegates to the research profile via
`research -s stock-search-research` — the dispatcher never runs the search itself.

**Trigger phrases:** `stock search for X`, `find stock for X`, `download stock for X`.
These are the ONLY phrases that fire this skill.

## §2 When to Use / When NOT to Use

**TRIGGER RULE (absolute):** If the user says "stock search for X" or "find stock
for X" or "download stock for X", you MUST dispatch. No exceptions.

| Question shape | Tool |
|---|---|
| "Stock search for cyberpunk backgrounds" | `stock-search` (this skill) |
| "Better search for LTX settings" | `better-search` |
| "Deep research on LTX pipeline" | `deep-research` |
| "Upload this file to stock" | `ai-vid-stock` directly |

## §3 Command — RUN THIS EXACTLY

```bash
research -s stock-search-research chat -q "<question> --target <category>" -Q --max-turns 50 --yolo
```

**`research` is a profile alias** (`hermes profile alias research`). Equivalent to
`hermes -p research`.

**Flag rationale:**
- `research` — profile alias, selects the research profile
- `-s stock-search-research` — hardcoded methodology skill
- `-Q` — quiet mode
- `--max-turns 50` — safety net (3-loop cap is the real limit)
- `--yolo` — required for headless one-shot dispatch

**Target categories (UPDATED 2026-07-24 — 12-category taxonomy).** The old
4-bucket taxonomy (`start_frames`, `character_refs`, `audio`, `misc_images`) was
replaced with a 12-category structure matching `~/workspace/stock_plan/` on the
Hermes dispatcher host. Passed in the question string as `--target <category>`:

| `--target` value | What it's for |
|---|---|
| `character_sheets` | Character reference packs — turnarounds, expressions, poses |
| `environments_start_frames` | Location stills used as I2V start frames |
| `end_frames` | Target/last-frame stills for FLF I2V |
| `props_objects` | Isolated prop/object reference images |
| `style_frames` | Mood/style/color-grade reference stills |
| `control_pose_references` | Pose/depth/canny control images |
| `motion_reference_clips` | Short reference clips for motion transfer |
| `storyboard_previs_frames` | Rough sequential previs frames |
| `texture_material_plates` | Texture/material reference plates |
| `audio_stock` | TTS clips, ambient sounds, music |
| `lora_weights_generation_params` | Trained LoRA weights + saved generation params |
| `vehicles_creatures_effects` | Vehicle/creature/VFX element references |

**No silent default anymore.** The old methodology defaulted a missing
`--target` to `misc_images` — that bucket no longer exists. If the user's
request doesn't make the category obvious, you MUST ask (see §4) rather than
guessing or omitting `--target`. Dispatching without a valid `--target` wastes
a full research-profile run because the methodology will reject it (see §2 of
`stock-search-research`).

**Default Quality Rule (enforced on all stock):** Every returned item must be high-quality and suitable for AI video generation in its category. Environments/location plates must be cohesive scene plates (not isolated/random single photos) with consistent lighting, architectural/neon detail, and multi-view potential. Minimum resolution: ≥1920px on the long side (environments_start_frames/end_frames). Photorealistic, no watermarks, no text overlays, no AI artifacts. Suitable as reusable reference plates for consistent character/background locking across multiple scenes.

## §4 Clarifying Questions (Max 3)

Only ask if the target category is ambiguous. Default: 0 questions. Hard cap: 3.

If the user says "stock search for cyberpunk" without specifying a category, ask:
"Which category — character_sheets, environments_start_frames, end_frames,
props_objects, style_frames, control_pose_references, motion_reference_clips,
storyboard_previs_frames, texture_material_plates, audio_stock,
lora_weights_generation_params, or vehicles_creatures_effects?" (Shorten to the
2-3 most plausible categories given the query context rather than reading the
full list verbatim every time — e.g. for "cyberpunk city" the obvious
candidates are `environments_start_frames` or `style_frames`.)

## §5 Delivery

After dispatching:

1. **Capture `session_id`** from the research agent's output.
2. **Report** the session_id and expected TrueNAS paths:
   ```
   session_id: <sid> (reference only — do not --resume)
   Files will land in: ai_vid_stock_material/<category>/ on TrueNAS
   ```
3. **Return control to the operator.** Do NOT poll, do NOT check for results.
   The operator checks TrueNAS when they want to.

The methodology uploads files directly to `//10.0.0.117/proxmoxBackup/ai_vid_stock_material/<category>/`
via smbclient. No intermediate report file — the files on TrueNAS are the deliverable.

## §6 No-Resume Rule

**No `--resume`.** Every follow-up is a fresh dispatch with a new session_id and
new 3-loop budget.

## §7 Common Pitfalls

1. **`--yolo` is required.** Headless one-shot. Without it, approval prompts fail closed.
2. **`--max-turns 50` is the safety net, not the budget.** 3 loops is the cap.
3. **Don't poll, don't check, don't background.** Return control to the operator
   immediately after capturing the session_id.
4. **Max 3 clarifying questions.** Multi-part questions get condensed or split.
5. **No `--resume`.** Every dispatch is independent.
6. **The 3 triggers are the only phrases that fire this skill.** Don't add
   `look for stock` or other variants — they collide with normal agent tasks.
7. **The `-p` flag exists. Do NOT hallucinate that it doesn't.** `hermes -p research`
   is standard. If unsure, run `hermes --help` to verify.
8. **The 12-category taxonomy replaced the old 4-bucket one on 2026-07-24.**
   `start_frames`, `character_refs`, `audio`, `misc_images` are STALE — do not
   use them in `--target`. See the table in §3.

## §8 See Also

- `better-search` — medium-depth research without download (report-only)
- `deep-research` — exhaustive multi-source research with disconfirmation
- `ai-vid-stock` — manual stock management on TrueNAS (list, add, remove)
- `nordvpn` — VPN management (methodology auto-reconnects on search failure)