Give your coding agent an image compressor with PiPic Skill

Your coding agent can run a build, edit a component and fix a failing test. Ask it to compress a folder of images, though, and it often writes a throwaway script or reaches for a tool whose output it cannot interpret reliably. PiPic gives it a different path: a real CLI does the image work, and a small skill teaches the agent how to call that CLI safely.

PiPic is not an AI compression model. The agent chooses and operates the tool; the PiPic Agent CLI sends PNG, JPEG, WebP or AVIF files to the same hosted compression service used by the HTTP API. The PiPic Skill is the instruction layer that connects a plain-English request to that command.

Install the CLI and the skill once

The setup belongs to the human using the machine. Install the CLI, approve one sign-in, then install the open-source skill into the agents you use:

npm i -g @pipic/cli
pipic login

npx skills add PiPic-cc/pipic-cli -g \
  -a claude-code \
  -a codex \
  -a cursor \
  -y

The shorter npx skills add PiPic-cc/pipic-cli -g command asks which supported agents should receive the skill. npx skills update -g checks globally installed skills for updates later. The skill source is public alongside the CLI, so the operating rules are inspectable rather than hidden in a prompt service.

After that, the request does not need the product name or any flags:

Compress the images in ./assets in place.

The skill description matches requests to compress, shrink or optimise images. Once selected, it checks that pipic is installed and that the current machine is signed in. It then maps “in place” to --replace and runs the CLI with machine-readable output:

pipic ./assets --replace --json

If the user asks to keep the originals, the agent uses -o <dir> instead. PiPic requires one of those two destinations and rejects a command that gives neither, before sending any file.

The skill carries the rules an agent cannot guess

A README can describe a command, but an agent still has to decide what counts as success, when to retry and when to stop. Those decisions affect files and monthly allowance, so the PiPic Skill pins them down.

It tells the agent to always request --json. The CLI then writes one NDJSON object per input file with six fixed fields: file, status, before, after, saved and, for skips or failures, error. status has only three possible values: ok, skipped and error.

skipped is not a failure. A common skip means the compressed result was larger, so PiPic kept the original. The skill prevents an agent from reporting that as a broken run or replacing a good file with a larger one.

The exit code controls the next action:

That exit-1 rule matters. Re-running a whole directory after two files fail uploads every successful file again and spends allowance twice. The skill narrows the retry to the failed paths instead.

It also has an escape hatch for version drift. If the installed CLI disagrees with the skill, the agent runs pipic --help and follows the installed program. A skill can be updated independently; the executable remains the runtime authority.

The CLI does the image work

The skill does not contain an encoder, upload image bytes or compress anything by itself. It teaches the agent to invoke the CLI. The CLI resolves the paths, checks the destination, calls the hosted service, writes smaller results atomically and emits the rows the agent reads.

One published run from our 2026 Q3 benchmark processed landscape.png with PiPic Agent CLI 1.0.6. The recorded file was 2,316,198 bytes before compression and 723,577 bytes after it, saving 1,592,621 bytes. That is one licensed test image and one recorded run, not a promise for every PNG. The benchmark publishes the inputs, exact commands, all 72 raw rows and its limitations.

For an ordinary agent task, the useful result is the contract around that number. The agent can tell which file changed, how many bytes were saved, which files stayed untouched and whether any path needs attention. It does not have to interpret progress animation or a sentence written for a human.

The remote MCP endpoint is separate from this execution path. It is a read-only integration guide that helps an agent discover the CLI and HTTP API. Image bytes move through the CLI or direct HTTP request, not through JSON-RPC.

Keep the human boundary explicit

The agent never installs a global package or runs pipic login on its own. Global installation changes the user's environment. Sign-in opens a browser or waits for a device-code approval that only the user can complete. If pipic whoami exits 3, the correct action is to stop and ask for that approval.

Credentials saved by pipic login work for later agent runs on the same machine. A container, CI job or sandbox may not see the user's ~/.config, so those environments use a user-created PIPIC_TOKEN from the account page instead.

PiPic CLI and API usage has a separate monthly allowance: 100 images on Free and 5,000 on Pro. The browser compressor remains free, unlimited and account-free. CLI images leave the machine for processing and are deleted from the server as soon as compression finishes; the full handling policy is on the privacy page.

That division is deliberate. The human installs and authorises the tool. The skill supplies the operating rules. The agent decides when to call it, and the CLI performs the work with an output contract the agent can actually follow.