Beutl Agent Look Effect Chain

Use this skill when an agent needs to apply color, blur, shadow, stylization, or other effect chains consistently across Beutl elements.

Workflow

1. Derive the look direction before changing colors or effects.
   • Record why the subject, existing scene, audience, mood, and delivery surface lead to this hue family, tonal seed, material vocabulary, and motion/effect vocabulary. Unjustified choices are disallowed; if a hue, tone, or effect language cannot be explained, derive again.
   • For original or broad look changes, call list_creative_directions and compare recentToAvoid; the look must differ in palette family, structure, and motion/effect vocabulary unless the repeat is intentional and recorded.
2. Call derive_palette with baseHueDegrees, tonalSeed, harmonyScheme, the recorded derivationReason, and the look's structuralSignature. Resolve any hue-band or structural repeat warning by revising the look direction, or record why the repeat is intentional before patching.
3. If the look touches a background, surface, atmospheric layer, glow field, vignette, or depth treatment, call get_background_grammar and record the chosen base/depth/motion slots. The minimum depth contract is background/midground/foreground; missing a band requires a recorded reason.
4. Call get_schema for the target effect/drawable category and read parameter ranges, defaults, animatable flags, and expression support.
5. Call read_document and identify the element/object handles to modify.
6. If source-code reading is allowed, use beutl-agent-source-grounding before changing effect-unit, transform, bounds, text measurement, backing-plate alignment, render-scale, or live-session behavior.
   • Read .claude/skills/beutl-agent-source-grounding/SKILL.md, then use narrow rg/read passes over the source and tests it identifies.
   • Record a sourceGrounding note with assumption, evidence, rule, and uncertainty before the first relevant apply_edit.
   • If the user explicitly forbids source reading, skip this step and record that limitation.
7. Before changing the look, record the look brief in notes or the response:
   • directionContract: objective, audience, emotional temperature, brand posture, delivery surface, one-sentence look promise, and the recorded reason for hue, tone, material, and motion/effect vocabulary.
   • paletteRoles: derived bg-base, bg-accent, foreground, text-primary, and accent; include the derive_palette contrast checks and warnings.
   • backgroundGrammarPlan: if applicable, the selected base layer, depth layer A, optional depth layer B, motion slot, and the Elements that satisfy background/midground/foreground.
   • deviationReason: required for any hand-picked color, skipped derive_palette, skipped background grammar, ignored repeat warning, missing depth band, or static background.
   • contrastPlan: how text, backing plates, and focal objects stay readable.
   • hierarchyPlan: what remains the primary focal point after the look change.
   • effectIntentPlan: the job of each effect chain, such as material texture, hierarchy separation, transition energy, color grade, or text legibility.
   • roleTagPlan: preserve or add intent tags such as [role:background], [role:text-backing], and [role:decorative] when the look change touches plates, decorative rectangles, or text readability.
   • structurePreservationPlan: keep ordinary Elements to one EngineObject; do not add extra Objects to an Element unless it is an intentional IFlowOperator chain such as DrawableGroup, DrawableDecorator, SoundGroup, or Scene3D.
   • shapeMotionIntentPlan: if the look change adds or animates foreground shapes, name their role, purpose, and motion intent before patching. Do not add abstract glint/glow/aperture/lens ellipses as foreground decoration; use parseable strokes, particles, letter fragments, editor/timeline marks, masks, media, GeometryShape vector figures, or procedural texture instead.
   • gradientFalloffPlan: when changing ambient/aperture/glow backgrounds, use at least three falloff stops, wider alpha/color transitions, a real Blur/SKSL texture, or procedural texture so color boundaries do not read as hard bands.
   • transformPreservationPlan: if a target object has animated transform children plus static rotation/skew/scale, state whether the motion is screen-space or local/rotated-space and preserve the existing TransformGroup.Children order unless the change explicitly fixes it.
8. Prefer a merge-patch for look changes:
   • Preserve existing element timing and unrelated properties.
   • Patch only the target Objects, effect collections, and property values.
9. Call apply_edit in the smallest useful look/effect stage and inspect valid, changes, validation, and createdIds before continuing.
10. Resolve all validation_rejected, unknown_type, fallback-object, and stale-handle errors from apply_edit by reading get_schema/read_document and retrying only that small stage.
11. For file sessions, call save_project after a successful major look stage. For LiveEditor sessions, record the save_project/read_operation_status message that saving is not required or supported by the toolkit.
12. Run preview_quality_risks when the look change adds/removes plates, changes text/background contrast, introduces foreground RectShape objects, adds abstract decorative light shapes, changes ambient/glow gradients, or changes short-lived typography.
13. Render stills before and after the most visible transition points. Confirm the primary focal point, text contrast, backing plate fit, and whether each visible effect still serves its named job.
14. Run evaluate_edit_quality; resolve all critical/major issues introduced by the look change before export. Prefer final_preflight before export when available.

Contrast Exemplars - derive, don't copy

These examples describe relationships to derive with derive_palette; they are not literal palettes to reuse.

• Good: text-primary clears 4.5:1 against both bg-base and bg-accent; the accent is saturated but small and clears 3.0:1 against bg-base.
• Good: a light-toned look uses dark low-saturation text, a calmer foreground material color, and one small high-chroma motion accent.
• Bad: changing only hue while keeping text and background at similar luma fails readability even when the colors feel different.
• Bad: stacking several saturated glows at the same lightness creates competition; lower support saturation or make one role clearly dominant.
• Bad: dark teal plus cyan/magenta neon is a repeat-prone default and needs an explicit brief reason before use.

Effect Chain Rules

