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: 1.0.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** (passed in the question string as `--target <category>`):
- `start_frames` — first/last frame images for I2V
- `character_refs` — character reference images
- `audio` — TTS clips, ambient sounds, music
- `misc_images` — unsorted images, inspiration
- `all` — let the methodology classify by file type

If no `--target` is specified, the methodology defaults to `misc_images`.

## §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 — start_frames, character_refs, audio, or misc_images?"

## §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 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)