expert-usage-guide

name	expert-usage-guide
description	Use when the task depends on choosing the right Creative Claw expert, composing expert calls, or explaining the usage strategy for image, video, search, grounding, segmentation, prompt extraction, or knowledge experts.

Expert Usage Guide

Use this skill when you need to decide which Creative Claw expert should handle a task, how to structure invoke_agent(...) parameters, or how to chain several experts together.

This skill is about routing and strategy. It does not replace the actual expert implementation.

Core Rule

• Prefer built-in file tools and direct reasoning for ordinary coding, file editing, and lightweight analysis.
• Use an expert only when the task needs a specialized capability that is already productized in the system.
• When an expert has a structured parameter contract, always pass a JSON object string to invoke_agent.
• Prefer workspace-relative paths such as inbox/... and generated/....

Expert Selection Strategy

ImageGenerationAgent

Use when:

• The user wants to create new images from text.
• No source image is required as the main input.

Recommended providers:

• nano_banana: default choice for general text-to-image generation.
• seedream: use when the user explicitly asks for Seedream or the task clearly needs that provider.
• gpt_image: use when the user explicitly asks for GPT Image / OpenAI image generation, or when the task should follow OpenAI-native image parameters.
• dashscope: use when the user asks for Aliyun Model Studio, Wan image, Qwen Image 2.0, or Z-Image generation.

Recommended parameters:

{"prompt":"a cinematic cat poster","provider":"nano_banana"}

{"prompt":"a cinematic cat poster","provider":"seedream"}

{"prompt":"a cinematic cat poster","provider":"gpt_image","size":"1536x1024","quality":"medium"}

{"prompt":"a cinematic cat poster","provider":"dashscope","model_name":"wan2.7-image-pro","size":"2K"}

Do not use when:

• The user wants to edit an existing image.
• The user first needs image understanding, grounding, segmentation, or prompt extraction.

ImageEditingAgent

Use when:

• The user wants to modify one or more existing images.
• The task is "change this image", "replace background", "make it blue", "edit the uploaded image", and similar.

Recommended parameters:

{"input_path":"inbox/cli/source.png","prompt":["replace the background with a clean white studio"],"provider":"nano_banana"}

Use input_paths when several images or references are required.

Do not use when:

• The user wants a mask first.
• The user wants pure text-to-image generation.

ImageSegmentationAgent

Use when:

• The user wants a mask, cutout, localized edit, region-only processing, or inpaint-style preparation.
• The task says "segment", "extract the subject", "generate a mask", "keep only the person", or similar.

Recommended parameters:

{"input_path":"inbox/cli/source.png","prompt":"person","threshold":0.2}

Key follow-up rule:

• After success, read current_output.results[0].mask_path.
• That mask_path is a reusable workspace file path for later tools or experts.

Typical chaining:

1. Call ImageSegmentationAgent.
2. Read mask_path.
3. Pass that workspace path to later editing or file-processing steps.

ImageGroundingAgent

Use when:

• The user needs locations or bounding boxes, not a pixel mask.
• The task is to find where an object is in the image.

Recommended parameters:

{"input_path":"inbox/cli/source.png","prompt":"red handbag"}

Prefer this over segmentation when:

• Bbox information is enough.
• The next step only needs rough localization.

ImageUnderstandingAgent

Use when:

• The user wants description, style analysis, OCR, prompt reverse engineering, or a combined understanding pass.
• The task says "describe this image", "read the text in this image", "analyze the style", "reverse prompt this image", or similar.

Recommended parameters:

{"input_path":"inbox/cli/source.png","mode":"description"}

{"input_path":"inbox/cli/source.png","mode":"all"}

{"input_path":"inbox/cli/reference.png","mode":"prompt"}

Prefer this before generation or editing when:

• The image contents are unclear.
• You need to understand a reference before deciding the next step.

TextTransformExpert

Use when:

• The task is one atomic text transform only.
• The user wants rewrite, expand, compress, translate, structure, title, or script.

Recommended parameters:

{"input_text":"Launch a summer tea campaign.","mode":"rewrite"}

{"input_text":"Launch a summer tea campaign.","mode":"translate","target_language":"zh-CN"}

VideoGenerationAgent

Use when:

• The user wants a video generated from text or image-guided inputs.

Recommended parameters:

{"prompt":"make a cinematic cat video","provider":"seedance","mode":"prompt"}

{"input_path":"inbox/cli/first_frame.png","prompt":"animate this image","provider":"veo","mode":"first_frame"}

{"prompt":"A cinematic dragon boat racing through neon rain","provider":"dashscope","mode":"prompt","model_name":"wan2.7-t2v","resolution":"1080p","duration_seconds":5}

{"input_path":"inbox/cli/first_frame.png","prompt":"animate this image","provider":"dashscope","mode":"first_frame","model_name":"wan2.7-i2v"}

Do not use when:

• The task is only to generate still images.
• The task requires DashScope video editing or reference-video generation; those routes are not exposed yet.

