# Expert Usage Guide > 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. - Skill: `pipixia-labs/expert-usage-guide` (Agent Skill) - Install (CLI): `npx skillmds@latest add pipixia-labs/expert-usage-guide` - Raw SKILL.md: https://api.skillmd.com/api/skills/pipixia-labs/expert-usage-guide/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: pipixia-labs (https://skillmd.com/u/pipixia-labs) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/pipixia-labs/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: ```json {"prompt":"a cinematic cat poster","provider":"nano_banana"} ``` ```json {"prompt":"a cinematic cat poster","provider":"seedream"} ``` ```json {"prompt":"a cinematic cat poster","provider":"gpt_image","size":"1536x1024","quality":"medium"} ``` ```json {"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: ```json {"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: ```json {"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: ```json {"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: ```json {"input_path":"inbox/cli/source.png","mode":"description"} ``` ```json {"input_path":"inbox/cli/source.png","mode":"all"} ``` ```json {"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: ```json {"input_text":"Launch a summer tea campaign.","mode":"rewrite"} ``` ```json {"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: ```json {"prompt":"make a cinematic cat video","provider":"seedance","mode":"prompt"} ``` ```json {"input_path":"inbox/cli/first_frame.png","prompt":"animate this image","provider":"veo","mode":"first_frame"} ``` ```json {"prompt":"A cinematic dragon boat racing through neon rain","provider":"dashscope","mode":"prompt","model_name":"wan2.7-t2v","resolution":"1080p","duration_seconds":5} ``` ```json {"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: ```json {"input_path":"inbox/cli/reference.mp4","mode":"description"} ``` ```json {"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: ```json {"input_path":"inbox/cli/interview.wav"} ``` ```json {"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: ```json {"text":"Hello from Creative Claw.","voice_name":"Vivi 2.0"} ``` ```json {"text":"这是一段产品视频解说。","voice_name":"解说小明 2.0","audio_format":"mp3"} ``` ```json {"ssml":"Helloworld","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: ```json {"prompt":"cinematic orchestral background music","instrumental":true} ``` ```json {"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: ```json {"query":"editorial fashion poster references","mode":"image"} ``` ```json {"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: ```json {"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.