What it does
Cross-references every attachment in the media library against post content, postmeta (featured images, ACF fields), widgets, customizer settings, and theme template references, then flags files with zero matches as candidates for cleanup. Files are only ever listed for review, never deleted automatically.
Install
This skill isn't packaged in an installable registry. It's a plain SKILL.md file you can copy directly. Copy it from the SKILL.md tab and save it at the path for your assistant:
Use it in your AI assistant
Claude Code
.claude/skills/orphaned-media-cleaner/ (or ~/.claude/skills/orphaned-media-cleaner/ for all projects)
GitHub Copilot (VS Code)
.github/skills/orphaned-media-cleaner/
OpenAI Codex
.codex/skills/orphaned-media-cleaner/
Cursor
.cursor/skills/orphaned-media-cleaner/ (or ~/.cursor/skills/orphaned-media-cleaner/ globally)
Compatibility
Any WordPress site; needs file system and database access, ideally via WP-CLI, to cross-check attachment usage against content.
The complete SKILL.md for this skill:
---
name: orphaned-media-cleaner
description: Use when a user wants to free up storage space, asks "what images am I not using", or wants a media library audit before a migration.
---
# Orphaned Media Cleaner
## When to use
The media library has grown large over time and the user wants to know which files are actually unused before spending time or storage cleaning it up, especially before a migration or storage upgrade.
## Procedure
1. Enumerate every attachment in the media library along with its ID and file URL.
2. Search post_content, postmeta (including common custom field frameworks), widget content, and customizer settings for references to each attachment ID or URL.
3. Also check the active theme's template files for hardcoded references to media, since not all image usage lives in the database.
4. Mark any attachment with zero references found anywhere as a cleanup candidate, and separate those from ones only used in trashed/draft posts (lower confidence, flag as "possibly unused").
5. Present the candidate list with file size and last-modified date so the user can sort by space saved.
6. Leave deletion to the user; do not remove files even if the match is confident.
## Guardrails
- Never delete or move media files directly, only report candidates; a false negative in the reference search would cause real content to break.
- Flag large files and recently uploaded files separately so the user doesn't accidentally approve deleting something they just added.