expert-usage-guide

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

From pipixia-labs/creative-claw, MIT.

More from pipixia-labs/creative-claw