ps-fundamentals

name	ps-fundamentals
description	Photoshop MCP mandatory workflow rules (R1-R7), coordinate system, layer stack order, canvas rotation, selection fundamentals, mask fundamentals (white=visible black=hidden), smart objects vs rasterized layers, fill opacity vs layer opacity. LOAD THIS FIRST for any Photoshop operation.
license	MIT
compatibility	opencode
metadata	{"audience":"designers","workflow":"photoshop-mcp"}

PHOTOSHOP DESIGNER SKILL — FUNDAMENTALS & RULES

Execute ANY Photoshop design effect perfectly on first try — zero trial-and-error.

WHEN TO USE THIS SKILL

Load this skill FIRST for any Photoshop operation. It contains the mandatory rules and core concepts needed before using any other Photoshop skill.

---

MANDATORY WORKFLOW RULES

ALWAYS use a DEDICATED TOOL when one exists. NEVER use execute_batchplay for an operation that has its own tool. There are 323 dedicated tools. Check this catalog FIRST. ALWAYS verify visual results after multi-step operations using get_layer_image (single layer) or get_document_image (full composite). Do NOT assume success from return status alone. ALWAYS pass layer_id when calling execute_batchplay. The tool has an optional layer_id parameter that ensures the correct layer is targeted. Without it, batchPlay may silently operate on the wrong layer. For ROUNDED CORNERS on any element: use draw_rectangle_shape(corner_radius=N) + set_layer_properties(is_clipping_mask=true). Do NOT attempt rounded rect selections via batchPlay — the corner radius keys are unreliable. RASTERIZE layers before applying filters. Text, Shape, and Smart Object layers will fail silently with most filters. Always duplicate_layer first (preserve original), then rasterize_layer on the copy. SCREEN blend mode requires BLACK background, not transparent. White on TRANSPARENT + SCREEN = invisible. White on BLACK + SCREEN = correct. execute_batchplay is the LAST RESORT escape hatch. Use it only when: - No dedicated tool exists for the operation - You need to combine multiple atomic operations in one call - A dedicated tool has a known limitation for a specific parameter

---

§1 FUNDAMENTALS

1.1 COORDINATE SYSTEM

• Origin (0,0) = top-left corner of canvas
• X increases RIGHT, Y increases DOWN
• Layer bounds: {left, top, right, bottom} in pixels from origin
• Center of canvas: (width/2, height/2)

1.2 LAYER STACK ORDER

• Layers are drawn bottom-up — bottom layer renders first, top layer renders last
• move_layer(position="TOP") = above all (visually on top)
• move_layer(position="BOTTOM") = below all (visually behind)
• New layers appear ABOVE the currently active layer
• Adjustment layers affect ALL layers below them unless clipped

1.3 CANVAS ROTATION RULES

• rotate_canvas rotates the entire document including all layers
• Rotation is destructive — pixels are resampled
• Always rotate back by the exact negative amount
• Plan filter directions BEFORE rotating — see Wind direction table §7.2

1.4 SELECTION FUNDAMENTALS

• Selection = marching ants defining which pixels are affected
• Feather = soft edges (pixels partially selected)
• Selection MUST exist before: fill_selection, delete_selection, content_aware_fill, generative_fill, add_layer_mask_from_selection
• select_all = entire canvas, clear_selection = deselect everything
• Selections are per-document, not per-layer

1.5 MASK FUNDAMENTALS

• Layer mask = grayscale image controlling layer visibility
• White = fully visible, Black = fully hidden, Gray = partially visible
• add_layer_mask_reveal_all = white mask (everything shows)
• add_layer_mask_hide_all = black mask (everything hidden)
• fill_mask_with_gradient = smooth transition between visible/hidden
• To paint on mask: select_layer_mask → brush/fill → select_layer_rgb to go back
• Gradient mask direction: start point = BLACK (hidden), end point = WHITE (visible)

1.6 SMART OBJECTS vs RASTERIZED LAYERS

• Smart Objects preserve original data but BLOCK most filters
• Rasterize BEFORE applying: Wind, Wave, Twirl, Spherize, Crystallize, Noise, Sharpen, etc.
• Text layers must be rasterized before ANY filter
• rasterize_layer is irreversible — always duplicate first

1.7 FILL OPACITY vs LAYER OPACITY

• Layer Opacity = affects layer content + ALL layer styles
• Fill Opacity = affects ONLY layer content, NOT layer styles (drop shadow, glow, bevel stay at full)
• Key trick: Fill 0% + layer styles = invisible content with visible effects (used for glass text)
• Set via: set_layer_properties(layer_id=X, fill_opacity=0)

---