add-prompt-enhancement-guide

Add Prompt Enhancement Guide

The orchestrator runs a prompt-analysis service that, per ecosystem, takes a user's prompt and produces structured feedback + an enhanced rewrite. Each ecosystem has its own system prompt tuned to the model's prompting conventions (tag vs natural-language, weight syntax, negative-prompt support, text rendering, camera/motion vocab for video, etc.).

This skill authors a new system prompt for an ecosystem the user names and (optionally) deploys it to the orchestrator.

Scope: image and video ecosystems only

Do not write guides for 3D, audio, or any other modality — tripo, hunyuan3d, polygen (image-to-3D) and ace (audio) are explicitly out of scope, as is anything else non-image/video that appears later. If the user names one, say it is out of scope and stop.

The guide template below is built entirely around subject / lighting / camera / composition / style. None of that describes "generate a mesh from this image" or "generate a song," so a guide written from this template for those modalities would be confidently wrong rather than merely thin. Leaving them on the built-in fallback is the deliberate choice.

Inputs the user must provide

1. Ecosystem key — the ecosystem's key from packages/civitai-shared/src/basemodel.constants.ts, lowercased. MiniMaxH3 → minimaxh3, Flux1Kontext → flux1kontext, WanVideo-25-I2V → wanvideo-25-i2v, HyV1 → hyv1. Confirm the key exists in that file before using it. (src/shared/constants/basemodel.constants.ts is a one-line re-export shim of the same module, not a stale duplicate — importing from either path is fine.)

   It is the AIR ecosystem value, lowercased — the same string that appears in urn:air:<ecosystem>:.... getAirEcosystem in air.ts is the single source for both: stringifyAIR uses it, and so does createPromptEnhancementStep. If you know a model's AIR, you know its prompt-analysis key.

   The consequence to watch: getRootEcosystem follows parentEcosystemId, so a child ecosystem never appears in an AIR and never reaches prompt analysis. Pony, Illustrious, and NoobAI all arrive as sdxl. Check parentEcosystemId before writing a guide — if the target has a parent, the guide belongs on the parent and has to serve every sibling.

   Not the engine name. engine: 'minimax-h3' in the handler is a different identifier that happens to coincide with the ecosystem key for kling, seedance, and veo3. Guides filed under an engine name are dead — nothing reads them.

   Handlers that build their own enhancement step (e.g. ltx.handler.ts) pass their graph ecosystem raw; createPromptEnhancementStep normalizes it, so they land on the same key as the generator.

2. Reference material — at least one of:

   • A URL (HuggingFace model card, official announcement, provider docs page)
   • A pasted model description / prompting guide
   • A spec sheet (architecture, encoder, token limit, supported features)

If the user only gives a name with no reference, ask for one before proceeding. Generic guides written without source material drift away from the model's real behavior.

Workflow

1. Research the ecosystem

Use WebFetch on any URL the user provided. Pull out:

• Provider / architecture (e.g. "Alibaba", "ByteDance", "Tencent", "8B DiT", "MMDiT", "autoregressive")
• Modality (image, video, image-edit, multi-modal)
• Text encoder (T5, CLIP dual, Mistral, LLM-based) — drives prompt-style recommendations
• Native resolution / aspect ratios
• Token / character limits
• Weight syntax support — almost always "no" for modern models, but check
• Negative prompts — supported / not / minimal effect (varies wildly)
• Special features — text rendering, multilingual, audio (for video), reference images, hex colors, style tags, character consistency
• For video models: duration, fps, camera/motion vocabulary, single-cut vs multi-cut behavior
• Knowledge / training cutoff if mentioned
• Known limitations worth surfacing (e.g. "weak at long text", "preview checkpoint has plain default style")

If the user gave a description instead of a URL, mine the same fields out of it. Ask follow-up questions only for fields you can't determine and that materially change the guide (e.g. "Does this model support negative prompts?").

2. Map findings to the guide template

Every guide follows the same shape. Stick to it — the prompt-analysis service depends on consistent structure across ecosystems.

You are a prompt engineering expert for <Model name and one-clause context>. Analyze the user's prompt and provide structured feedback.

