Agent Bridge for Photoshop Skill

Product summary

Agent Bridge for Photoshop is a local automation stack for Photoshop that provides a stable command surface, operation payload schema, and runtime bridge between CLI workflows and Photoshop UXP APIs. Agents use the psagent CLI to control Photoshop documents, layers, and operations through JSON operation envelopes. The bridge daemon runs on http://127.0.0.1:43120 and brokers calls between the CLI and a UXP plugin inside Photoshop. Key files: .psagent.json (project config), ~/.config/psagent/config.json (user config), operation envelope JSON payloads. Primary CLI: psagent with subcommands for sessions, documents, layers, operations, rendering, checkpoints, and diagnostics. MCP server available via psagent mcp-serve for agent tool integration.

When to use

Reach for this skill when:

Automating Photoshop document and layer operations (create, rename, delete, style, export)
Building reproducible creative workflows with deterministic operation sequences
Managing document state with checkpoints and rollback capabilities
Querying document structure (manifest, layers, properties)
Exporting renders (PNG/JPG) from Photoshop programmatically
Testing operation payloads before production use (dry-run mode)
Integrating Photoshop automation into agent-driven workflows via MCP tools
Debugging operation failures and validating bridge connectivity

Quick reference

Essential CLI commands

Command	Purpose
`psagent session start [--profile <name>]`	Start a bridge session
`psagent bridge status`	Check daemon and UXP connection
`psagent doc open <path>`	Open a Photoshop document
`psagent layer list [--match <regex>]`	List layers in active document
`psagent op apply -f <ops.json> [--checkpoint] [--dry-run] [--op-delay-ms <ms>]`	Apply operation envelope
`psagent op -h`	List available operations and quick catalog
`psagent op <command> -h`	Show operation arguments, aliases, and example payload
`psagent render --format png\|jpg --out <path>`	Export active document
`psagent checkpoint list`	List saved checkpoints
`psagent checkpoint restore <id>`	Restore document to checkpoint
`psagent doctor`	Diagnose health and connectivity
`psagent mcp-serve`	Start MCP server for agent tools

Discover operation contracts from CLI help

Use these before writing an ops payload:

psagent op -h to see the full operation list/capability catalog.
psagent op <command> -h to see required args, supported args, notes, aliases, and a copy/paste JSON example for that operation.

Working patterns (quality-first)

Centered headline pattern: create or style text with position.x = 0, set maxWidth to the canvas/section width, and set alignment: "center" instead of hand-tuning x values.
Baseline positioning pattern: createTextLayer.position.y is the text baseline (not visual top). For large text, set a lower baseline and iterate with quick renders.
Readable text pattern: set explicit text color via textColor/color and add setLayerEffects drop shadow or stroke for contrast on busy photos.
Shape polish pattern: use createShapeLayer with cornerRadius and fillType: "gradient" for modern buttons/badges.
Photo frame pattern: place photo layer above a frame shape and apply createClippingMask to constrain photo bounds.
Single-transaction pattern: keep all dependent operations for one document in the same op apply call to avoid active-document drift between CLI invocations.
Iterative composition pattern: render after each logical group (background, photo, text, accents, CTA) and adjust before adding the next group.
Pacing pattern for stability: when Photoshop is unstable under heavy automation, set safety.opDelayMs (or CLI --op-delay-ms) to add a short delay between ops (for example 80-200ms).

BatchPlay recipes (high-friction cases)

Preserve text style while changing color: if using textStyleRange, include the full style payload (fontPostScriptName, fontName, fontStyleName, size with unitDouble/pointsUnit, and color) because Photoshop replaces style objects rather than merging.
Prefer first-class text ops when possible: use createTextLayer/setTextStyle for normal font/size/color/alignment workflows. Reserve batchPlay for gaps not covered by first-class ops.
Descriptor units are explicit: numeric descriptor values often require { "_obj": "unitDouble", "_unit": "pointsUnit", "_value": <number> } (or other unit enums) instead of raw numbers.

Global flags

