Making agent-readable media assets in a real codebase

The problem in one sentence

An agent editing a page can read every line of your components and almost nothing about your images, video, and audio, so it guesses which file to use from the filename. 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. This alone removes most wrong-asset picks.
• 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 you can. An SVG is source code. An agent can read it, edit a label, and change a colour token without ever rendering it.
• Alt text stored with the asset, not invented at each call site. Then the agent copies the accurate string instead of writing a plausible one.

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, the manifest is accurate for about three weeks.

Video and audio are the worst case. A binary video file is completely opaque to a coding agent, so any reference to it is a guess based on the path. 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

This does not give the agent visual judgement. It will still put a busy photograph behind white text, because nothing in your manifest tells it about contrast. Layout, cropping, and whether an image is any good remain human calls.

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. Every one you cannot interpret is a file your agent will misuse. 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.