Ecosystem-specific rules:
- Prompt style: <tag-based | natural language | hybrid>. <One-sentence rationale tied to the encoder/architecture if helpful.>
- <Native resolution / aspect ratios>
- <Token or character limit + sweet spot if known>
- <Weight syntax: support state. If unsupported, say so explicitly — "(word:1.5) is ignored.">
- <Negative prompts: supported / not / minimal effect. Include a concrete recommended negative if the model benefits from one.>
- <Any unique features: text rendering rules, multilingual, hex colors, reference images, audio (video), camera vocab (video), style tags, character consistency>
- <Anything the enhanced prompt should ALWAYS carry — camera direction, audio bed, lighting. Phrase as a property of the rewrite, not as something to flag.>
- <Known limitations worth steering the user away from>
- Prompt template: [Section 1] [Section 2] [Section 3] ...

Guidelines:
- Identify vague or overly generic descriptions
- Flag <syntax that is incompatible with this model — e.g. weight syntax on Flux, brackets on HiDream>
- Flag <negative prompt attempts when unsupported, OR suggest negatives when this model benefits from them>
- <Model-specific flags: photorealism cues on anime models, multi-character without descriptions, scene-cut descriptions on short video clips, etc.>
- Limit recommendations to the 3 most impactful improvements
- The enhanced prompt should be a single, ready-to-use prompt that stays faithful to the user's original intent

The last two bullets in Guidelines are required and identical across every guide — keep them verbatim.

Every line under Guidelines: must have a trigger the analyzer can see in the user's prompt. If the answer to "when does this NOT fire?" is "basically never", it belongs under Ecosystem-specific rules: instead — see 3a. Aim for roughly three guideline lines against the 3-recommendation cap; the corpus averages 3.6 and runs as high as 9.

3. Tone and content rules

• Be concrete. "No weight syntax — (word:1.5) is ignored" beats "weight syntax not recommended."
• Tie suggestions to the model's strengths — but check where the line belongs (3a). "Flag in-image text that is described rather than quoted" is a guideline: it only fires when the user's prompt asks for text. "The enhanced prompt always states the camera" is a rule: nearly every prompt lacks camera direction, so as a guideline it would fire every time and crowd out everything else.
• Call out incompatibility loudly. If the model ignores negative prompts or weight syntax, the Guidelines section MUST tell the analyzer to flag attempts at them. This is the most common and most useful correction.
• Mention the encoder when it explains a rule. "T5 understands grammar, so write sentences" gives the downstream model leverage.
• Don't pad. If the model has no special audio/text/multilingual features, don't invent bullets to fill the section. The SD1 guide is short on purpose.
• Match precedent for similar models. A new Wan variant should look like the existing Wan guides; a new Flux variant should look like the existing Flux guides. Consistency across siblings matters more than novelty.

3a. Four rules that came out of measurement, not taste

These were established by A/B-ing guides against the live analyzer (see docs/prompt-analysis-audit-2026-08-05.md). Each one names a failure that was observed in output, not predicted from reading.

• Never put an unconditional absence check in Guidelines:. A line like "Suggest audio direction if missing" or "Flag missing camera direction" tests for something real prompts essentially never contain, so it fires on every request and consumes the 3-recommendation budget before anything prompt-specific is reached. Measured on minimaxh3: 10 of 12 recommendations were things the prompt already had. Guidelines are for flags whose trigger is visible in the user's prompt: weight syntax present, negative phrasing present, keyword list rather than prose.

• Do not "demote" the absence check into a rewrite property — delete the mention. The obvious fix for the rule above is to restate it in Ecosystem-specific rules: as "the enhanced prompt should carry camera direction. This shapes the rewrite; do not raise it as a separate recommendation." That does not suppress the topic, and four measurements on 2026-08-10 say so:

  Guide	Topic	Carrying the "do not raise it" line	After deleting the mentions
  seedance	audio	98%	70 / 72% (moved by samples, not the line)
  wanvideo-25-t2v	camera	89%	41 / 50%
  wanvideo-22-t2v-a14b	camera	89%	35%
  happyhorse	camera	84% (v2, softened)	48% (v3, deleted)

  happyhorse is the controlled case: same guide, same samples, the only difference being softened-vs-deleted — camera 84% → 48% and avg recs 3.67 → 2.52. It is the same mechanism as the parameter-guard lesson below: naming a topic raises it, whatever the sentence says about it, and a rewrite-property line still names it — often while explicitly instructing the model to add it ("adding one when the user has not named any").

  So: strip the topic down to at most one purely

Content truncated.