feat: route Sume agent skills for SUM-619

AGENTS.md

@@ -28,3 +28,24 @@ cd web
 pnpm run check
 ```
 
+## Agent Skill Routing
+
+Bundled Sume agent skills live under `agent/`. For Sume API workflow tasks,
+start from the `sume` router skill, then route to focused skills such as
+`sume-tools`, `sume-auth`, `sume-avatar`, `sume-avatar-video`,
+`sume-min-latency`, `sume-quality-experiment`,
+`sume-spend-capped-dogfood`, `sume-media-qa`, or `sume-assets`.
+
+Do not guess public API inputs from memory. Use `sume tools list --json` and
+`sume tools schema <name> --json` before constructing writes. Use
+`sume skills list --json` to discover bundled skill packs and
+`sume skills export <name> --json` to inspect bundled content.
+
+Skills are decision/workflow guides. CLI commands and the current
+`api.sume.com` OpenAPI/schema remain the executable source of truth. MCP tools,
+when enabled, must mirror the same names, safety gates, and redaction rules.
+
+Do not use old `sume.so` Brand, Ads, Face Swap, generic image/video generation,
+private provider, database, Railway, or hidden workflow routes unless they are
+explicitly exposed by the current public `api.sume.com` contract and local tool
+registry.

README.md

@@ -285,11 +285,14 @@ sume skills install sume-assets --json
 ```
 
 The bundled skills are current `api.sume.com` packs: `sume`, `sume-tools`,
-`sume-assets`, `sume-avatar`, and `sume-avatar-video`. They document auth,
+`sume-auth`, `sume-assets`, `sume-avatar`, `sume-avatar-video`,
+`sume-min-latency`, `sume-quality-experiment`,
+`sume-spend-capped-dogfood`, and `sume-media-qa`. They document auth,
 redaction, Avatar 1.0, Avatar Video 1.0, batch planning, jobs, balance, usage,
-schema discovery, and advanced compatibility asset handling. They explicitly exclude
-old `sume.so` Brand, Ads, Face Swap, generic generation, raw provider,
-billing-write, and file workflows.
+schema discovery, minimum-latency iteration, capped paid QA, local media QA, and
+advanced compatibility asset handling. They explicitly exclude old `sume.so`
+Brand, Ads, Face Swap, generic generation, raw provider, billing-write, and file
+workflows.
 
 ## MCP
 

agent/sume-assets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sume-assets
-description: Use advanced compatibility Sume.com asset tools for approved internal/agent workflows; launch Avatar and Avatar Video inputs should use stable public HTTPS URLs directly.
+description: Use advanced compatibility Sume asset upload/download helpers only when explicitly requested; launch Avatar and Avatar Video inputs should use stable public HTTPS URLs directly.
 ---
 
 # Sume Assets
@@ -54,4 +54,6 @@ Read `references/media-workflows.md` for details.
 Do not use assets as the default launch upload path, and do not pass asset ids
 into generation requests unless the current OpenAPI schema explicitly accepts
 them. Do not use old Asset Library scene search or `uploads/presign`; those are
-`sume.so`-only unless the current public catalog exposes them.
+`sume.so`-only unless the current public catalog exposes them. Do not use this
+skill for paid generation; route Avatar work to `sume-avatar`, Avatar Video work
+to `sume-avatar-video`, and local comparison work to `sume-media-qa`.

agent/sume-auth/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: sume-auth
+description: Set up and verify Sume CLI authentication safely, including browser login, API-key readiness, doctor checks, and headless-terminal caveats without exposing secrets.
+---
+
+# Sume Auth
+
+Use this skill for local CLI readiness, login, and API-key configuration.
+
+## Discover
+
+```bash
+sume --version
+sume auth status --json
+sume doctor --agent --json
+```
+
+## Local Browser Login
+
+Use browser login only when the browser is on the same machine as the CLI
+process:
+
+```bash
+sume login
+sume auth status --json
+```
+
+## Headless Or Remote Terminals
+
+In remote/headless terminals, avoid long foreground login waiters because
+approval URLs/codes can be hidden until timeout or retained in logs. Use the
+short-lived process-log pattern in `sume/references/safety.md`, surface the
+approval URL/code only to the requesting user, and delete logs after approval.
+
+## API Keys
+
+Prefer approved local config or environment variables. Do not ask the user to
+paste API keys into chat unless they explicitly choose manual key setup.
+
+## Not For
+
+Do not run paid generation, uploads, downloads, MCP setup, or production
+infrastructure work from this skill. Do not print auth URLs/codes, API keys, or
+local config contents in final reports, issues, PRs, or persistent logs.

