Split Image Assets

Mission

Turn a source image into a reusable, inspectable asset package.

This skill is not a one-shot image prompt. Its main output is an asset package with transparent PNGs, masks, cleaned background, metadata, previews, and QA evidence. A 2x2 sprite sheet is only a preview artifact.

This skill is not a professional segmenter. It does not promise production-grade automatic segmentation by itself. Its job is to receive, normalize, inspect, package, and validate results from professional upstream tools or manual workflows. If mature upstream extraction is unavailable, the run must stay in draft-only packaging rather than claiming production extraction.

Structure the work as four layers: capability preparation, whole-image planning, segmentation/generation execution adapter, and quality adjudication. Capability preparation decides whether the run can be production-capable. Whole-image planning decides which objects are worth raster effort at all and which route each object should follow. The execution adapter normalizes professional upstream outputs or approved generated candidates into package-owned assets, masks, and provenance. Quality adjudication separates structural validation from visual quality warnings, user/manual acceptance, and production reuse claims.

Before extraction, explicitly state the quality target tier for the run:

• structural-valid: package contract, provenance, previews, and evidence are complete
• usable-draft: candidate assets are organized and reviewable, but not yet signoff-ready
• visual-acceptance-ready: current assets are intended to support final visual acceptance

Default Execution Contract

Conservative continuous execution is the default execution model. Keep the workflow moving unless a real stop condition is present.

Progress updates are commentary only. They report what is happening, what changed, and what remains, but they do not ask for confirmation by themselves and they do not pause execution.

Only the three formal stop classes may exit the workflow. Medium/high-risk semantic divergence is not a fourth stop class; it is the reason a branch may require a user-decision stop when the next choice would materially change package semantics, reuse boundaries, or acceptance claims and existing instructions do not settle it.

Every exit must include all of the following:

• Why This Needs a Human
• Recommendation
• Options and Impact
• What I Will Do After Confirmation

Iron Rules

ANALYZE BEFORE EXTRACTING
EXTRACTION CAPABILITY GATE
PREFLIGHT TOOLING RECOMMENDATION GATE
DO NOT START EXTRACTION BEFORE TOOLING PREFLIGHT IS REPORTED AND RECORDED
WHOLE-IMAGE PLANNING BEFORE EXPENSIVE OBJECT WORK
GRANULARITY ALIGNMENT GATE
GENERATION ROUTING GATE
CONFIRMATION GATE
PROGRESS UPDATES ARE COMMENTARY, NOT CONFIRMATION GATES
ONLY THREE EVENT TYPES MAY PAUSE EXECUTION
NO FORMAL GATE MAY BE SATISFIED BY AGENT DEFAULTING
INFERRED-FROM-USER MEANS EVIDENCE-BACKED USER INTENT, NOT AGENT GUESSING
PROFESSIONAL SEGMENTER FIRST
SEMANTIC LAYERS BEFORE RECTANGLES
QUALITY-GATED PIPELINE
DECISION SYNC BEFORE AMBIGUOUS SPLITS
DO NOT DEFAULT TO ONE-PASS EXTRACTION
REUSABLE ASSETS BEFORE PREVIEWS
TRANSPARENT PNGS ARE PRODUCTION ASSETS
SOURCE-SPACE MASKS ARE NORMAL
STAGE INTERMEDIATES
PREVIEWS ARE INSPECTION ARTIFACTS
NEVER HIDE UNCERTAINTY

Interaction State Machine

Execution only pauses in three cases:

• user-decision
• external-blocker
• formal-approval

Everything else stays in Running and should be reported as commentary only. Progress summaries, tool output notes, and “still working” updates are not confirmation gates and must not stop the workflow.

Use these states consistently:

• Running: analysis, import, preview generation, scoring, QA inspection, validation, and evidence capture
• AwaitingDecision: a real user choice is required and will change package semantics
• AwaitingExternalBlocker: the workflow cannot proceed without tools, outputs, credentials, installs, or another external prerequisite
• AwaitingApproval: the workflow has enough evidence to request a formal approval gate such as pilot approval, final acceptance, or candidate promotion
• Completed: the current run has reached a real terminal outcome

