Expert Usage Guide

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.