agent/sume-avatar-video/SKILL.md

@@ -1,17 +1,20 @@
 ---
 name: sume-avatar-video
-description: Create, batch-plan, watch, and inspect Sume Avatar Video 1.0 resources from selected avatars with metadata-aware readback and safe paid gates.
+description: Create, batch-plan, watch, and inspect Sume Avatar Video 1.0 jobs from selected avatar handles, including productless/product-image flows, metadata readback, and paid gates.
 ---
 
 # Sume Avatar Video
 
 Use this skill after a ready avatar is selected.
+Use `sume tools schema avatar-videos.create --json` before constructing writes;
+do not copy request schemas from memory.
 
 ## Discover
 
 ```bash
 sume tools schema avatar-videos.create --json
 sume tools schema avatar-videos.get --json
+sume tools schema avatar-videos.batch.plan --json
 sume tools schema jobs.result --json
 ```
 
@@ -53,9 +56,12 @@ sume avatar-videos batch result ./avatar-videos.json --state-file ./avatar-video
 ```
 
 Read `references/avatar-video-batch-manifest.md` for manifest shape.
+Rerunning batch create with the same state file must not duplicate already
+submitted paid jobs.
 
 ## Not For
 
 Do not route generic video generation, Ads, UGC Ads, Face Swap, or raw provider
 model ids through this skill unless they are added to the current public
-`api.sume.com` catalog.
+`api.sume.com` catalog. Do not use this skill for local media inspection only;
+use `sume-media-qa` when no paid generation is needed.

agent/sume-avatar/SKILL.md

@@ -1,17 +1,20 @@
 ---
 name: sume-avatar
-description: Create, inspect, batch-plan, and select Sume Avatar 1.0 resources with safe paid gates and agent-redacted readback.
+description: Create, batch-plan, watch, inspect, and select current Sume Avatar 1.0 resources by avatar_handle with safe paid gates and agent-redacted readback.
 ---
 
 # Sume Avatar
 
 Use this skill for Avatar 1.0 creation and selection.
+Use `sume tools schema avatars.create --json` before constructing writes; do
+not copy request schemas from memory.
 
 ## Discover
 
 ```bash
 sume tools schema avatars.create --json
 sume tools schema avatars.list --json
+sume tools schema avatars.batch.plan --json
 sume tools schema jobs.watch --json
 ```
 
@@ -52,6 +55,9 @@ sume avatars batch result ./avatars.json --state-file ./avatars.state.json --jso
 
 Use ready avatar handles with `sume-avatar-video`.
 
+Rerunning batch create with the same state file must not duplicate already
+submitted paid jobs.
+
 ## Selection
 
 ```bash
@@ -62,3 +68,10 @@ sume avatars get <avatar_id> --agent --json
 
 Summarize name, status, creation style, artifacts count, and any taste-relevant
 metadata. Do not paste raw media URLs.
+
+## Not For
+
+Do not use this skill for Avatar Video generation, generic image/video
+generation, old `sume.so` Brand/Ads/Face Swap workflows, raw provider models,
+or paid QA experiments. Use `sume-avatar-video`, `sume-quality-experiment`, or
+`sume-spend-capped-dogfood` as appropriate.

agent/sume-media-qa/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: sume-media-qa
+description: Inspect and compare Sume media outputs locally with no provider calls, using duration/codec checks, still sheets, side-by-side comparisons, and artifact notes.
+---
+
+# Sume Media QA
+
+Use this skill to inspect existing Sume outputs without submitting new paid
+generation jobs.
+
+## Get Files Only When Needed
+
+```bash
+sume jobs result <job_id> --agent --json
+sume jobs download <job_id> --output-dir ./sume-outputs --json
+```
+
+Use explicit output directories. Final reports should mention local filenames,
+counts, dimensions, duration, and issues, not full media URLs.
+
+## Local Checks
+
+Use local tools when available:
+
+```bash
+ffprobe -v error -show_format -show_streams ./sume-outputs/video.mp4
+```
+
+Check:
+
+- duration and aspect ratio;
+- codec/container compatibility;
+- audio presence and sync;
+- obvious visual artifacts;
+- product/identity continuity;
+- whether a side-by-side comparison or still sheet is needed.
+
+## Report
+
+Return a compact QA note with files inspected, pass/fail observations, and
+recommended next action. Keep provider internals and full URLs out of the
+report.
+
+## Not For
+
+Do not create Avatar or Avatar Video jobs from this skill. Use
+`sume-avatar-video`, `sume-min-latency`, `sume-quality-experiment`, or
+`sume-spend-capped-dogfood` when paid generation is needed.