When the workflow exits from AwaitingDecision, AwaitingExternalBlocker, or AwaitingApproval, the stop message must include Why This Needs a Human, Recommendation, Options and Impact, and What I Will Do After Confirmation. Do not exit with a bare question.

Asset Value Scoring Gate

Asset value scoring happens before extraction. The goal is to decide whether an object should exist as a raster asset at all, not to justify extraction after the fact.

Apply an editability-first bias:

• ordinary text, button labels, numeric values, and form values should default to rebuild_downstream
• logo wordmarks, decorative text, and other visual-fidelity-critical text may route to extract_asset
• ambiguous high-complexity text-like objects should route to requires_user_confirmation

This is a normal running stage, not a default pause gate. Ordinary text defaults do not stop the workflow. Only a true requires_user_confirmation outcome should pause and ask whether the object should be rebuilt downstream or preserved as a visual asset.

Workflow

1. Read references/workflow.md.
2. Create or inspect the package directory.
3. Initialize the package with scripts/init_asset_package.py when a package does not already exist.
4. Run the Preflight Tooling Recommendation Gate before selecting a recipe or starting extraction:
   • run scripts/check_extraction_environment.py
   • report segmentation, matting, reconstruction, environment, production_capable, missing_for_production, missing_roles, recommended_installs, and why_it_matters
   • distinguish installed tooling, runtime-ready tooling, and production-ready capability
   • explain which missing upstream roles affect the run: detection, segmentation, alpha refinement/matting, and background reconstruction
   • proactively recommend installing or activating missing professional upstream tools
   • ask whether to continue with install-or-activate-tools, external-professional-outputs, or draft-packaging-only
   • record the decision in metadata.capability, metadata.confirmation.tooling_preflight, and metadata.decision_log[]
   • do not continue into extraction until this decision is recorded
5. Read references/pipeline-recipes.md and references/grounded-sam-pipeline.md and select an extraction recipe before extraction.
   • read references/default-route-chains.md when route planning needs a default provider chain
6. Run the Granularity Alignment Gate before cutting pixels:
   • module-level, component-level, atomic-layer, or production-editable reconstruction
   • high-signal subset or full-image batch strategy
   • text/labels/buttons extracted as images or rebuilt downstream as live text/UI
   • carrier/glyph split, grouping, or conditional policy
   • exact background recovery required or approximate background_clean.png accepted as needs-review
   • animation-ready independent layers required or static reuse enough
7. For complex UI or graphic compositions, start with a high-signal subset instead of trying to atomize the entire image at once. Good first-pass targets are logos, nav icons, status dots, pins, checkboxes, chart marks, badges, and other small foreground elements whose masks can be inspected clearly.
   • high-signal subset examples do not by themselves authorize choosing a micro-asset package; keep the package aligned to the confirmed semantic branch and resource_family
   • for complex UI, run a pilot object first and stop for confirmation unless the pilot gate is explicitly recorded as not-required
8. For UI, dashboard, badge, tile/glyph, or dense interface images, read references/ui-atomic-split.md and create a semantic split plan before extraction.
   • classify each target as ui-carrier, ui-glyph, carrier-glyph-pair, soft-edge-logo-brand-mark, outlined-illustration-logo, flat-support-plate, or photo-object-matte
   • choose the upstream orchestration and repair path from that object type before cutting pixels
9. Run the Asset Value Scoring Gate before extraction:
   • classify each candidate as text-like or non-text
   • assign text_role and text_render_class
   • score editability_score, visual_complexity_score, and asset_value_score
   • set decision_routing.recommended_action
   • resolve decision_routing.final_action
   • only extract a production raster asset when final_action=extract_asset