Flag	Purpose
`--json`	Output JSON format
`--dry-run` / `-n`	Preview without mutation
`--checkpoint`	Create checkpoint before operation
`--timeout <ms>`	Override request timeout
`--profile <name>`	Use named configuration profile
`--config <path>`	Specify config file path
`-v, --verbose`	Verbose logging
`-q, --quiet`	Suppress output

Configuration precedence

Flags override environment variables, which override session config, which override project config (.psagent.json), which override user config (~/.config/psagent/config.json), which override defaults.

Environment variables

Variable	Purpose
`PSAGENT_PROFILE`	Default profile name
`PSAGENT_TIMEOUT_MS`	Request timeout in milliseconds
`PSAGENT_PLUGIN_ENDPOINT`	UXP plugin endpoint (default: `http://127.0.0.1:43120`)
`PSAGENT_DRY_RUN`	Enable dry-run mode by default

Operation envelope structure

{
  "transactionId": "tx-001",
  "doc": { "ref": "active" },
  "refs": {
    "hero": "layer_123"
  },
  "ops": [
    { "op": "createLayer", "name": "Draft", "ref": "draftLayer" },
    { "op": "renameLayer", "target": "$draftLayer", "name": "Draft v2" }
  ],
  "safety": {
    "dryRun": false,
    "checkpoint": false,
    "rollbackOnError": false,
    "onError": "abort"
  }
}

MCP tools (for agent use)

Tool	Purpose
`photoshop_capabilities`	Return adapter mode and capability map
`photoshop_open_document`	Open document by local path or URL
`photoshop_get_manifest`	Return document structure and metadata
`photoshop_query_layers`	List layers with optional regex filter
`photoshop_apply_ops`	Apply operation envelope payload
`photoshop_render`	Export active document to PNG/JPG
`photoshop_checkpoint_restore`	Restore document to checkpoint by ID
`photoshop_events_tail`	Fetch recent adapter events

Decision guidance

When to use dry-run vs. checkpoint vs. rollback

Scenario	Use	Why
Testing operation syntax before production	`--dry-run`	Validates schema without mutating document
Want to undo if operation fails	`rollbackOnError: true`	Restores document to pre-operation state on error
Need to save state before risky operations	`--checkpoint`	Creates named snapshot for manual restore
Batch operations with per-op error handling	`onError: "continue"`	Skips failed ops, continues with rest
Single operation must not fail	`onError: "abort"`	Stops entire transaction on first error

When to use abort vs. continue error policy

Scenario	Use	Why
All operations depend on previous success	`onError: "abort"`	Prevents cascading failures
Some operations are optional/independent	`onError: "continue"`	Maximizes output even if some ops fail
Cleanup operations must run regardless	Per-op `onError: "continue"`	Ensures deleteLayer runs even if earlier ops fail

When to use CLI vs. MCP server

Scenario	Use	Why
Direct command-line automation	`psagent` CLI	Simple, synchronous, full control
Agent-driven workflows	`psagent mcp-serve`	Exposes tools to agent clients via JSON-RPC
Integration testing	`psagent` CLI with `--json`	Structured output for assertions
Real-time monitoring	`psagent events tail`	Stream recent operations and errors

Workflow

Typical task: Apply operations to a Photoshop document

Start the bridge stack (one-time setup):
- Terminal A: psagent bridge daemon (runs on 127.0.0.1:43120)
- Terminal B: Reload UXP plugin in Photoshop (or use npm run bridge:reload)
- Terminal C (optional): psagent mcp-serve if using agent tools
Verify connectivity:
- Run psagent bridge status — confirm "Connected" and queue is empty
- Run psagent doctor — check health, exit code 0 = OK
Open a document:
- psagent doc open ./path/to/file.psd
- Verify with psagent layer list to see current structure
Create operation envelope:
- Write JSON file with ops array, safety settings, and refs for layer targeting
- Use $refName syntax to reference layers created earlier in same transaction
- Keep all dependent ops in one envelope for the same document
Test with dry-run:
- psagent op apply -f ops.json --dry-run
- Verify schema is valid and operation names are recognized
- Check result for applied: 0 (no mutations)
Apply with checkpoint:
- psagent op apply -f ops.json --checkpoint
- Inspect result for applied, failed, aborted counts
- If errors, check failures[] array for details
Validate output iteratively:
- After each logical block, render and inspect:
  - psagent render --format png --out ./preview-step-<n>.png
