Index of every page on this site: llms.txt
All skills
openmontageinc avatar

/media-use

@2e003e6
by openmontageincopenmontageinc/openmontage82k stars
11,135
Run it yourself

Agent Media OS — resolve any media need (BGM, SFX, image, icon) into a frozen local file + ledger record. One verb (`resolve`) handles the full cascade — project cache, global cache, HeyGen catalog search, freeze, register. Keeps search noise on disk, hands the agent a path. Use when a composition needs background music, sound effects, images, or icons.

Use this Skill: https://skilld.dev/gh/openmontageinc/openmontage/media-use

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈93 tokens for metadata: the name and description. ≈1.3k when used: this file.

Description uses 4.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈367 characters, or 4.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

media-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

  1. Check project .media/manifest.jsonl for exact-prompt match
  2. Scan existing assets/ directory for unregistered files matching the need
  3. Check global cache ~/.media/ for reusable asset
  4. Search via provider (HeyGen audio catalog, HeyGen asset search)
  5. Freeze file to .media/<type>/, register in manifest, regenerate index.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".

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert12d3 checks · Risk HIGH
  • Gen Agent Trust Hub12d

    The skill is well-architected with strong security controls against command injection. It requires an external CLI tool and processes natural language descriptions to resolve media assets, which presents a standard attack surface for indirect prompt injection.

  • Socket12d

    2 alerts: gptAnomaly

  • Snyk12d

    Risk: MEDIUM · 1 issue

Signed by skilld at 2e003e6. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 5 months ago

README badge

README badge for openmontageinc/openmontage/media-use