10. Create or refresh plan_manifest.json before formal extraction or generation:
    • record the whole-image planning state separately from metadata.json
    • record per-object planned_route
    • use the planning routes extract, reconstruct, generate, rebuild_downstream, and support_only
    • record route signals for recoverability_low, object_is_reconstruction_like, quality_target_high, and segmentation_cost_unfavorable
    • record attempt budgets, token budget hints, pilot grouping, and protected-object approval requirements
11. Run the Generation Routing Gate before expensive object work:
    • 3/4 route signals may continue directly to a generated-candidate setup when no protected-object rule blocks the route
    • 2/4 route signals require a one-question user-decision stop
    • 0-1/4 route signals continue on the non-generation path
    • missing segmentation tooling alone must not justify a generated delivery path
12. Choose the default provider chain for the resolved route before broad upstream execution:
    • use references/default-route-chains.md
    • choose the route default first, then apply any explicit object_type override
    • this is the route default plus object_type override rule for provider selection
    • allow plan_manifest.provider_preferences to override the default only when the preferred provider is valid for the route
    • write a package-owned provider plan summary with scripts/describe_provider_plan.py before broad request generation so the selected provider, selection source, alternative providers, capability fit, and expected consume mode are explicit
    • write provider work-item status with scripts/describe_provider_work_items.py so each object has an explicit next action such as prepare-generation-brief, prepare-provider-request, await-provider-result, or consume-provider-result, without losing the capability-fit explanation
    • build provider request manifests with scripts/prepare_provider_request.py; --provider-id is optional when the default chain is acceptable
    • provider requests and results must satisfy the selected provider's registry-specific input/output contract, not just the generic JSON schema
    • for generate routes, write a package-owned brief first with scripts/prepare_generation_brief.py
    • keep provider requests and results under _staging/providers/<provider-id>/<object-id>/
    • record provider result manifests with scripts/record_provider_result.py
    • do not let provider bridge scripts write metadata.json directly; final package truth still changes only through explicit consumers
    • treat the provider bridge layer as the standard path between planning and import/compare/promotion
    • consume provider results through scripts/consume_provider_result.py when the result should enter import or staged-candidate flow
    • when one staged provider result is unambiguous, consume_provider_result.py may infer --provider-id and --mode from the bridge result plus plan defaults
    • for external-manifest providers, prefer artifacts.provider_manifest plus consume_provider_result.py --mode import-manifest
13. Analyze the source image before extraction:
    • visual hierarchy from background to foreground
    • main object
    • secondary objects

• background type
• occlusion
• complex edges
• transparent, reflective, fuzzy, smoky, or low-contrast regions
• recommended split plan

14. When UI elements combine a carrier shape and a symbol, split them as tile/badge/panel background plus foreground glyph/symbol when independent reuse or clean edge review matters.
15. When the split plan has an ambiguous decision point, an uncertain text-like preservation choice, or a subjective reuse boundary, run the appropriate confirmation gate before extracting. Read references/confirmation-prompts.md for grill-me style prompt templates.

• only real user decisions, genuine external blockers, and formal approvals may pause execution
• if prior instructions already settle the branch, record the evidence-backed decision instead of asking again
• ordinary progress updates remain commentary and do not pause execution

16. Read references/quick-contract.md for the short contract view, then references/asset-package-contract.md when you need the full package contract. Update metadata.json with the visual hierarchy, recommended split plan, extraction_pipeline, and object inventory.

• record metadata.granularity.mode, metadata.granularity.user_confirmed, and metadata.granularity.notes
• for UI or dense compositions, also record metadata.granularity.scope_strategy, text_handling, carrier_glyph_policy, background_expectation, and layer_independence
• record per-object value_scoring, decision_routing, rebuild_intent, and text_semantics
• record object asset_class and reuse_status so draft candidates, support layers, and production-ready atomic assets cannot be confused

17. Produce or collect reusable assets:
    • transparent PNGs for individual objects
    • source-space masks
    • cleaned background
    • optional shadows and grouped object layers