agent/sume-min-latency/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: sume-min-latency
+description: Run the fastest safe Sume Avatar/Avatar Video iteration loop using async submits, batch state files, parallel polling, deferred downloads, and explicit quality/cost tradeoffs.
+---
+
+# Sume Minimum Latency
+
+Use this skill when the user wants the fastest useful Sume result while still
+respecting paid gates and avoiding duplicate jobs.
+
+## Rules
+
+1. Run readiness only if local state is unknown:
+
+   ```bash
+   sume doctor --agent --json
+   ```
+
+2. Use schema discovery only for the write you are about to make:
+
+   ```bash
+   sume tools schema avatars.create --json
+   sume tools schema avatar-videos.create --json
+   ```
+
+3. Prefer async submit plus watch/result over blocking waits.
+4. For multiple independent candidates, draft a manifest and use batch
+   plan/create/watch/result with a persistent state file.
+5. Use stable idempotency keys. Reruns must skip already-created jobs.
+6. Do not download media unless local comparison is required or the user asks.
+7. If the user prioritizes speed/cost, explicitly choose `quality=standard`;
+   otherwise preserve the platform default quality.
+
+## Fast Avatar Video Loop
+
+```bash
+sume avatar-videos create \
+  --avatar-handle <ready_avatar_handle> \
+  --script "Short reviewed script." \
+  --quality standard \
+  --confirm-paid \
+  --agent \
+  --json
+
+sume jobs watch <job_id> --agent --json
+sume jobs result <job_id> --agent --json
+```
+
+## Report
+
+Report job id, resource id, requested quality, wall-clock time if measured,
+queue/run state, captured/refunded cost when available, and sanitized result
+availability. Do not paste full media URLs.
+
+## Not For
+
+Do not use this skill for broad quality exploration or side-by-side evaluation;
+use `sume-quality-experiment`. Do not use it to bypass spend caps, paid
+approval, idempotency, or state files.

agent/sume-quality-experiment/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: sume-quality-experiment
+description: Design and run controlled Sume quality experiments with one-variable variants, reusable manifests, side-by-side artifact comparison, and rubric-based sanitized reports.
+---
+
+# Sume Quality Experiment
+
+Use this skill for controlled Avatar or Avatar Video comparisons.
+
+## Experiment Rules
+
+1. Write a short local manifest before paid calls.
+2. Change one variable per variant: quality tier, scene prompt, product image,
+   avatar handle, script, duration, or aspect ratio.
+3. Keep shared anchors identical across variants.
+4. Run no-cost checks first: schema discovery, manifest validation, and local
+   media inspection when outputs already exist.
+5. Ask for explicit paid approval and a spend cap before paid generation.
+6. Use idempotency keys and state files so reruns do not duplicate jobs.
+
+## Commands
+
+```bash
+sume tools schema avatar-videos.create --json
+sume avatar-videos batch plan ./experiment.videos.json --output-file ./experiment.plan.json --json
+sume avatar-videos batch create ./experiment.videos.json --state-file ./experiment.state.json --confirm-paid --json
+sume avatar-videos batch watch ./experiment.videos.json --state-file ./experiment.state.json --json
+sume avatar-videos batch result ./experiment.videos.json --state-file ./experiment.state.json --json
+```
+
+Use `sume-media-qa` after results exist if the user needs local files, still
+sheets, codec checks, or side-by-side comparison.
+
+## Rubric
+
+Score or summarize:
+
+- identity preservation;
+- product fidelity;
+- script/audio fit;
+- scene continuity;
+- artifact severity;
+- metadata/readback usefulness;
+- cost and elapsed time.
+
+## Not For
+
+Do not use this skill for unrestricted exploration, raw provider endpoint
+tests, or one-off fastest iteration. Use `sume-min-latency` for speed and
+`sume-spend-capped-dogfood` for paid QA with a strict budget.