How to Let an AI Agent Optimize a Docs Folder Safely

Documentation folders often collect heavy screenshots, diagrams, product walkthrough images, and generated assets. An AI agent can help clean them up, but it should not blindly rewrite every image in the repository. Docs images carry meaning. Small text, UI labels, and step-by-step screenshots must remain readable.

A safe workflow gives the agent a narrow tool, a clear folder, and review checkpoints.

"Let AI optimize your docs images" is unsafe unless the task limits what the agent may read, write, convert, or rewrite. The workflow has to name the folder scope, the first read-only action, the structured report fields, the visual review gate, and the build step that proves the docs still render.

Start With Read-Only Discovery#

The first step should be a scan, not conversion. If the agent has access to a local image tool through MCP or another integration, ask it to inspect the docs folder and report candidates without writing files.

The Model Context Protocol tools specification describes tools as callable capabilities with defined inputs and outputs. The GetWebP MCP server exposes a scan_images tool for this purpose, and the CLI can do the same kind of first pass with --dry-run and --json as documented in the commands reference. For image work, a scan should return facts such as path, format, dimensions if available, byte size, and whether the file already has a modern-format sibling.

That lets the agent produce a useful summary before any asset changes.

For a docs folder, the instruction can be explicit:

Scope: docs/images only
Allowed first step: scan_images or getwebp ./docs/images --recursive --dry-run --json
Not allowed yet: conversion, markdown rewrites, deleting originals
Report: large files, screenshots, SVGs, existing WebP/AVIF files, risky filenames

Constrain the Folder#

Give the agent a specific path:

docs/images/

or:

apps/docs/public/images/

Avoid vague requests like "optimize all images in the repo." Repositories often contain logos, source artwork, test fixtures, snapshots, icons, and files that should not be touched.

A constrained folder makes the diff reviewable and reduces the chance of accidental changes outside documentation assets.

Preserve Originals#

Documentation images should not be overwritten during the first pass. The GetWebP CLI commands reference documents that original files are never modified or deleted, and that --output controls where converted files are written. Use that behavior deliberately by writing optimized outputs as siblings or into a separate folder:

docs/images/source/login-flow.png
docs/images/optimized/login-flow.webp

This gives reviewers a source comparison and lets the team revert easily. If the final workflow later replaces references, that should be a separate reviewed step.

Original preservation is especially important for screenshots. If a compressed screenshot becomes unreadable, the team needs the clean source for a new export.

Flag Screenshots With Text#

Docs screenshots often contain the most fragile content: small labels, code snippets, UI controls, terminal output, and error messages. Compression that is acceptable for photos can be poor for screenshots.

Ask the agent to identify likely screenshots and flag them for review. It can look for file names such as screenshot, settings, terminal, dashboard, or flow, but it should not pretend that filename detection is enough.

Manual review should check:

• text readability
• color contrast
• line sharpness
• dark-mode variants
• mobile crops if used
• before-and-after dimensions

If a screenshot fails, keep PNG or use a lighter setting.

Convert a Sample First#

Before converting a whole docs folder, convert a small representative sample:

• one screenshot
• one diagram
• one photo or illustration
• one transparent image
• one large hero image

Review those outputs in the docs site, not only in a file viewer. Static-site generators, markdown components, and responsive CSS can change the final display.

MDN's responsive images guide is useful background when docs templates use width candidates or image components.

A small sample command is easier to review than a repository-wide run:

getwebp ./docs/images/sample \
  --output ./docs/images/optimized-sample \
  --recursive \
  --quality 82 \
  --json

The agent should summarize the outputPath, originalSize, newSize, savedRatio, and status fields from the JSON output schema, then stop for visual review before processing the rest of the folder.

Keep Reference Updates Separate#

Converting files and updating markdown references are different tasks. Do not let the agent do both in one broad step unless the repository already has strong tests and review controls.

A safer sequence:

1. scan docs images
2. convert sample outputs
3. review quality
4. convert approved files
5. update markdown references in a separate diff
6. run docs build
7. review rendered pages

This makes failures easier to isolate.

Use Structured Reports#

Ask the agent for a report like:

Command: getwebp ./docs/images --output ./docs/images/optimized --recursive --json
Exit code: 3, partial failure
Files scanned: 46
Converted: 18
Skipped: 6 screenshots, 3 SVGs, 2 existing WebP files
Largest saving: onboarding-hero.png, 1.8 MB saved
Needs review: terminal-error-flow.webp
Failed input: docs/images/source/broken-export.png
Originals modified: no
Next step allowed: inspect failures and review rendered docs pages

The current exit-code model matters because a partial failure should not be described as a successful optimization pass. This report gives maintainers enough information to review the change without inspecting every file manually.

Run the Docs Build#

After conversion and reference updates, run the docs build or preview server. Check broken image paths, layout shifts, and screenshots rendered at the wrong size.

If the docs site uses search indexing, image manifests, or localized content, include those in the verification step. A file conversion that breaks a translated guide is still a failed optimization.

For localized docs, ask the agent to list every reference it changed by file path and locale. That makes it possible to spot a common failure mode: English docs render correctly while translated Markdown still points to the old image name.

Keep the Agent Accountable#

The agent should say what it changed and what it skipped. It should not hide uncertainty. Good agent output includes paths, decisions, and review notes.

An AI agent can be useful for docs image optimization when the workflow is bounded: scan first, preserve originals, convert a sample, flag fragile screenshots, update references separately, and verify the rendered documentation site before merging.