• for UI carriers, use scripts/generate_ui_carrier_candidates.py when reconstruction candidates are needed
• for hard-edge UI glyphs, use scripts/generate_ui_glyph_cleanup_candidates.py when cleanup variants are needed
• for small assets under roughly 128 px, prefer scripts/upscale_repair_downscale.py before final cleanup when quality matters
• use scripts/score_candidate_assets.py before compare when candidate count or quality variance is high - for generated-route objects, create a package-owned generation brief before generation begins and keep generated output in candidate state until compare/promotion/acceptance evidence exists

18. Put external model outputs, candidate masks, refinement files, temporary manifests, generation briefs, and provider bridge request/result manifests in _staging/ while active, then _archive_intermediate/ when retained for traceability.

• use scripts/archive_intermediates.py when you want a deterministic archive step
• use scripts/describe_candidate_work_items.py when staged repair candidates exist and you need an explicit next step for compare versus promotion

19. Normalize professional upstream results with scripts/import_external_assets.py. Treat this as the default production path:

• professional upstream
• scripts/import_external_assets.py
• scripts/build_previews.py
• scripts/build_quality_previews.py
• scripts/record_quality_review.py
• scripts/validate_asset_package.py
• scripts/export_asset_manifest.py

20. Record per-layer segmentation quality evidence: semantic boundary, mask source, alpha source, edge checks, background residue checks, and reuse readiness.
21. Use scripts/record_quality_review.py to record semantic analysis, quality gates, object quality checks, formal gate decisions, and manual QA status after inspection instead of hand-editing JSON.

• use formal gate writes only for real decision/approval state
• keep commentary and review progress out of metadata.decision_log[] and metadata.confirmation

22. Build inspection previews with scripts/build_previews.py.
23. Build segmentation-quality previews with scripts/build_quality_previews.py.
24. Run scripts/audit_visual_quality.py for warning-only checks such as hard alpha edges, loose crops, large masks, and support plates miscounted as atomic assets.
25. Read references/qa-standards.md and inspect the package.
26. Validate structure with scripts/validate_asset_package.py.
27. Export a downstream layer manifest with scripts/export_asset_manifest.py after validation.
28. Read references/manual-review.md before assigning pass, needs-review, or blocked.

Script Boundaries

The bundled scripts are deterministic packaging helpers. They do not perform segmentation, matting, inpainting, object recognition, or AI image generation.

Use external image tools, AI image editing, manual editing, or user-provided cutouts for the actual extraction work. Good default pipelines are Grounded-SAM/SAM2 style detection and segmentation, matting refinement with rembg/BiRefNet/RMBG-style tools, inpainting or manual paint repair for hidden background, and Qwen-Image-Layered style RGBA layer proposals when the source is a designed composition. Then use this skill to keep the package structure, previews, metadata, and QA evidence consistent.

Pillow, OpenCV, and skimage are not primary segmenters for production splitting. Use them for alpha compositing, PNG writing, source-space mask persistence, repair/refinement helpers, preview generation, metadata, and manifest packaging. Do not silently downgrade a production request to bbox or coordinate crops when the mature segmenter path is missing.

scripts/import_external_assets.py is the standard adapter for professional upstream outputs. Use it to copy SAM2, rembg, BiRefNet, RMBG, Qwen-Image-Layered, LayerDiffuse, manual, or user-provided assets into the package while recording object metadata and upstream tool provenance. This adapter path is the primary production workflow, not a side path.

scripts/describe_provider_plan.py, scripts/describe_provider_work_items.py, scripts/prepare_provider_request.py, scripts/record_provider_result.py, scripts/consume_provider_result.py, and the provider bridge helpers standardize how planned object routes talk to upstream providers. Use them to normalize provider planning, work-item status, requests, and results into _staging/providers/ before import, compare, or promotion. This bridge layer should come before broad native-runner expansion.

scripts/describe_provider_plan.py is the planning-side bridge helper. Use it after plan_manifest.json is ready and before broad request generation so the package owns an explicit _staging/providers/provider_plan.json summary of route defaults, object-type overrides, valid plan preferences, selected providers, and alternative provider chains.

