Guide · Agent skill
How to use the Fix broken images agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The broken-images skill is an agent skill for Claude that reviews a website's image tags, file paths and external image links to find images that are missing or likely to fail. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what to check before you accept its changes. You do not need prior experience with agent skills to follow it.
Fix broken imagesthedaviddias/Front-End-Checklist · MIT Download the skill Quick start
- 1Download the ZIP. Get the broken-images skill ZIP from this page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ in a project folder.
- 3Or upload in the Claude apps. Go to Settings → Capabilities → Skills and upload the ZIP.
- 4Ask in plain language. Request a check for broken or missing images, naming the folder or pages to review.
- 5Review the findings. Open each reported file and line and confirm the problem exists.
- 6Apply and verify fixes. Accept the fixes you agree with, then check the page in DevTools Network tab filtered by Img.
What the broken-images skill makes the agent do
Once installed, the agent looks at your image tags, file paths and external image links. It flags images that appear to be missing or may fail, and reports each problem with its file and line number.
For each problem, the agent suggests a fix. Typical fixes are correcting a wrong path, adding a missing image file, or adding an onerror handler that swaps in a placeholder image. The skill also explains why broken images hurt user experience and Core Web Vitals scores.
- Checks <img> src attributes and CSS background-image URLs in the codebase
- Flags paths to files that are not in the project
- Flags <img> elements with no onerror handler or fallback
- Flags hardcoded external image URLs that may become unavailable
- Flags dynamic image paths built from user data without existence checks
Install the broken-images skill
Download the ZIP for the skill from this page. Then choose one of the two install routes below.
For a personal install, unzip the skill into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into .claude/skills/ in your project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Trigger the skill with natural requests
You do not need a special command. The skill is described as being used when reviewing image assets, markup, and CDN or build transforms. Ask the agent in plain language about broken or missing images, and it should pick up the skill.
Be specific about the scope. Naming the folder, the site or the page type gives the agent a clearer target than a general request.
- "Check this project for broken image links."
- "Find <img> tags that point to files that don't exist."
- "Review the product pages for images that might fail to load and suggest onerror fallbacks."
- "We changed CDNs. Audit the image URLs in src/ for anything that may now 404."
What to expect in the report
The agent works from the files it is given. It reports each suspect image with its file path and line number, so you can open the exact spot and check it yourself.
Fixes change markup. The skill may add an onerror attribute such as this.src set to a fallback image, and then set this.onerror to null to stop error loops. Review each change before you accept it.
- Each finding lists the file and line
- Suggested fixes include correcting paths, adding missing files, and adding onerror fallbacks
- For React or Vue components, the fix is an onError callback that swaps the src
- External images may be suggested for self-hosting or a CDN with fallback
onerror="this.src='/images/fallback.png'; this.onerror=null;"Confirm fixes in the browser
The rule behind this skill suggests using browser DevTools to find broken images. In the Network tab, filter by type Img and look for red rows, which indicate failed requests.
The skill's reference also includes a small script you can run in the page console. It lists images where the image is not complete or its natural width is zero. You can use it to check your fixes on a running page.
- Open DevTools, go to the Network tab, and filter by Img
- Test fallback behaviour by blocking the image request in DevTools and reloading
- Run the console check to list images with zero natural width
const brokenImages = Array.from(document.querySelectorAll('img'))
.filter(img => !img.complete || img.naturalWidth === 0)
console.log('Broken images:', brokenImages.map(img => img.src))Safety notes: scripts and network access
This skill does not run scripts and does not use the network. It works from the files you give it. It does not browse or fix live sites on its own.
Because the skill edits code, keep changes under version control so you can review and revert them. Be careful in projects where images come from a user-controlled source, since the fixes change markup and may swap in fallback images that need checking.
- Runs scripts: no
- Uses network: no
- Requires: nothing listed
- Edits code only; check diffs before committing
Tips for better results
Point the agent at the directories that hold your templates, components and stylesheets, since those are where image references live.
Use the skill before launch and after a migration or CDN change. Pair it with the DevTools check so you confirm what the agent found in the browser.
- Name the folder or page type to narrow the scope
- Run it before a pre-launch review of product or marketing pages
- Run it after a site migration or CDN change
- Treat fallback images as content that also needs review
What people use it for
- Find <img> tags pointing to files that were removed during a redesign
- Audit external image links in product pages after a CDN change
- Add onerror fallbacks to components that display user-supplied or dynamic image paths
- Check marketing pages for missing assets before a launch
Frequently asked questions
How do I install the broken-images skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills instead.
Does the broken-images skill require anything else to run?
The skill lists no specific requirements. It does not run scripts and does not use the network, and it works from the files it is given.
Is the broken-images skill free to use?
The skill is published under the MIT licence. This page does not list a price, so check the licence file included with the source for the terms.
Will the skill fix broken images on my live website?
No. The skill edits code based on the files it is given and does not browse or fix live sites on its own. You still need to deploy any changes yourself.
Why does the agent suggest an onerror fallback?
An onerror handler swaps a failed image for a placeholder so visitors do not see the broken-image icon. The skill also sets this.onerror to null to prevent infinite error loops.
How is this different from checking images in the browser?
Browser DevTools shows which image requests failed at runtime. This skill reviews your code for paths and links that may fail, and reports the file and line for each one.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Choose this skill if you maintain a website with many images, need a pre-launch check, or are auditing links after a migration or CDN change. Skip it if you only want to view images or need a tool that browses and repairs a live site, since this skill works only from the files you provide.
Download the skill