Media Use
FreeResolve media needs into local files effortlessly.
Free · Opens the source repo
What Media Use does
Media Use is a specialized tool designed to streamline the process of sourcing and managing media assets for projects. By utilizing a single command, resolve, users can efficiently retrieve various types of media, including background music, sound effects, images, and icons, from the HeyGen catalog or local assets. The skill handles the entire workflow: it searches for the required media, downloads it, freezes the file locally, and registers it in a manifest, ensuring that all relevant information is neatly organized and accessible.
The core functionality revolves around the resolve command, which takes parameters such as the type of media needed and a natural language description of the intent. This command not only simplifies the search process but also minimizes clutter by returning a concise output that indicates the resolved asset's ID and path. This means that users can focus on their creative work without getting bogged down by the intricacies of media management.
Media Use is particularly beneficial for developers and designers who regularly incorporate multimedia elements into their projects. Whether you are creating a presentation, developing a game, or working on a video project, this tool ensures that you can quickly access high-quality media assets without the hassle of manual searches or file management. Additionally, the skill supports bulk adoption of existing media assets, making it easier to integrate previously used files into new projects.
Overall, Media Use is an essential tool for anyone looking to enhance their projects with professional-grade media while maintaining an organized workflow. Its integration with the HeyGen catalog and local caching mechanisms provides a robust solution for managing media needs efficiently.
When to use it
Use Media Use when you need to quickly find and incorporate media such as music, sound effects, images, or icons into your projects.
When not to use it
This tool may not be suitable for projects that require highly customized or unique media assets that are not available in the HeyGen catalog or local storage.
What you can build with it
Game Development
Incorporate sound effects and background music into your game quickly by resolving assets directly from the HeyGen catalog.
Presentation Creation
Easily find and use high-quality images and icons for your presentations without the hassle of manual searches.
Video Production
Streamline the process of adding sound effects and music to your video projects with a single command.
How to install Media Use
View source1. Install with the skills CLI
npx skills add calesthio/openmontage/media-use --agent claude-code2. Or install it manually
Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.
Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs
Inside SKILL.md
Written by calesthiomedia-use
Resolve media needs into frozen local files. One verb, four types, zero context noise.
When to use
Call resolve whenever a composition needs media — background music, sound effects, images, or icons. media-use searches the HeyGen catalog, downloads the best match, freezes it locally, and registers it in a manifest. The agent gets back one line; all search noise stays on disk.
Resolve
node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
Returns one line: resolved <id> → <path> (<type>, <metadata>)
Types
| Type | What it finds | Provider |
|---|---|---|
bgm | Background music | HeyGen audio catalog (10k+ tracks) |
sfx | Sound effects | Bundled 19-file library + HeyGen catalog |
image | Photos, backgrounds | HeyGen asset search (75k+ vectors) |
icon | Icons, logos | HeyGen asset search (type=icon) |
Examples
# Background music
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .
# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
# Sound effect
node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
# Image
node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project .
# → resolved image_001 → .media/images/image_001.jpg (image)
# Icon
node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .
# → resolved icon_001 → .media/images/icon_001.png (icon, transparent)
Flags
| Flag | Description |
|---|---|
--type, -t | Media type: bgm, sfx, image, icon |
--intent, -i | What you need (natural language) |
--entity, -e | Entity name for cache matching (optional) |
--project, -p | Project directory (default: .) |
--adopt | Bulk-import existing assets/ into manifest |
--json | Output JSON instead of one-line result |
How it works
- Check project
.media/manifest.jsonlfor exact-prompt match - Scan existing
assets/directory for unregistered files matching the need - Check global cache
~/.media/for reusable asset - Search via provider (HeyGen audio catalog, HeyGen asset search)
- Freeze file to
.media/<type>/, register in manifest, regenerateindex.md
The agent gets back one line. Candidates, scores, provenance stay on disk.
Adopt existing projects
Most HyperFrames projects already have assets in assets/. media-use adopts them:
node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
# → adopted 9 assets from assets/
# bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)
# image_001 → assets/images/avatar.jpg (image, 400×400)
ffprobe extracts real duration and dimensions. During resolve, unregistered files in assets/ matching the intent are adopted on the fly.
Reading the inventory
After resolve or adopt, read .media/index.md for the full inventory:
# .media · 4 assets
id type dur dims path description
bgm_001 bgm 25s — .media/audio/bgm/bgm_001.mp3 upbeat tech launch
sfx_001 sfx 0.6s — .media/audio/sfx/sfx_001.mp3 whoosh
image_001 image — 1920×1080 .media/images/image_001.jpg gradient tech background
icon_001 icon — 200×200 .media/images/icon_001.png rocket
Cross-project reuse
Assets are cached automatically on resolve. Subsequent resolves for the same prompt hit the global cache at ~/.media/ — no re-download, no provider call. Promote an asset explicitly with organize --promote <id> to make it reusable across all projects.
Files
.media/manifest.jsonl— machine SSOT, one JSON record per line.media/index.md— agent-readable table (id, type, dur, dims, path, description)~/.media/— global cross-project reuse cache (content-addressed, SHA-256)
CLI tools used
| Tool | Purpose | Required? |
|---|---|---|
ffprobe | Probe duration, dimensions, codec on adopt | Yes |
heygen | Audio catalog, asset search | For providers |
Install the heygen CLI (single static binary, no runtime) and authenticate:
curl -fsSL https://static.heygen.ai/cli/install.sh | bash # installs latest to ~/.local/bin
heygen update # if already installed: needs >= v0.1.6
export HEYGEN_API_KEY=<your-key> # or: heygen auth login --key <key>
Requires heygen >= v0.1.6 — the providers tag requests with the allowlisted --headers 'X-HeyGen-Client-Source: media-use' flag, added in v0.1.6. asset search is a pre-launch command hidden from heygen --help, but it runs. Without a heygen on PATH (or a valid key) the providers print a one-line diagnostic to stderr and resolve falls through to "no provider could resolve".
Frequently asked questions about Media Use
Similar skills
Spring Boot Testing
Master testing techniques for Spring Boot 4 applications.
GitHub Issues
Manage GitHub issues efficiently with MCP tools.
Geofeed Tuner
Optimize your IP geolocation feeds in CSV format.
Batch Files
Master Windows batch scripting for automation and task management.
Adobe Illustrator Scripting
Automate your Illustrator workflows with ExtendScript.
Plugin Structure
Create and organize Claude Code plugins effectively.