How to use the GIMP Image Editing CLI agent skill

What does this agent skill let the AI agent do?

An agent skill is a folder with a SKILL.md file that tells an AI agent how to perform a task with a specific tool. This one teaches the agent to use cli-anything-gimp, a stateful command-line interface for image editing. The tool works on a project file (JSON) rather than an open window, so the agent can build an image step by step and keep its state between commands.

The skill covers creating a project, adding and arranging layers, resizing, scaling or cropping the canvas, applying filters, drawing text or rectangles, and exporting a finished image. The agent can request machine-readable JSON output so it can read results reliably, and it can undo or redo steps.

• Create and save project files
• Add layers from image files, set opacity, visibility, blend mode and offsets
• Resize, scale, crop the canvas and set colour mode and DPI
• Apply and adjust filters on a layer
• Draw text and rectangles, which are applied when the project is rendered
• Export PNG or similar images, with undo and redo along the way

How do you install the GIMP image editing agent skill?

Download the skill ZIP from this page and unzip it. Then place the skill folder in one of two locations: your personal skills folder at ~/.claude/skills/, or a project-specific .claude/skills/ folder inside the project you are working in. A project folder keeps the skill available only to that project.

If you use the Claude apps instead of a local folder, upload the skill under Settings → Capabilities → Skills.

The underlying CLI is a Python package. The source lists this install command for the tool itself, which requires Python 3.10 or newer:

How do you trigger the skill with natural requests?

You do not need to type the commands yourself. Once the skill is installed, describe the result you want in plain language and mention the image files involved. The agent will select the matching commands from the skill.

Good requests name the inputs, the operations and the output file. For example: 'Make a 1200 by 800 poster canvas, place logo.png in the top left, add the headline Launch Night in white, and export poster.png.' Vague requests such as 'make this nicer' give the agent too little to act on, so state the change you need.

• Name the source files, using absolute paths where you can
• Say what should change: resize, add layer, filter, text, rectangle
• Name the output file and whether it may overwrite an existing file
• Ask for JSON output if another script will read the result

What commands does the agent run?

The agent works through command groups: project, layer, canvas, filter, media, export, session and draw. The commands below are the basics the source documents. You can run them yourself to check what the agent did.

Commands can be run with a single call or inside an interactive session. With no subcommand, the CLI opens a REPL with tab-completion and history. JSON output is requested with the --json flag placed before the subcommand.

• project new creates a project file; project info reports on it
• layer list shows layers; layer set changes name, opacity, visible, mode, offset_x or offset_y
• canvas resize changes the canvas without scaling content; canvas scale scales everything
• filter list-available shows filters; filter add applies one to a layer
• draw text and draw rect are render-time operations
• export render writes the final image; session undo and session redo step through history

Example: build a layered poster and export it

The source gives a layered composition workflow for overlay-heavy designs. It moves layer 0 by a negative horizontal and a positive vertical offset, adds a text layer, and renders the project to output.png. Negative offsets are accepted in both command mode and REPL mode.

Because text and rectangle draws are applied at render time, check the exported PNG itself, not only the project JSON.

• Set layer 0 offset_x to -48 and offset_y to 24
• Draw the text 'Launch Night' on layer 0 at x 96, y 120, size 72, colour #f6f1e8
• Render to output.png, overwriting if it exists

What does the skill need, and what are the safety notes?

You need Python 3.10 or newer and the cli-anything-gimp pip package. GIMP is optional. The source recommends it for native batch rendering, but layered compositions can still render through the built-in Pillow path when GIMP is missing or when deferred draw operations are present. The source says the Pillow path is the stable default even when GIMP is installed for projects with deferred draw operations.

This skill runs scripts. It does not use the network, according to the listing. Because the agent executes commands on your machine and writes files, review what it proposes before running it on important files, and keep backups of originals. Use absolute paths and confirm output files exist after each export, as the source advises.

• Requires: Python 3.10 or newer, pip package cli-anything-gimp
• GIMP is optional
• Runs scripts: yes
• Uses network: no
• Critical or legal image work needs human review of the rendered output

Tips for reliable results

The source gives a short checklist for agents, and it applies equally to people reading the results. Undo covers up to 50 levels of history, which helps when a step goes wrong. Keep the project file as a record of the layers, but judge the work by the rendered image.

If something fails, check the return code (0 means success, non-zero means error) and read stderr for the message. For documentation beyond this page, the source points to README.md and TEST.md in the package.

• Always request --json when a script or agent reads the output
• Check return codes and parse stderr on failure
• Verify that the output file exists after export
• Review rendered output after offset, draw, blend-mode or filter changes
• Use session undo and session redo to step back