- Confirm structure and refs:
  - psagent layer list
- Inspect document properties as needed:
  - psagent doc manifest
Rollback if needed:
- psagent checkpoint list to see available snapshots
- psagent checkpoint restore <id> to revert to checkpoint

Typical task: Use MCP tools from an agent

Start psagent mcp-serve in a terminal
Agent client connects via JSON-RPC over stdio
Call tools in order:
- photoshop_capabilities — confirm adapter is ready
- photoshop_open_document — open target file
- photoshop_get_manifest — inspect structure
- photoshop_query_layers — find specific layers
- photoshop_apply_ops — execute operation envelope
- photoshop_render — export result
- photoshop_checkpoint_restore — undo if needed

Common gotchas

Daemon not running: psagent op apply will timeout if psagent bridge daemon is not running on 127.0.0.1:43120. Always start daemon first.
UXP plugin disconnected: psagent bridge status shows "Disconnected" if Photoshop UXP panel is not loaded. Reload plugin with npm run bridge:reload or manually in Photoshop.
Text style confusion: createTextLayer already supports styling/fitting args like font, fontName, fontSize, textColor, alignment, maxWidth, and overlap controls. Use setTextStyle for post-create edits or re-styling existing text layers.
Text baseline mismatch: createTextLayer.position.y is baseline-aligned. If text appears clipped or too high, move the baseline down and re-render.
BatchPlay textStyleRange resets styles: textStyleRange[*].textStyle replaces style values; it does not patch them. Include full style fields (font + size + color) in the descriptor.
Active document drift across commands: Photoshop can switch active documents between separate CLI calls. Put dependent operations in one op apply payload and set doc.ref.
saveDocumentAs key confusion: saveDocumentAs uses output for destination path. path is not a valid key.
Layer references fail silently: Use $refName syntax to reference layers created in the same transaction. If reference is wrong, operation may target wrong layer or fail. Validate with --dry-run first.
Rollback doesn't work as expected: rollbackOnError: true uses best-effort history snapshot strategy. Some Photoshop actions may not be fully reversible. Test rollback behavior in dry-run before relying on it.
Checkpoint restore is slow: Restoring large documents from checkpoint can take seconds. Don't call checkpoint restore in tight loops.
Schema validation errors are silent in JSON output: Check result.failures[] array for validation errors. Exit code will be non-zero if schema validation fails.
Operation names are case-sensitive: Use exact canonical names like createLayer, not CreateLayer or create_layer. Alias forms (e.g., layer.rename) map to canonical names.
Timeout on slow operations: Large document operations may exceed default timeout. Use --timeout <ms> to increase limit for batch operations.
Dry-run still requires valid document: --dry-run validates schema but still needs an open document. Session must be active.

Verification checklist

Before submitting work with Agent Bridge for Photoshop:

Resources

Comprehensive navigation: https://agent-bridge-for-photoshop.jaredverdi.com/llms.txt — full page-by-page documentation index
CLI reference: https://agent-bridge-for-photoshop.jaredverdi.com/reference/cli-reference — all commands, flags, and exit codes
Operation envelope: https://agent-bridge-for-photoshop.jaredverdi.com/reference/operation-envelope — payload schema, refs, safety controls, error handling
Operation arguments and examples: https://agent-bridge-for-photoshop.jaredverdi.com/reference/operation-arguments-and-examples — operation parameters and real payload examples
Real-world workflows: https://agent-bridge-for-photoshop.jaredverdi.com/guides/real-world-workflows — patterns for agent-driven creative automation

For additional documentation and navigation, see: https://agent-bridge-for-photoshop.jaredverdi.com/llms.txt