From 1e70215a4d8bc8a1017ad3bffaffe8fadaf73786 Mon Sep 17 00:00:00 2001 From: chaewon-huh Date: Mon, 6 Jul 2026 13:37:28 +0900 Subject: [PATCH] feat: route Sume agent skills for SUM-619 --- AGENTS.md | 21 ++++++++ README.md | 11 ++-- agent/sume-assets/SKILL.md | 6 ++- agent/sume-auth/SKILL.md | 44 ++++++++++++++++ agent/sume-avatar-video/SKILL.md | 10 +++- agent/sume-avatar/SKILL.md | 15 +++++- agent/sume-media-qa/SKILL.md | 48 ++++++++++++++++++ agent/sume-min-latency/SKILL.md | 59 ++++++++++++++++++++++ agent/sume-quality-experiment/SKILL.md | 50 ++++++++++++++++++ agent/sume-spend-capped-dogfood/SKILL.md | 64 ++++++++++++++++++++++++ agent/sume-tools/SKILL.md | 18 +++++-- agent/sume/SKILL.md | 60 +++++++++++++++------- docs/agent-skills.md | 16 +++++- docs/agent-workflows.md | 3 ++ docs/architecture.md | 8 +-- src/lib/bundled-skills-data.ts | 35 +++++++++---- test/cli.test.ts | 12 +++++ test/skills-registry.test.ts | 44 ++++++++++++++++ 18 files changed, 477 insertions(+), 47 deletions(-) create mode 100644 agent/sume-auth/SKILL.md create mode 100644 agent/sume-media-qa/SKILL.md create mode 100644 agent/sume-min-latency/SKILL.md create mode 100644 agent/sume-quality-experiment/SKILL.md create mode 100644 agent/sume-spend-capped-dogfood/SKILL.md diff --git a/AGENTS.md b/AGENTS.md index b3d0086..cc56fd4 100644 --- a/AGENTS.md +++ b/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 --json` before constructing writes. Use +`sume skills list --json` to discover bundled skill packs and +`sume skills export --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. diff --git a/README.md b/README.md index 19100d3..5a7b133 100644 --- a/README.md +++ b/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 diff --git a/agent/sume-assets/SKILL.md b/agent/sume-assets/SKILL.md index 352a9da..3e96310 100644 --- a/agent/sume-assets/SKILL.md +++ b/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`. diff --git a/agent/sume-auth/SKILL.md b/agent/sume-auth/SKILL.md new file mode 100644 index 0000000..d6d2c1d --- /dev/null +++ b/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. diff --git a/agent/sume-avatar-video/SKILL.md b/agent/sume-avatar-video/SKILL.md index 3ab5de2..96fc8bd 100644 --- a/agent/sume-avatar-video/SKILL.md +++ b/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. diff --git a/agent/sume-avatar/SKILL.md b/agent/sume-avatar/SKILL.md index 4ff5588..43f96ab 100644 --- a/agent/sume-avatar/SKILL.md +++ b/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 --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. diff --git a/agent/sume-media-qa/SKILL.md b/agent/sume-media-qa/SKILL.md new file mode 100644 index 0000000..99f366e --- /dev/null +++ b/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 --agent --json +sume jobs download --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. diff --git a/agent/sume-min-latency/SKILL.md b/agent/sume-min-latency/SKILL.md new file mode 100644 index 0000000..b6d496f --- /dev/null +++ b/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 \ + --script "Short reviewed script." \ + --quality standard \ + --confirm-paid \ + --agent \ + --json + +sume jobs watch --agent --json +sume jobs result --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. diff --git a/agent/sume-quality-experiment/SKILL.md b/agent/sume-quality-experiment/SKILL.md new file mode 100644 index 0000000..358db35 --- /dev/null +++ b/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. diff --git a/agent/sume-spend-capped-dogfood/SKILL.md b/agent/sume-spend-capped-dogfood/SKILL.md new file mode 100644 index 0000000..bdc2d1a --- /dev/null +++ b/agent/sume-spend-capped-dogfood/SKILL.md @@ -0,0 +1,64 @@ +--- +name: sume-spend-capped-dogfood +description: Run paid Sume dogfood QA under an explicit USD cap using idempotency, max_spend_usd where available, cost readback, and no duplicate paid submissions. +--- + +# Sume Spend-Capped Dogfood + +Use this skill when the user authorizes paid Sume QA with a hard budget. + +## Required Before Paid Calls + +- Confirm the exact USD cap. +- Identify the minimum number of jobs needed for evidence. +- Prefer dry-run/admission preview or estimate if exposed by the current tool + schema. +- Use stable idempotency keys. +- Use batch state files for more than one job. +- Stop once the evidence is sufficient. + +If a future release enables MCP paid tools, `idempotency_key` and +`max_spend_usd` are mandatory. For current CLI commands, record the approved cap +in the manifest/report and pass idempotency keys where supported. + +## Commands + +```bash +sume doctor --agent --json +sume balance --json +sume tools schema avatar-videos.create --json +``` + +Single-job example after explicit approval: + +```bash +sume avatar-videos create \ + --avatar-handle \ + --script "Short QA script." \ + --quality standard \ + --idempotency-key \ + --confirm-paid \ + --agent \ + --json +``` + +Then: + +```bash +sume jobs watch --agent --json +sume jobs result --agent --json +sume balance --json +``` + +## Report + +Report requested quality, job id, resource id, expected/reserved/captured/ +refunded cost when available, status/result, and whether the cap was respected. +If exact cost telemetry is missing, state that as a product gap instead of +inferring a billing guarantee. + +## Not For + +Do not use this skill without an explicit cap. Do not keep spending for broad +exploration. Do not print secrets, full URLs, signed URLs, provider payloads, or +private identifiers. diff --git a/agent/sume-tools/SKILL.md b/agent/sume-tools/SKILL.md index 8a419be..1192ca1 100644 --- a/agent/sume-tools/SKILL.md +++ b/agent/sume-tools/SKILL.md @@ -1,12 +1,15 @@ --- name: sume-tools -description: Discover Sume.com CLI tool schemas, install or export bundled Sume skills, inspect balance/usage, and choose safe public-api workflows. +description: Discover current Sume CLI tool schemas, inspect bundled skills, check readiness, and choose safe CLI/MCP workflows without executing paid generation. --- # Sume Tools Use this skill for schema discovery and local skill maintenance. +Do not construct write or paid payloads from memory. Use the local tool registry +as the executable contract. + ## Discovery ```bash @@ -14,6 +17,7 @@ sume doctor --agent --json sume tools list --json sume tools schema avatars.create --json sume tools schema avatar-videos.create --json +sume tools schema jobs.watch --json sume balance --json sume usage get --json ``` @@ -22,6 +26,7 @@ sume usage get --json ```bash sume skills list --json +sume skills export sume --json sume skills install sume --json sume skills install sume-avatar --json sume skills update --json @@ -35,9 +40,14 @@ Skills install into `.agents/skills/` when `.agents/` exists, otherwise Sume MCP is coming soon and is not part of this public CLI launch release yet. Use direct CLI commands today. +If a future release enables MCP, treat MCP tool descriptions and +`sume tools schema` safety metadata as the source of truth for toolsets, write +gates, paid gates, and redaction behavior. + ## Not For Do not execute paid creation directly from this skill. Route avatar work to -`sume-avatar` and video work to `sume-avatar-video`. Route media inputs through -public HTTPS URLs unless the user explicitly asks for advanced compatibility -asset tooling. +`sume-avatar`, video work to `sume-avatar-video`, spend-capped QA to +`sume-spend-capped-dogfood`, local artifact checks to `sume-media-qa`, and fast +iteration to `sume-min-latency`. Route media inputs through public HTTPS URLs +unless the user explicitly asks for advanced compatibility asset tooling. diff --git a/agent/sume/SKILL.md b/agent/sume/SKILL.md index 86eecf9..72a3679 100644 --- a/agent/sume/SKILL.md +++ b/agent/sume/SKILL.md @@ -1,35 +1,50 @@ --- name: sume -description: Use the Sume.com CLI safely for auth, API discovery, avatars, avatar videos, jobs, balance, usage, and choosing focused Sume skills. Use this as the entry skill for current api.sume.com workflows. +description: Router for current Sume.com public API workflows. Use for auth, schema discovery, Avatar 1.0, Avatar Video 1.0, jobs, spend-capped dogfooding, minimum-latency generation loops, media QA, and selecting focused Sume skills. --- # Sume Skill Router -Sume CLI is a thin wrapper over the current `api.sume.com` public API. It must -not call Sume databases, internal routes, provider APIs, or old `sume.so`-only -surfaces. +Start here for Sume agent work. The executable source of truth is the `sume` +CLI over current `api.sume.com`; this skill chooses the safest workflow and +points agents to focused skills. + +Sume CLI must remain a thin wrapper over public API boundaries. Do not call +Sume databases, internal app routes, Railway services, provider APIs, or old +`sume.so`-only surfaces. ## Core Rules -1. Use `sume tools list --json` and `sume tools schema --json` before - constructing writes. -2. Use `--agent --json` whenever automation reads jobs, avatars, or - avatar videos. -3. Ask for explicit approval before `--confirm-submit` or `--confirm-paid`. -4. Do not print API keys, auth approval URLs/codes in final reports, signed +1. Run readiness checks when the local state is unknown. +2. Use `sume tools list --json` and `sume tools schema --json` before + constructing any write or paid request. +3. Use `sume skills list --json` and `sume skills export --json` to + discover bundled skill content instead of guessing. +4. Use `--agent --json` whenever automation reads jobs, avatars, or avatar + videos. +5. Ask for explicit approval before `--confirm-submit` or `--confirm-paid`. +6. Paid work must use idempotency and a spend cap where the command/tool + supports it. +7. Do not print API keys, auth approval URLs/codes in final reports, signed URLs, private media URLs, storage object keys, raw provider identifiers, workspace/user ids, or full result URLs. -5. Use current public launch API surfaces only: account, catalog, balance, +8. Use current public launch API surfaces only: account, catalog, balance, usage, jobs, Avatar 1.0, and Avatar Video 1.0. -## Setup +## First Checks ```bash sume --version -sume auth status --json sume doctor --agent --json +sume tools list --json +sume skills list --json ``` +Use `sume tools schema --json` before constructing writes. Do not copy +request schemas from memory or from stale docs. + +## Auth + Use browser login when the browser is local: ```bash @@ -42,16 +57,23 @@ the exact pattern. ## Routing -- Use `sume-tools` for schema discovery and skill maintenance. -- Use `sume-avatar` for creating several avatars and choosing a ready avatar. -- Use `sume-avatar-video` for making videos from selected avatars and reading - metadata/result state. -- Use `sume-assets` only for explicitly requested advanced compatibility asset - workflows; launch generation inputs should be stable public HTTPS URLs. +| User intent | Use skill | First command | +| --- | --- | --- | +| Schema, tool list, MCP status, skill setup | `sume-tools` | `sume tools list --json` | +| Login, API key, local readiness | `sume-auth` | `sume auth status --json` | +| Create or choose avatars | `sume-avatar` | `sume tools schema avatars.create --json` | +| Generate videos from ready avatars | `sume-avatar-video` | `sume tools schema avatar-videos.create --json` | +| Fastest safe iteration loop | `sume-min-latency` | local manifest/state file, then async create/watch/result | +| Controlled quality comparisons | `sume-quality-experiment` | variant manifest, then schema check before paid calls | +| Paid QA under an explicit cap | `sume-spend-capped-dogfood` | estimate/admission check if available, then idempotent capped submit | +| Local result inspection/comparison | `sume-media-qa` | `sume jobs download --output-dir --json` | +| Advanced compatibility assets | `sume-assets` | `sume tools schema assets.upload_url --json` | Read `references/safety.md` for auth, paid/write gates, and redaction rules. Read `references/eval-scenarios.md` when validating agent behavior. +## MCP State + Sume MCP is coming soon and is not part of this public CLI launch release yet. Use direct CLI commands today. diff --git a/docs/agent-skills.md b/docs/agent-skills.md index 994aa3e..7301f5d 100644 --- a/docs/agent-skills.md +++ b/docs/agent-skills.md @@ -17,13 +17,25 @@ directories first so the CLI does not guess where an agent should read skills. Bundled skills: -- `sume`: router, auth, safety, redaction, eval scenarios. -- `sume-tools`: schema discovery, balance/usage, skill maintenance. +- `sume`: router, safety, redaction, eval scenarios, and focused skill + selection. +- `sume-tools`: schema discovery, balance/usage, skill maintenance, and MCP + launch-state guidance. +- `sume-auth`: login, auth status, API-key readiness, and headless-terminal + caveats. - `sume-assets`: advanced compatibility asset registration/upload/download helpers; not the default launch media-input path. - `sume-avatar`: Avatar 1.0 prompt/photo/props creation and batch planning. - `sume-avatar-video`: selected-avatar video creation, batch planning, and metadata-aware readback. +- `sume-min-latency`: fastest safe Avatar/Avatar Video iteration loop with + async jobs, state files, and deferred downloads. +- `sume-quality-experiment`: controlled variant experiments with one variable + changed at a time and rubric-based reports. +- `sume-spend-capped-dogfood`: paid QA under an explicit USD cap with + idempotency and cost readback. +- `sume-media-qa`: local media inspection and comparison without provider + calls. Safe setup: diff --git a/docs/agent-workflows.md b/docs/agent-workflows.md index 5a8da41..315cbde 100644 --- a/docs/agent-workflows.md +++ b/docs/agent-workflows.md @@ -5,6 +5,9 @@ generic image/video generation, raw provider models, brand, ads, UGC, billing writes, or file surfaces until those routes exist in the public OpenAPI/catalog. Use this sequence for current Avatar 1.0 and Avatar Video 1.0 prompts. +For installed agent skill routing, start from `sume`, then use focused skills +such as `sume-avatar`, `sume-avatar-video`, `sume-min-latency`, +`sume-quality-experiment`, `sume-spend-capped-dogfood`, or `sume-media-qa`. ## Readiness diff --git a/docs/architecture.md b/docs/architecture.md index 4ba3f58..f127eb8 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -126,9 +126,11 @@ current command contracts without treating MCP as launched. Bundled agent skill packs live under `agent/` and ship with the npm/package artifact. `src/lib/skills-registry.ts` lists, exports, installs, updates, and removes those local packs for `.agents/skills` or `.claude/skills` projects. -The packs are limited to current `api.sume.com` workflows and exclude old -`sume.so`-only Brand, Ads, Face Swap, generic generation, raw provider, -billing-write, and file surfaces. +Agents should start with the `sume` router skill, then route to focused skills +for tools/auth/avatar/avatar-video/latency/quality/spend-capped QA/media QA or +advanced compatibility assets. The packs are limited to current `api.sume.com` +workflows and exclude old `sume.so`-only Brand, Ads, Face Swap, generic +generation, raw provider, billing-write, and file surfaces. ## Website diff --git a/src/lib/bundled-skills-data.ts b/src/lib/bundled-skills-data.ts index 623810f..d861c1a 100644 --- a/src/lib/bundled-skills-data.ts +++ b/src/lib/bundled-skills-data.ts @@ -1,23 +1,38 @@ export const bundledSkillFiles = { "sume": { + "SKILL.md": "---\nname: sume\ndescription: Router for current Sume.com public API workflows. Use for auth, schema discovery, Avatar 1.0, Avatar Video 1.0, jobs, spend-capped dogfooding, minimum-latency generation loops, media QA, and selecting focused Sume skills.\n---\n\n# Sume Skill Router\n\nStart here for Sume agent work. The executable source of truth is the `sume`\nCLI over current `api.sume.com`; this skill chooses the safest workflow and\npoints agents to focused skills.\n\nSume CLI must remain a thin wrapper over public API boundaries. Do not call\nSume databases, internal app routes, Railway services, provider APIs, or old\n`sume.so`-only surfaces.\n\n## Core Rules\n\n1. Run readiness checks when the local state is unknown.\n2. Use `sume tools list --json` and `sume tools schema --json` before\n constructing any write or paid request.\n3. Use `sume skills list --json` and `sume skills export --json` to\n discover bundled skill content instead of guessing.\n4. Use `--agent --json` whenever automation reads jobs, avatars, or avatar\n videos.\n5. Ask for explicit approval before `--confirm-submit` or `--confirm-paid`.\n6. Paid work must use idempotency and a spend cap where the command/tool\n supports it.\n7. Do not print API keys, auth approval URLs/codes in final reports, signed\n URLs, private media URLs, storage object keys, raw provider identifiers,\n workspace/user ids, or full result URLs.\n8. Use current public launch API surfaces only: account, catalog, balance,\n usage, jobs, Avatar 1.0, and Avatar Video 1.0.\n\n## First Checks\n\n```bash\nsume --version\nsume doctor --agent --json\nsume tools list --json\nsume skills list --json\n```\n\nUse `sume tools schema --json` before constructing writes. Do not copy\nrequest schemas from memory or from stale docs.\n\n## Auth\n\nUse browser login when the browser is local:\n\n```bash\nsume login\n```\n\nFor remote/headless terminals, use a short-lived background login process and\nshow the URL/code only to the requesting user. See `references/safety.md` for\nthe exact pattern.\n\n## Routing\n\n| User intent | Use skill | First command |\n| --- | --- | --- |\n| Schema, tool list, MCP status, skill setup | `sume-tools` | `sume tools list --json` |\n| Login, API key, local readiness | `sume-auth` | `sume auth status --json` |\n| Create or choose avatars | `sume-avatar` | `sume tools schema avatars.create --json` |\n| Generate videos from ready avatars | `sume-avatar-video` | `sume tools schema avatar-videos.create --json` |\n| Fastest safe iteration loop | `sume-min-latency` | local manifest/state file, then async create/watch/result |\n| Controlled quality comparisons | `sume-quality-experiment` | variant manifest, then schema check before paid calls |\n| Paid QA under an explicit cap | `sume-spend-capped-dogfood` | estimate/admission check if available, then idempotent capped submit |\n| Local result inspection/comparison | `sume-media-qa` | `sume jobs download --output-dir --json` |\n| Advanced compatibility assets | `sume-assets` | `sume tools schema assets.upload_url --json` |\n\nRead `references/safety.md` for auth, paid/write gates, and redaction rules.\nRead `references/eval-scenarios.md` when validating agent behavior.\n\n## MCP State\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today.\n\n## Not For\n\nDo not use old `sume.so` Brand, Ads, Face Swap, generic image/video generation,\nraw provider model, billing-write, file, or asset-search workflows unless they\nappear in the current public `api.sume.com` catalog and tool schemas.\n", "references/eval-scenarios.md": "# Sume Agent Eval Scenarios\n\nUse these scenarios to QA skill routing and safety behavior.\n\n1. Missing auth: agent runs `sume doctor --agent --json`, sees missing auth, and\n asks for login/API-key setup without printing secrets in the final report.\n2. Create several avatars: agent drafts a local avatar batch plan, asks for paid\n approval, submits with idempotency keys, then watches jobs.\n3. Choose an avatar: agent lists ready avatars with `--agent --json`, compares\n names/status/artifacts, and asks the user to choose by taste.\n4. Selected avatar to video: agent uses the chosen ready avatar handle\n with `sume avatar-videos create --confirm-paid --agent --json`, then watches\n and reads result.\n5. Metadata/readback: agent calls `sume avatar-videos get` and\n `sume jobs result --agent --json`, summarizes status, scenes/tags/summary if\n present, and does not paste full URLs.\n6. Paid gate: agent refuses to submit Avatar or Avatar Video jobs until the user\n explicitly authorizes paid generation work.\n", - "references/safety.md": "# Sume Safety Reference\n\n## Auth\n\n- Prefer `sume login` only when the browser is on the same machine.\n- In remote/headless terminals, avoid a long foreground login waiter because\n intermediate auth URLs/codes can be hidden until timeout or persisted in logs.\n- Use a short-lived process log:\n\n```bash\nlogin_log=\"$(mktemp -t sume-login.XXXXXX.log)\"\n(sume login --no-browser --timeout 600 >\"$login_log\" 2>&1; echo $? >\"$login_log.status\") &\nlogin_pid=$!\nsleep 4\nsed -n '1,80p' \"$login_log\"\n```\n\nAfter user approval:\n\n```bash\nwait \"$login_pid\"\nsume auth status --json\nrm -f \"$login_log\" \"$login_log.status\"\n```\n\n## Gates\n\n- `--confirm-submit`: non-paid writes such as asset registration, upload\n completion, and job cancellation.\n- `--confirm-paid`: paid generation submits such as Avatar 1.0 and Avatar Video\n 1.0 creation.\n\n## Sensitive Outputs\n\nNever echo API keys, approval codes, signed upload/download URLs, private media\nURLs, storage object keys, raw auth headers, provider ids, workspace/user ids,\nor full result URLs in reports. Use `--agent --json` and summarize redacted\nmetadata.\n\n## Current Public Boundary\n\nAllowed current launch surfaces: `GET /me`, `GET /catalog`, `GET /balance`,\n`GET /usage`, jobs, Avatar 1.0 model runs, Avatar Video 1.0 model runs, avatar\nresources, and avatar-video resources. `/v1/assets/*` is advanced\ncompatibility tooling only and is hidden from the launch OpenAPI/catalog.\n\nExcluded until public contracts exist: old Brand, Ads, Face Swap, generic\nimage/video generation, arbitrary file APIs, provider ids, and billing-write\noperations.\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today.\n", - "SKILL.md": "---\nname: sume\ndescription: Use the Sume.com CLI safely for auth, API discovery, avatars, avatar videos, jobs, balance, usage, and choosing focused Sume skills. Use this as the entry skill for current api.sume.com workflows.\n---\n\n# Sume Skill Router\n\nSume CLI is a thin wrapper over the current `api.sume.com` public API. It must\nnot call Sume databases, internal routes, provider APIs, or old `sume.so`-only\nsurfaces.\n\n## Core Rules\n\n1. Use `sume tools list --json` and `sume tools schema --json` before\n constructing writes.\n2. Use `--agent --json` whenever automation reads jobs, avatars, or\n avatar videos.\n3. Ask for explicit approval before `--confirm-submit` or `--confirm-paid`.\n4. Do not print API keys, auth approval URLs/codes in final reports, signed\n URLs, private media URLs, storage object keys, raw provider identifiers,\n workspace/user ids, or full result URLs.\n5. Use current public launch API surfaces only: account, catalog, balance,\n usage, jobs, Avatar 1.0, and Avatar Video 1.0.\n\n## Setup\n\n```bash\nsume --version\nsume auth status --json\nsume doctor --agent --json\n```\n\nUse browser login when the browser is local:\n\n```bash\nsume login\n```\n\nFor remote/headless terminals, use a short-lived background login process and\nshow the URL/code only to the requesting user. See `references/safety.md` for\nthe exact pattern.\n\n## Routing\n\n- Use `sume-tools` for schema discovery and skill maintenance.\n- Use `sume-avatar` for creating several avatars and choosing a ready avatar.\n- Use `sume-avatar-video` for making videos from selected avatars and reading\n metadata/result state.\n- Use `sume-assets` only for explicitly requested advanced compatibility asset\n workflows; launch generation inputs should be stable public HTTPS URLs.\n\nRead `references/safety.md` for auth, paid/write gates, and redaction rules.\nRead `references/eval-scenarios.md` when validating agent behavior.\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today.\n\n## Not For\n\nDo not use old `sume.so` Brand, Ads, Face Swap, generic image/video generation,\nraw provider model, billing-write, file, or asset-search workflows unless they\nappear in the current public `api.sume.com` catalog and tool schemas.\n" + "references/safety.md": "# Sume Safety Reference\n\n## Auth\n\n- Prefer `sume login` only when the browser is on the same machine.\n- In remote/headless terminals, avoid a long foreground login waiter because\n intermediate auth URLs/codes can be hidden until timeout or persisted in logs.\n- Use a short-lived process log:\n\n```bash\nlogin_log=\"$(mktemp -t sume-login.XXXXXX.log)\"\n(sume login --no-browser --timeout 600 >\"$login_log\" 2>&1; echo $? >\"$login_log.status\") &\nlogin_pid=$!\nsleep 4\nsed -n '1,80p' \"$login_log\"\n```\n\nAfter user approval:\n\n```bash\nwait \"$login_pid\"\nsume auth status --json\nrm -f \"$login_log\" \"$login_log.status\"\n```\n\n## Gates\n\n- `--confirm-submit`: non-paid writes such as asset registration, upload\n completion, and job cancellation.\n- `--confirm-paid`: paid generation submits such as Avatar 1.0 and Avatar Video\n 1.0 creation.\n\n## Sensitive Outputs\n\nNever echo API keys, approval codes, signed upload/download URLs, private media\nURLs, storage object keys, raw auth headers, provider ids, workspace/user ids,\nor full result URLs in reports. Use `--agent --json` and summarize redacted\nmetadata.\n\n## Current Public Boundary\n\nAllowed current launch surfaces: `GET /me`, `GET /catalog`, `GET /balance`,\n`GET /usage`, jobs, Avatar 1.0 model runs, Avatar Video 1.0 model runs, avatar\nresources, and avatar-video resources. `/v1/assets/*` is advanced\ncompatibility tooling only and is hidden from the launch OpenAPI/catalog.\n\nExcluded until public contracts exist: old Brand, Ads, Face Swap, generic\nimage/video generation, arbitrary file APIs, provider ids, and billing-write\noperations.\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today.\n" }, "sume-assets": { - "references/media-workflows.md": "# Media Workflows\n\n## Upload Safety\n\n- Signed upload URLs and headers are temporary credentials.\n- Do not send Sume API auth headers to signed storage URLs.\n- Direct upload helpers should keep signed URLs internal and return only\n redacted asset metadata.\n\n## Download Safety\n\n- Download only into an explicit user-approved output directory.\n- Download helpers should accept only URL fields returned by public Sume job or\n asset responses.\n- Final reports should summarize local filenames, sizes, and counts, not remote\n URLs.\n\n## Asset Usage\n\nLaunch model-run inputs accept URL references where the OpenAPI schema defines\nmedia fields. `/v1/assets/*` remains an advanced compatibility workflow, not the\ndefault public upload path. Do not assume an asset id is valid in a submit\nrequest unless the schema says so.\n", - "SKILL.md": "---\nname: sume-assets\ndescription: 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.\n---\n\n# Sume Assets\n\nUse this skill only when the user explicitly asks for advanced compatibility\n`api.sume.com` asset tooling. `/v1/assets/*` is hidden from the launch\nOpenAPI/catalog; normal Avatar and Avatar Video generation should use stable\npublic HTTPS URLs directly.\n\n## Discover Contracts\n\n```bash\nsume tools schema assets.create --json\nsume tools schema assets.upload_url --json\nsume tools schema assets.complete --json\nsume tools schema assets.download_url --json\n```\n\n## Register Public URL\n\n```bash\nsume assets create \\\n --source-url https://example.com/reference.png \\\n --media-type image \\\n --confirm-submit \\\n --agent \\\n --json\n```\n\nOnly register public HTTPS URLs that the user approved. The public API does not\necho the original source URL in readback.\n\n## Direct Upload\n\nUse `assets upload-url`, PUT bytes outside the CLI, then `assets complete`.\nNever paste signed URLs into reports.\n\n## Download\n\nUse CLI download helpers only when the user asks for local files:\n\n```bash\nsume assets download --output-dir ./outputs --json\nsume jobs download --output-dir ./outputs --json\n```\n\nRead `references/media-workflows.md` for details.\n\n## Not For\n\nDo not use assets as the default launch upload path, and do not pass asset ids\ninto generation requests unless the current OpenAPI schema explicitly accepts\nthem. Do not use old Asset Library scene search or `uploads/presign`; those are\n`sume.so`-only unless the current public catalog exposes them.\n" + "SKILL.md": "---\nname: sume-assets\ndescription: 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.\n---\n\n# Sume Assets\n\nUse this skill only when the user explicitly asks for advanced compatibility\n`api.sume.com` asset tooling. `/v1/assets/*` is hidden from the launch\nOpenAPI/catalog; normal Avatar and Avatar Video generation should use stable\npublic HTTPS URLs directly.\n\n## Discover Contracts\n\n```bash\nsume tools schema assets.create --json\nsume tools schema assets.upload_url --json\nsume tools schema assets.complete --json\nsume tools schema assets.download_url --json\n```\n\n## Register Public URL\n\n```bash\nsume assets create \\\n --source-url https://example.com/reference.png \\\n --media-type image \\\n --confirm-submit \\\n --agent \\\n --json\n```\n\nOnly register public HTTPS URLs that the user approved. The public API does not\necho the original source URL in readback.\n\n## Direct Upload\n\nUse `assets upload-url`, PUT bytes outside the CLI, then `assets complete`.\nNever paste signed URLs into reports.\n\n## Download\n\nUse CLI download helpers only when the user asks for local files:\n\n```bash\nsume assets download --output-dir ./outputs --json\nsume jobs download --output-dir ./outputs --json\n```\n\nRead `references/media-workflows.md` for details.\n\n## Not For\n\nDo not use assets as the default launch upload path, and do not pass asset ids\ninto generation requests unless the current OpenAPI schema explicitly accepts\nthem. Do not use old Asset Library scene search or `uploads/presign`; those are\n`sume.so`-only unless the current public catalog exposes them. Do not use this\nskill for paid generation; route Avatar work to `sume-avatar`, Avatar Video work\nto `sume-avatar-video`, and local comparison work to `sume-media-qa`.\n", + "references/media-workflows.md": "# Media Workflows\n\n## Upload Safety\n\n- Signed upload URLs and headers are temporary credentials.\n- Do not send Sume API auth headers to signed storage URLs.\n- Direct upload helpers should keep signed URLs internal and return only\n redacted asset metadata.\n\n## Download Safety\n\n- Download only into an explicit user-approved output directory.\n- Download helpers should accept only URL fields returned by public Sume job or\n asset responses.\n- Final reports should summarize local filenames, sizes, and counts, not remote\n URLs.\n\n## Asset Usage\n\nLaunch model-run inputs accept URL references where the OpenAPI schema defines\nmedia fields. `/v1/assets/*` remains an advanced compatibility workflow, not the\ndefault public upload path. Do not assume an asset id is valid in a submit\nrequest unless the schema says so.\n" + }, + "sume-auth": { + "SKILL.md": "---\nname: sume-auth\ndescription: Set up and verify Sume CLI authentication safely, including browser login, API-key readiness, doctor checks, and headless-terminal caveats without exposing secrets.\n---\n\n# Sume Auth\n\nUse this skill for local CLI readiness, login, and API-key configuration.\n\n## Discover\n\n```bash\nsume --version\nsume auth status --json\nsume doctor --agent --json\n```\n\n## Local Browser Login\n\nUse browser login only when the browser is on the same machine as the CLI\nprocess:\n\n```bash\nsume login\nsume auth status --json\n```\n\n## Headless Or Remote Terminals\n\nIn remote/headless terminals, avoid long foreground login waiters because\napproval URLs/codes can be hidden until timeout or retained in logs. Use the\nshort-lived process-log pattern in `sume/references/safety.md`, surface the\napproval URL/code only to the requesting user, and delete logs after approval.\n\n## API Keys\n\nPrefer approved local config or environment variables. Do not ask the user to\npaste API keys into chat unless they explicitly choose manual key setup.\n\n## Not For\n\nDo not run paid generation, uploads, downloads, MCP setup, or production\ninfrastructure work from this skill. Do not print auth URLs/codes, API keys, or\nlocal config contents in final reports, issues, PRs, or persistent logs.\n" }, "sume-avatar": { - "references/avatar-batch-manifest.md": "# Avatar Batch Manifest\n\n```json\n{\n \"defaults\": {\n \"mode\": \"async\"\n },\n \"avatars\": [\n {\n \"id\": \"friendly\",\n \"type\": \"prompt\",\n \"avatar_handle\": \"friendly_presenter\",\n \"prompt\": \"Warm, direct-to-camera skincare presenter\"\n },\n {\n \"id\": \"photo\",\n \"type\": \"photo\",\n \"avatar_handle\": \"photo_reference\",\n \"image_url\": \"https://example.com/person.png\"\n },\n {\n \"id\": \"profile\",\n \"type\": \"props\",\n \"avatar_handle\": \"profile_presenter\",\n \"ethnicity\": \"Asian\",\n \"sex\": \"female\",\n \"age\": 28\n }\n ]\n}\n```\n\n`batch plan` is local and no-provider. `batch create` is paid generation\nand must use `--confirm-paid`. Reruns with the same state file should not create\nduplicate jobs for items that already have a job id.\n", - "SKILL.md": "---\nname: sume-avatar\ndescription: Create, inspect, batch-plan, and select Sume Avatar 1.0 resources with safe paid gates and agent-redacted readback.\n---\n\n# Sume Avatar\n\nUse this skill for Avatar 1.0 creation and selection.\n\n## Discover\n\n```bash\nsume tools schema avatars.create --json\nsume tools schema avatars.list --json\nsume tools schema jobs.watch --json\n```\n\n## Single Avatar\n\n```bash\nsume avatars create \\\n --type prompt \\\n --avatar-handle presenter \\\n --prompt \"Friendly skincare presenter\" \\\n --confirm-paid \\\n --agent \\\n --json\n```\n\nPhoto and profile-style creation are current public inputs:\n\n```bash\nsume avatars create --type photo --avatar-handle photo_ref --image-url https://example.com/person.png --confirm-paid --agent --json\nsume avatars create --type props --avatar-handle profile --ethnicity Asian --sex female --age 28 --confirm-paid --agent --json\n```\n\n## Several Avatars\n\nPlan locally first:\n\n```bash\nsume avatars batch plan ./avatars.json --output-file ./avatars.plan.json --json\n```\n\nAfter explicit paid approval:\n\n```bash\nsume avatars batch create ./avatars.json --state-file ./avatars.state.json --confirm-paid --json\nsume avatars batch watch ./avatars.json --state-file ./avatars.state.json --json\nsume avatars batch result ./avatars.json --state-file ./avatars.state.json --json\n```\n\nUse ready avatar handles with `sume-avatar-video`.\n\n## Selection\n\n```bash\nsume avatars list --ready --agent --json\nsume avatars list --handle presenter --agent --json\nsume avatars get --agent --json\n```\n\nSummarize name, status, creation style, artifacts count, and any taste-relevant\nmetadata. Do not paste raw media URLs.\n" + "SKILL.md": "---\nname: sume-avatar\ndescription: Create, batch-plan, watch, inspect, and select current Sume Avatar 1.0 resources by avatar_handle with safe paid gates and agent-redacted readback.\n---\n\n# Sume Avatar\n\nUse this skill for Avatar 1.0 creation and selection.\nUse `sume tools schema avatars.create --json` before constructing writes; do\nnot copy request schemas from memory.\n\n## Discover\n\n```bash\nsume tools schema avatars.create --json\nsume tools schema avatars.list --json\nsume tools schema avatars.batch.plan --json\nsume tools schema jobs.watch --json\n```\n\n## Single Avatar\n\n```bash\nsume avatars create \\\n --type prompt \\\n --avatar-handle presenter \\\n --prompt \"Friendly skincare presenter\" \\\n --confirm-paid \\\n --agent \\\n --json\n```\n\nPhoto and profile-style creation are current public inputs:\n\n```bash\nsume avatars create --type photo --avatar-handle photo_ref --image-url https://example.com/person.png --confirm-paid --agent --json\nsume avatars create --type props --avatar-handle profile --ethnicity Asian --sex female --age 28 --confirm-paid --agent --json\n```\n\n## Several Avatars\n\nPlan locally first:\n\n```bash\nsume avatars batch plan ./avatars.json --output-file ./avatars.plan.json --json\n```\n\nAfter explicit paid approval:\n\n```bash\nsume avatars batch create ./avatars.json --state-file ./avatars.state.json --confirm-paid --json\nsume avatars batch watch ./avatars.json --state-file ./avatars.state.json --json\nsume avatars batch result ./avatars.json --state-file ./avatars.state.json --json\n```\n\nUse ready avatar handles with `sume-avatar-video`.\n\nRerunning batch create with the same state file must not duplicate already\nsubmitted paid jobs.\n\n## Selection\n\n```bash\nsume avatars list --ready --agent --json\nsume avatars list --handle presenter --agent --json\nsume avatars get --agent --json\n```\n\nSummarize name, status, creation style, artifacts count, and any taste-relevant\nmetadata. Do not paste raw media URLs.\n\n## Not For\n\nDo not use this skill for Avatar Video generation, generic image/video\ngeneration, old `sume.so` Brand/Ads/Face Swap workflows, raw provider models,\nor paid QA experiments. Use `sume-avatar-video`, `sume-quality-experiment`, or\n`sume-spend-capped-dogfood` as appropriate.\n", + "references/avatar-batch-manifest.md": "# Avatar Batch Manifest\n\n```json\n{\n \"defaults\": {\n \"mode\": \"async\"\n },\n \"avatars\": [\n {\n \"id\": \"friendly\",\n \"type\": \"prompt\",\n \"avatar_handle\": \"friendly_presenter\",\n \"prompt\": \"Warm, direct-to-camera skincare presenter\"\n },\n {\n \"id\": \"photo\",\n \"type\": \"photo\",\n \"avatar_handle\": \"photo_reference\",\n \"image_url\": \"https://example.com/person.png\"\n },\n {\n \"id\": \"profile\",\n \"type\": \"props\",\n \"avatar_handle\": \"profile_presenter\",\n \"ethnicity\": \"Asian\",\n \"sex\": \"female\",\n \"age\": 28\n }\n ]\n}\n```\n\n`batch plan` is local and no-provider. `batch create` is paid generation\nand must use `--confirm-paid`. Reruns with the same state file should not create\nduplicate jobs for items that already have a job id.\n" }, "sume-avatar-video": { - "references/avatar-video-batch-manifest.md": "# Avatar Video Batch Manifest\n\n```json\n{\n \"defaults\": {\n \"avatar_handle\": \"ready_avatar\",\n \"scene_prompt\": \"Bright studio\",\n \"mode\": \"async\"\n },\n \"videos\": [\n {\n \"id\": \"hook\",\n \"script\": \"This is the quick morning skincare step.\"\n },\n {\n \"id\": \"demo\",\n \"script\": \"Apply a small amount and watch it absorb.\",\n \"title\": \"Application demo\"\n }\n ]\n}\n```\n\n`batch plan` is local and no-provider. `batch create` is paid generation\nand requires `--confirm-paid`. Use a persistent state file so reruns skip items\nthat already have a job id.\n\nScripts are estimated locally and by the API; accepted target duration is 4-60\nseconds inclusive.\nAdd `product_image` in defaults or per-video entries only when the user provides\na public product/reference image.\n", - "SKILL.md": "---\nname: sume-avatar-video\ndescription: Create, batch-plan, watch, and inspect Sume Avatar Video 1.0 resources from selected avatars with metadata-aware readback and safe paid gates.\n---\n\n# Sume Avatar Video\n\nUse this skill after a ready avatar is selected.\n\n## Discover\n\n```bash\nsume tools schema avatar-videos.create --json\nsume tools schema avatar-videos.get --json\nsume tools schema jobs.result --json\n```\n\n## Single Video\n\n```bash\nsume avatar-videos create \\\n --avatar-handle \\\n --script \"This serum absorbs quickly.\" \\\n --scene-prompt \"Bright clean studio\" \\\n --confirm-paid \\\n --agent \\\n --json\n```\n\nThen:\n\n```bash\nsume jobs watch --agent --json\nsume jobs result --agent --json\nsume avatar-videos get --agent --json\n```\n\nScripts are estimated locally and by the API; accepted target duration is 4-60\nseconds inclusive. Use handles for avatar handoffs.\nAdd `--product-image` when the user provides a public product/reference image;\nomit it for productless avatar videos.\n\nSummarize status, artifacts, duration, tags, scenes, transcript, and summary\nwhen present. Do not paste full media URLs.\n\n## Batch Videos\n\n```bash\nsume avatar-videos batch plan ./avatar-videos.json --output-file ./avatar-videos.plan.json --json\nsume avatar-videos batch create ./avatar-videos.json --state-file ./avatar-videos.state.json --confirm-paid --json\nsume avatar-videos batch watch ./avatar-videos.json --state-file ./avatar-videos.state.json --json\nsume avatar-videos batch result ./avatar-videos.json --state-file ./avatar-videos.state.json --json\n```\n\nRead `references/avatar-video-batch-manifest.md` for manifest shape.\n\n## Not For\n\nDo not route generic video generation, Ads, UGC Ads, Face Swap, or raw provider\nmodel ids through this skill unless they are added to the current public\n`api.sume.com` catalog.\n" + "SKILL.md": "---\nname: sume-avatar-video\ndescription: 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.\n---\n\n# Sume Avatar Video\n\nUse this skill after a ready avatar is selected.\nUse `sume tools schema avatar-videos.create --json` before constructing writes;\ndo not copy request schemas from memory.\n\n## Discover\n\n```bash\nsume tools schema avatar-videos.create --json\nsume tools schema avatar-videos.get --json\nsume tools schema avatar-videos.batch.plan --json\nsume tools schema jobs.result --json\n```\n\n## Single Video\n\n```bash\nsume avatar-videos create \\\n --avatar-handle \\\n --script \"This serum absorbs quickly.\" \\\n --scene-prompt \"Bright clean studio\" \\\n --confirm-paid \\\n --agent \\\n --json\n```\n\nThen:\n\n```bash\nsume jobs watch --agent --json\nsume jobs result --agent --json\nsume avatar-videos get --agent --json\n```\n\nScripts are estimated locally and by the API; accepted target duration is 4-60\nseconds inclusive. Use handles for avatar handoffs.\nAdd `--product-image` when the user provides a public product/reference image;\nomit it for productless avatar videos.\n\nSummarize status, artifacts, duration, tags, scenes, transcript, and summary\nwhen present. Do not paste full media URLs.\n\n## Batch Videos\n\n```bash\nsume avatar-videos batch plan ./avatar-videos.json --output-file ./avatar-videos.plan.json --json\nsume avatar-videos batch create ./avatar-videos.json --state-file ./avatar-videos.state.json --confirm-paid --json\nsume avatar-videos batch watch ./avatar-videos.json --state-file ./avatar-videos.state.json --json\nsume avatar-videos batch result ./avatar-videos.json --state-file ./avatar-videos.state.json --json\n```\n\nRead `references/avatar-video-batch-manifest.md` for manifest shape.\nRerunning batch create with the same state file must not duplicate already\nsubmitted paid jobs.\n\n## Not For\n\nDo not route generic video generation, Ads, UGC Ads, Face Swap, or raw provider\nmodel ids through this skill unless they are added to the current public\n`api.sume.com` catalog. Do not use this skill for local media inspection only;\nuse `sume-media-qa` when no paid generation is needed.\n", + "references/avatar-video-batch-manifest.md": "# Avatar Video Batch Manifest\n\n```json\n{\n \"defaults\": {\n \"avatar_handle\": \"ready_avatar\",\n \"scene_prompt\": \"Bright studio\",\n \"mode\": \"async\"\n },\n \"videos\": [\n {\n \"id\": \"hook\",\n \"script\": \"This is the quick morning skincare step.\"\n },\n {\n \"id\": \"demo\",\n \"script\": \"Apply a small amount and watch it absorb.\",\n \"title\": \"Application demo\"\n }\n ]\n}\n```\n\n`batch plan` is local and no-provider. `batch create` is paid generation\nand requires `--confirm-paid`. Use a persistent state file so reruns skip items\nthat already have a job id.\n\nScripts are estimated locally and by the API; accepted target duration is 4-60\nseconds inclusive.\nAdd `product_image` in defaults or per-video entries only when the user provides\na public product/reference image.\n" + }, + "sume-media-qa": { + "SKILL.md": "---\nname: sume-media-qa\ndescription: Inspect and compare Sume media outputs locally with no provider calls, using duration/codec checks, still sheets, side-by-side comparisons, and artifact notes.\n---\n\n# Sume Media QA\n\nUse this skill to inspect existing Sume outputs without submitting new paid\ngeneration jobs.\n\n## Get Files Only When Needed\n\n```bash\nsume jobs result --agent --json\nsume jobs download --output-dir ./sume-outputs --json\n```\n\nUse explicit output directories. Final reports should mention local filenames,\ncounts, dimensions, duration, and issues, not full media URLs.\n\n## Local Checks\n\nUse local tools when available:\n\n```bash\nffprobe -v error -show_format -show_streams ./sume-outputs/video.mp4\n```\n\nCheck:\n\n- duration and aspect ratio;\n- codec/container compatibility;\n- audio presence and sync;\n- obvious visual artifacts;\n- product/identity continuity;\n- whether a side-by-side comparison or still sheet is needed.\n\n## Report\n\nReturn a compact QA note with files inspected, pass/fail observations, and\nrecommended next action. Keep provider internals and full URLs out of the\nreport.\n\n## Not For\n\nDo not create Avatar or Avatar Video jobs from this skill. Use\n`sume-avatar-video`, `sume-min-latency`, `sume-quality-experiment`, or\n`sume-spend-capped-dogfood` when paid generation is needed.\n" + }, + "sume-min-latency": { + "SKILL.md": "---\nname: sume-min-latency\ndescription: 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.\n---\n\n# Sume Minimum Latency\n\nUse this skill when the user wants the fastest useful Sume result while still\nrespecting paid gates and avoiding duplicate jobs.\n\n## Rules\n\n1. Run readiness only if local state is unknown:\n\n ```bash\n sume doctor --agent --json\n ```\n\n2. Use schema discovery only for the write you are about to make:\n\n ```bash\n sume tools schema avatars.create --json\n sume tools schema avatar-videos.create --json\n ```\n\n3. Prefer async submit plus watch/result over blocking waits.\n4. For multiple independent candidates, draft a manifest and use batch\n plan/create/watch/result with a persistent state file.\n5. Use stable idempotency keys. Reruns must skip already-created jobs.\n6. Do not download media unless local comparison is required or the user asks.\n7. If the user prioritizes speed/cost, explicitly choose `quality=standard`;\n otherwise preserve the platform default quality.\n\n## Fast Avatar Video Loop\n\n```bash\nsume avatar-videos create \\\n --avatar-handle \\\n --script \"Short reviewed script.\" \\\n --quality standard \\\n --confirm-paid \\\n --agent \\\n --json\n\nsume jobs watch --agent --json\nsume jobs result --agent --json\n```\n\n## Report\n\nReport job id, resource id, requested quality, wall-clock time if measured,\nqueue/run state, captured/refunded cost when available, and sanitized result\navailability. Do not paste full media URLs.\n\n## Not For\n\nDo not use this skill for broad quality exploration or side-by-side evaluation;\nuse `sume-quality-experiment`. Do not use it to bypass spend caps, paid\napproval, idempotency, or state files.\n" + }, + "sume-quality-experiment": { + "SKILL.md": "---\nname: sume-quality-experiment\ndescription: Design and run controlled Sume quality experiments with one-variable variants, reusable manifests, side-by-side artifact comparison, and rubric-based sanitized reports.\n---\n\n# Sume Quality Experiment\n\nUse this skill for controlled Avatar or Avatar Video comparisons.\n\n## Experiment Rules\n\n1. Write a short local manifest before paid calls.\n2. Change one variable per variant: quality tier, scene prompt, product image,\n avatar handle, script, duration, or aspect ratio.\n3. Keep shared anchors identical across variants.\n4. Run no-cost checks first: schema discovery, manifest validation, and local\n media inspection when outputs already exist.\n5. Ask for explicit paid approval and a spend cap before paid generation.\n6. Use idempotency keys and state files so reruns do not duplicate jobs.\n\n## Commands\n\n```bash\nsume tools schema avatar-videos.create --json\nsume avatar-videos batch plan ./experiment.videos.json --output-file ./experiment.plan.json --json\nsume avatar-videos batch create ./experiment.videos.json --state-file ./experiment.state.json --confirm-paid --json\nsume avatar-videos batch watch ./experiment.videos.json --state-file ./experiment.state.json --json\nsume avatar-videos batch result ./experiment.videos.json --state-file ./experiment.state.json --json\n```\n\nUse `sume-media-qa` after results exist if the user needs local files, still\nsheets, codec checks, or side-by-side comparison.\n\n## Rubric\n\nScore or summarize:\n\n- identity preservation;\n- product fidelity;\n- script/audio fit;\n- scene continuity;\n- artifact severity;\n- metadata/readback usefulness;\n- cost and elapsed time.\n\n## Not For\n\nDo not use this skill for unrestricted exploration, raw provider endpoint\ntests, or one-off fastest iteration. Use `sume-min-latency` for speed and\n`sume-spend-capped-dogfood` for paid QA with a strict budget.\n" + }, + "sume-spend-capped-dogfood": { + "SKILL.md": "---\nname: sume-spend-capped-dogfood\ndescription: Run paid Sume dogfood QA under an explicit USD cap using idempotency, max_spend_usd where available, cost readback, and no duplicate paid submissions.\n---\n\n# Sume Spend-Capped Dogfood\n\nUse this skill when the user authorizes paid Sume QA with a hard budget.\n\n## Required Before Paid Calls\n\n- Confirm the exact USD cap.\n- Identify the minimum number of jobs needed for evidence.\n- Prefer dry-run/admission preview or estimate if exposed by the current tool\n schema.\n- Use stable idempotency keys.\n- Use batch state files for more than one job.\n- Stop once the evidence is sufficient.\n\nIf a future release enables MCP paid tools, `idempotency_key` and\n`max_spend_usd` are mandatory. For current CLI commands, record the approved cap\nin the manifest/report and pass idempotency keys where supported.\n\n## Commands\n\n```bash\nsume doctor --agent --json\nsume balance --json\nsume tools schema avatar-videos.create --json\n```\n\nSingle-job example after explicit approval:\n\n```bash\nsume avatar-videos create \\\n --avatar-handle \\\n --script \"Short QA script.\" \\\n --quality standard \\\n --idempotency-key \\\n --confirm-paid \\\n --agent \\\n --json\n```\n\nThen:\n\n```bash\nsume jobs watch --agent --json\nsume jobs result --agent --json\nsume balance --json\n```\n\n## Report\n\nReport requested quality, job id, resource id, expected/reserved/captured/\nrefunded cost when available, status/result, and whether the cap was respected.\nIf exact cost telemetry is missing, state that as a product gap instead of\ninferring a billing guarantee.\n\n## Not For\n\nDo not use this skill without an explicit cap. Do not keep spending for broad\nexploration. Do not print secrets, full URLs, signed URLs, provider payloads, or\nprivate identifiers.\n" }, "sume-tools": { - "references/mcp-toolsets.md": "# MCP Coming Soon\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today for auth, schema discovery, Avatar, Avatar Video,\njobs, balance, and usage workflows.\n\n```bash\nsume login\nsume doctor --agent --json\nsume tools list --json\nsume tools schema avatars.create --json\nsume tools schema avatar-videos.create --json\n```\n", - "SKILL.md": "---\nname: sume-tools\ndescription: Discover Sume.com CLI tool schemas, install or export bundled Sume skills, inspect balance/usage, and choose safe public-api workflows.\n---\n\n# Sume Tools\n\nUse this skill for schema discovery and local skill maintenance.\n\n## Discovery\n\n```bash\nsume doctor --agent --json\nsume tools list --json\nsume tools schema avatars.create --json\nsume tools schema avatar-videos.create --json\nsume balance --json\nsume usage get --json\n```\n\n## Skill Maintenance\n\n```bash\nsume skills list --json\nsume skills install sume --json\nsume skills install sume-avatar --json\nsume skills update --json\n```\n\nSkills install into `.agents/skills/` when `.agents/` exists, otherwise\n`.claude/skills/` when `.claude/` exists.\n\n## MCP\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today.\n\n## Not For\n\nDo not execute paid creation directly from this skill. Route avatar work to\n`sume-avatar` and video work to `sume-avatar-video`. Route media inputs through\npublic HTTPS URLs unless the user explicitly asks for advanced compatibility\nasset tooling.\n" + "SKILL.md": "---\nname: sume-tools\ndescription: Discover current Sume CLI tool schemas, inspect bundled skills, check readiness, and choose safe CLI/MCP workflows without executing paid generation.\n---\n\n# Sume Tools\n\nUse this skill for schema discovery and local skill maintenance.\n\nDo not construct write or paid payloads from memory. Use the local tool registry\nas the executable contract.\n\n## Discovery\n\n```bash\nsume doctor --agent --json\nsume tools list --json\nsume tools schema avatars.create --json\nsume tools schema avatar-videos.create --json\nsume tools schema jobs.watch --json\nsume balance --json\nsume usage get --json\n```\n\n## Skill Maintenance\n\n```bash\nsume skills list --json\nsume skills export sume --json\nsume skills install sume --json\nsume skills install sume-avatar --json\nsume skills update --json\n```\n\nSkills install into `.agents/skills/` when `.agents/` exists, otherwise\n`.claude/skills/` when `.claude/` exists.\n\n## MCP\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today.\n\nIf a future release enables MCP, treat MCP tool descriptions and\n`sume tools schema` safety metadata as the source of truth for toolsets, write\ngates, paid gates, and redaction behavior.\n\n## Not For\n\nDo not execute paid creation directly from this skill. Route avatar work to\n`sume-avatar`, video work to `sume-avatar-video`, spend-capped QA to\n`sume-spend-capped-dogfood`, local artifact checks to `sume-media-qa`, and fast\niteration to `sume-min-latency`. Route media inputs through public HTTPS URLs\nunless the user explicitly asks for advanced compatibility asset tooling.\n", + "references/mcp-toolsets.md": "# MCP Coming Soon\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today for auth, schema discovery, Avatar, Avatar Video,\njobs, balance, and usage workflows.\n\n```bash\nsume login\nsume doctor --agent --json\nsume tools list --json\nsume tools schema avatars.create --json\nsume tools schema avatar-videos.create --json\n```\n" } } as const; diff --git a/test/cli.test.ts b/test/cli.test.ts index a500c25..cc0ecfb 100644 --- a/test/cli.test.ts +++ b/test/cli.test.ts @@ -255,6 +255,11 @@ describe("CLI", () => { "sume-assets", "sume-avatar", "sume-avatar-video", + "sume-auth", + "sume-media-qa", + "sume-min-latency", + "sume-quality-experiment", + "sume-spend-capped-dogfood", "sume-tools", ]), ); @@ -277,6 +282,13 @@ describe("CLI", () => { expect(body).toContain("Not For"); expect(body).toContain("Face Swap"); expect(body).toContain("unless they are added to the current public"); + + const router = await runCli(["--json", "skills", "export", "sume"], baseUrl); + const parsedRouter = JSON.parse(router.stdout); + expect(JSON.stringify(parsedRouter)).toContain("Sume Skill Router"); + expect(JSON.stringify(parsedRouter)).toContain("sume skills list --json"); + expect(JSON.stringify(parsedRouter)).toContain("sume-min-latency"); + expect(JSON.stringify(parsedRouter)).toContain("sume-spend-capped-dogfood"); }, ); }); diff --git a/test/skills-registry.test.ts b/test/skills-registry.test.ts index 62847a4..d6a04a4 100644 --- a/test/skills-registry.test.ts +++ b/test/skills-registry.test.ts @@ -20,6 +20,11 @@ describe("skills registry", () => { "sume-assets", "sume-avatar", "sume-avatar-video", + "sume-auth", + "sume-media-qa", + "sume-min-latency", + "sume-quality-experiment", + "sume-spend-capped-dogfood", "sume-tools", ]), ); @@ -32,6 +37,45 @@ describe("skills registry", () => { expect(body).toContain("current public `api.sume.com` catalog"); }); + it("exports a router skill with focused discovery routing", () => { + const exported = exportBundledSkill("sume"); + const body = JSON.stringify(exported); + expect(body).toContain("Sume Skill Router"); + expect(body).toContain("sume skills list --json"); + expect(body).toContain("sume skills export --json"); + expect(body).toContain("sume-min-latency"); + expect(body).toContain("sume-quality-experiment"); + expect(body).toContain("sume-spend-capped-dogfood"); + expect(body).toContain("sume-media-qa"); + expect(body).toContain("Sume MCP is coming soon"); + }); + + it("keeps focused skill boundaries discoverable and safe", () => { + const paidSkill = JSON.stringify(exportBundledSkill("sume-spend-capped-dogfood")); + expect(paidSkill).toContain("explicit USD cap"); + expect(paidSkill).toContain("idempotency"); + expect(paidSkill).toContain("max_spend_usd"); + expect(paidSkill).toContain("no duplicate paid submissions"); + + const mediaQa = JSON.stringify(exportBundledSkill("sume-media-qa")); + expect(mediaQa).toContain("no provider calls"); + expect(mediaQa).toContain("Do not create Avatar or Avatar Video jobs"); + expect(mediaQa).not.toContain("--confirm-paid"); + + const assets = JSON.stringify(exportBundledSkill("sume-assets")); + expect(assets).toContain("advanced compatibility"); + expect(assets).toContain("default launch upload path"); + expect(assets).toMatch(/Do not use this\\nskill for paid generation/u); + }); + + it("keeps bundled skills off old sume.so-only current workflows", () => { + for (const skillName of Object.keys(bundledSkillFiles)) { + const exported = JSON.stringify(exportBundledSkill(skillName)); + expect(exported).not.toMatch(/sume\\.so.*current workflow/iu); + expect(exported).not.toMatch(/sume (ads|images|videos|brand) /iu); + } + }); + it("installs, updates, and removes bundled skills in a temp project", () => { const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "sume-skills-")); try {