That provider-plan summary should also tell the operator whether the selected provider is preferred or merely tolerated for the current object type, which route-required capability tags it covers, and which consume mode is expected if the bridge succeeds.

scripts/describe_provider_work_items.py is the next-step bridge helper. Use it after provider planning to write _staging/providers/provider_work_items.json so each object records bridge artifact readiness, inferred consume mode when possible, and the recommended next command. Like the candidate-side surface, it should keep recommended_command for compatibility and may also expose recommended_command_variants[] plus a grouped recommended_task object when one provider bridge step has a stable task envelope.

scripts/prepare_generation_brief.py is the package-owned helper for generate routes. It writes _staging/generation_briefs/<object-id>.json plus _staging/generation_briefs/<object-id>_reference_inputs.json, and prepare_provider_request.py should fail closed for generate routes when those inputs do not exist yet.

For generated candidates, consume_provider_result.py --mode stage-candidate should also write a sibling provider-stage manifest under _staging/repair_candidates/<object-id>/. That stage manifest is the bridge between provider result evidence and later generated-reconstruction promotion.

scripts/check_extraction_environment.py is the preflight tooling recommendation gate. It checks optional module presence, runtime readiness, and production-ready capability for segmentation, matting, reconstruction, generation, and environment support. It does not install anything. For reconstruction, runtime support such as torch or onnxruntime is not enough by itself; only a dedicated reconstruction tool path should count as production_ready=true. For generation, raw image generation availability is not enough by itself; the provider must support object-level constrained generation plus transparent asset delivery before it can count as production_ready=true.

The capability report distinguishes module-installed from runtime-ready from production-ready states, lists missing_for_production, missing_roles, recommended_installs, and why_it_matters, and explains missing upstream role impact so an agent does not confuse partial local tooling with production readiness. manual_redraw_path is a human workflow, not automatic runtime capability, and should lead to manual redraw required or approximate reconstruction only, not to production_capable=true. Missing segmentation tooling alone must not be used as the reason to route an object into generated delivery.

scripts/build_quality_previews.py creates QA evidence images such as mask overlays and alpha inspection previews. These previews are inspection artifacts; they do not upgrade a package to pass by themselves.

scripts/audit_visual_quality.py creates _staging/quality/quality_audit.json and _staging/quality/qa_audit_contact_sheet.png. It is a warning-only visual audit for risks such as edge-halo, color-residue, detached-fragments, smear-artifact, over-flat-reconstruction, style-mismatch-reconstruction, hard-alpha-risk, support-layer-misclassified, and carrier-glyph-cross-contamination. It does not replace manual review and does not set qa.status=pass.

scripts/record_quality_review.py is the standard manual-review adapter. Use it to write metadata.analysis, append metadata.extraction_pipeline.quality_gates, update per-object quality_checks, set metadata.qa.status, and append qa_report.md notes after inspection. It refuses qa.status=pass unless every required object quality check is pass.

scripts/export_asset_manifest.py creates asset_manifest.json for downstream renderers, animation pipelines, design tools, or manual review. It records package-relative asset paths sorted by composition_order; it does not validate visual quality or replace metadata.json.

scripts/archive_intermediates.py moves active _staging/ outputs into _archive_intermediate/<run-id>/, writes an archive_manifest.json for traceability, and rewrites metadata.audit.quality_audit_path / previews.qa_audit_contact_sheet when those audit artifacts are archived.

scripts/compare_candidate_assets.py is the standard compare helper for high-risk repairs. Use it to turn staged repair candidates into a compare artifact plus metadata evidence before promotion.

scripts/promote_candidate_asset.py is the deterministic promotion helper for high-risk repairs. Use it when _staging/repair_candidates/ contains multiple staged candidate assets and one should become the current package-owned asset without hand-editing metadata.json. Candidate promotion should come from _staging/repair_candidates/, not an arbitrary package path.