Making agent-readable media assets in a real codebase

This research library uses AI-assisted source research and drafting. Linked sources support product claims; analysis and proposed exercises are our interpretation. Unless an article documents a test and its results, do not read it as a hands-on review or an independently verified benchmark.

The problem in one sentence

An agent editing a page may have text access without an image viewer, video player, or audio transcription tool. In that setup, it can choose the wrong media file from its name. Agent-readable media assets are the fix: enough machine-legible context next to each file that the choice stops being a guess.

You see the failure as an agent using hero-2.png where the design calls for the dark variant, or writing alt="" on a chart that carries the whole argument of the page.

What to change first

• Names that describe content, not history. pricing-table-dark.webp instead of Screenshot 2026-03-04 at 14.22.png. Clear names reduce ambiguity before a tool opens the asset.
• A manifest. One JSON file per asset directory listing each file with a description, intended use, dimensions, and whether it is decorative. The agent reads the manifest and stops opening binaries it cannot parse.
• Text sidecars for video and audio. A transcript at media/onboarding.mp4.txt makes six minutes of footage searchable and quotable.
• SVG where appropriate. Its source exposes labels and colour tokens, but render the result to check visual meaning and layout after editing.
• Store an accurate description with the asset, then choose alt text for its use on the page. The same image can be informative in one context and decorative in another.

A manifest entry that works

Keep it small enough that people maintain it:

{ "file": "art-07-hero.webp", "use": "article hero, top of page", "alt": "Two engineers reviewing a diff on a shared screen", "decorative": false, "dark_variant": null }

Put the rule in your repository instructions: never reference a file in images/ that is missing from images/manifest.json. Then add a CI check that fails when the two drift apart. Without the check, added and renamed files can leave the manifest stale.

Video and audio are the worst case. An agent without video-inspection tools cannot verify the contents from the file path alone. Generate a transcript when the file lands, store it beside the media, and add a short paragraph at the top saying what the clip shows and where it is used. Chapter markers with timestamps help too, because they let an agent link to a moment rather than to the whole file. None of this needs a new tool. It needs one step in whoever's process puts the media into the repository.

Honest limits

A manifest does not verify contrast, cropping, or layout. Inspect a render of the actual page, using a capable image tool and human review where needed; text metadata alone cannot establish that the result works.

There is also a maintenance cost, and it lands on whoever adds assets. For a marketing site with hundreds of images, that cost pays back quickly. For a repository with six icons, skip the manifest and just name the files properly.

Do this next

Open the largest asset directory in your project and read the filenames as if you knew nothing about the product. Ambiguous names are candidates for correction; they do not prove that an agent will misuse a file. Rename those, write a manifest for that one directory, add the CI check, and see whether the wrong-image corrections in review stop.

If you want help putting this into practice, talk to us.