• Use PascalCase property keys exactly as exposed by get_schema.
• Treat effect arrays as id-keyed arrays when entries have Id.
• Reorder effects with $index, $after, or $before; never delete and reinsert just to move an existing effect.
• Use in-range values from the schema. A coerced value is a signal to retry the same small apply_edit stage with the exact accepted value.
• Use concrete serialized color values such as #ffffb34d only after deriving them from derive_palette; do not use palette names such as Amber.
• Any color outside the derived palette roles requires a recorded reason and a contrast check against the affected background role.
• For Pen, brush, transform, animation, and effect values, copy the schema/read-document object shape with a concrete $type discriminator instead of inventing shorthand fields.
• When editing a moving rotated object, treat TransformGroup.Children order as behavior, not formatting. For screen-space drift with a tilted object, static orientation transforms should precede the animated TranslateTransform; for local-axis motion, record that intent and verify the result with still/motion samples.
• Keep effect types installed and discoverable; unknown_type means the effect cannot be used in this runtime.
• Call list_effects early and pick by intent instead of collapsing the vocabulary to blur/shadow/ColorShift: DisplacementMapEffect (warp/heat-haze/ripple), PathFollowEffect (move a drawable along a path), StrokeEffect (outline any drawable/text), Lighting, PerlinNoise (procedural texture), LutEffect/ColorGrading/Curves (grades), MosaicEffect, InnerShadow/FlatShadow. Confirm the exact property surface with get_schema before authoring.
• For masked reveals, knockouts, and alpha mattes, use Drawable.BlendMode Porter-Duff modes (SrcIn, DstIn, SrcOut, DstOut, Modulate) against the content below in the same flow (scope the matte with a DrawableGroup/DrawableDecorator so it does not affect the whole frame), and the Clipping FilterEffect (animatable Left/Top/Right/Bottom) for rectangular wipes/crops. Source-ground the compositing rule and verify with render_still before relying on it.
• Do not stack effects decoratively. Every effect must serve material texture, hierarchy separation, transition energy, color grade, or text legibility.
• Avoid three or more foreground objects with dense three-effect stacks unless the brief explicitly asks for a maximal or degraded look and the reason is recorded.
• Do not create foreground RectShape accents for glints, slashes, or rhythm marks unless the plain rectangular shape is intentional. Prefer non-rectangular accents, strokes, procedural texture, or tag them [role:decorative] and keep them shot-limited.
• Do not introduce unclear decorative shapes as a look fix. Any large or animated foreground shape must be named with a role and motion job such as beat sweep, scan texture, pulse reveal, transition wipe, or text backing.
• Do not introduce abstract foreground light blobs named only as glint, glow, aperture, lens, glass, reflection, or refraction. If viewers cannot parse what the shape represents without reading the layer name, replace it with a concrete visual system or move the light into the background with soft falloff.
• For ambient/aperture/glow gradients, avoid hard two-stop falloff. Use at least three gradient stops, wider offsets, Blur/SKSL texture, or a procedural surface treatment.
• Do not add a second Object to an ordinary Element while applying a look. Split the visual into its own Element unless the target Element is an intentional IFlowOperator chain.
• Prefer restrained color grading, texture, and subtle depth before heavy glow, blur, or card-like shadows.
• Avoid creating the dark teal plus cyan/magenta palette unless the user explicitly asks for that look and the recorded derivation reason justifies it.

Consistency Rules

• For a shared look, use the same property values across matching shots unless the brief names exceptions.
• Preserve source media and audio bindings unless the user asks to replace them.
• Verify with render_still; do not judge a look only from the JSON document.
• Preserve the designed visual hierarchy. A look change should not make supporting effects, panels, or labels compete with the primary focal point.
• Preserve Element/Object structure by default. Of the quality categories, only typographyReadTime, elementStructure, motionContinuity, and layerDensity when authored motion-graphics foreground density falls below half of a supplied quantitativePlanSheet target can fail the gate; shapeIntent, motionIntent, decorativeShapeClarity, gradientFalloff, tempoRhythm, paletteHarmony, backgroundRichness, and non-plan-violation layerDensity are advisory guidance. A deliberate, brief-justified deviation (stillness, negative space, monochrome / low-contrast, hard cuts, glow / atmospheric shapes, minimal density) is allowed: record the intent and set the matching intent flag (allowStillness, allowDenseText, allowMultiObjectElements, allowMonochrome, allowMinimalDensity) or [role:...] tag so the check downgrades to advisory. Pass relaxAesthetics to suppress the non-blocking aesthetic/pacing advisories in bulk when the brief is deliberately minimal — it does not clear the blocking checks (typographyReadTime, elementStructure, motionContinuity, supplied-plan layerDensity). Block only genuine accidents: unreadable text, structural errors with no recorded intent, low motion with no recorded intent, or a gate failure with no documented justification.
• If text uses a backing plate, keep text and [role:text-backing] plate timing, center, and padding aligned after the look change.
• For default-aligned text and shape backing plates, use the source-grounded center-offset coordinate rule: TranslateTransform(0, 0) means centered, and (x, y) offsets the object center from the scene center unless AlignmentX=Left/AlignmentY=Top is deliberately set.
• Use measure_object_bounds for text/backing-plate or shape alignment changes before judging the result from still renders.
• Before exporting or finishing a look change, run a transform-order audit on any object whose summary shows nested transform animation and a static rotation/skew/scale. If the order does not match the recorded motion intent, patch only the transform child ordering and rerun the representative still/motion check.
• Do not leave preview_quality_risks, evaluate_edit_quality, or final_preflight critical/major blockers unresolved.