VideoUnderstandingExpert

Use when:

• The task is about understanding an existing video, not generating one.
• The user wants description, shot breakdown, OCR, or prompt reverse engineering from a reference video.

Recommended parameters:

{"input_path":"inbox/cli/reference.mp4","mode":"description"}

{"input_path":"inbox/cli/reference.mp4","mode":"prompt"}

SpeechRecognitionExpert

Use when:

• The user wants audio or video converted into text.
• The task is transcript-first, not audio editing or synthesis.

Recommended parameters:

{"input_path":"inbox/cli/interview.wav"}

{"input_path":"inbox/cli/interview.mp4","timestamps":true,"language":"en"}

SpeechSynthesisExpert

Use when:

• The user wants text or SSML converted into spoken audio.
• The task is voiceover, narration, or TTS.

Recommended parameters:

{"text":"Hello from Creative Claw.","voice_name":"Vivi 2.0"}

{"text":"这是一段产品视频解说。","voice_name":"解说小明 2.0","audio_format":"mp3"}

{"ssml":"<speak>Hello<break time=\"500ms\"/>world</speak>","resource_id":"seed-tts-1.0","speaker":"zh_female_yingyujiaoyu_mars_bigtts"}

Notes:

• The default TTS resource is seed-tts-2.0; use voice_name, voice_type, or speaker for validated Seed TTS 2.0 voices.
• Pass resource_id="seed-tts-1.0" only for legacy speaker ids that are not in the Seed TTS 2.0 catalog.

MusicGenerationExpert

Use when:

• The user wants a generated song draft or BGM clip from text instructions.
• The task is music creation rather than speech synthesis.

Recommended parameters:

{"prompt":"cinematic orchestral background music","instrumental":true}

{"prompt":"warm folk pop song","lyrics":"custom lyric lines"}

SearchAgent

Use when:

• The user needs external references, inspirations, or web facts.

Mode strategy:

• image: use for visual references.
• text: use for factual or conceptual information.
• all: use when both are helpful.

Recommended parameters:

{"query":"editorial fashion poster references","mode":"image"}

{"query":"brand campaign visual strategy examples","mode":"text"}

KnowledgeAgent

Use when:

• The task needs design thinking, art direction, prompt planning, or creative decomposition before execution.
• The user wants several visual directions, campaign ideas, or prompt sets.

Recommended parameters:

{"prompt":"Design three visual directions for a premium matcha brand campaign"}

Prefer this before generation when:

• The task is underspecified.
• The user wants higher-level creative planning, not just direct rendering.

Common Chaining Patterns

Reference Image -> Better Prompt -> New Image

1. ImageUnderstandingAgent with mode="prompt"
2. ImageGenerationAgent

Video Reference -> Understand -> Decide Next Step

1. VideoUnderstandingExpert
2. Then choose VideoGenerationAgent, KnowledgeAgent, or file tools based on the result

Speech Media -> Transcript -> Script Rewrite

1. SpeechRecognitionExpert
2. TextTransformExpert

Uploaded Image -> Understand -> Decide Edit Direction

1. ImageUnderstandingAgent
2. ImageEditingAgent

Uploaded Image -> Segment Subject -> Local Edit

1. ImageSegmentationAgent
2. Read mask_path
3. Use ImageEditingAgent or built-in file/image tools

Design Brief -> Creative Directions -> Final Rendering

1. KnowledgeAgent
2. ImageGenerationAgent

Need Web References Before Rendering

1. SearchAgent
2. KnowledgeAgent or ImageGenerationAgent

Routing Heuristics

• If the user says "generate", start from ImageGenerationAgent.
• If the user says "edit this image", start from ImageEditingAgent.
• If the user says "describe / OCR / analyze style / reverse prompt image", start from ImageUnderstandingAgent.
• If the user says "rewrite / translate / compress / title / script", start from TextTransformExpert.
• If the user says "find where", start from ImageGroundingAgent.
• If the user says "mask / cutout / segment", start from ImageSegmentationAgent.
• If the user says "analyze this video / break down shots / OCR video / reverse prompt video", start from VideoUnderstandingExpert.
• If the user says "video generation", start from VideoGenerationAgent.
• If the user says "transcribe audio / transcribe video / speech to text", start from SpeechRecognitionExpert.
• If the user says "text to speech / narration / voiceover", start from SpeechSynthesisExpert.
• If the user says "BGM / generate music / song draft", start from MusicGenerationExpert.
• If the user says "search references / web info", start from SearchAgent.
• If the user says "give me design directions / creative plan", start from KnowledgeAgent.

Important Guardrails

• Do not call an expert just because one exists; choose it because it is the best fit.
• Do not use ImageGenerationAgent when the user clearly needs an image edit.
• Do not use ImageGroundingAgent when the next step truly needs a pixel mask; use ImageSegmentationAgent.
• Do not pass artifact names or vague labels when a workspace path is available.
• Do not invent unsupported provider names. Use only declared provider values.