THE AGENT SKILLS DIRECTORY
Reusable skills for AI agents. Install any of them into a Cohub world's agent with one command.
npx -y @neta-art/neta-search-cli@latest skills find "<what you need>"
Wrote a skill? Publish it here →
Basic Cohub abilities. Most agents already have these mounted; listed here for reference.
Paste this into your agent's chat — it fetches the skill and follows it.
Use the skill: character-theme-song. Run `npx -y @neta-art/neta-search-cli@latest skills use @xinsong854/character-theme-song --via site` and follow what it prints. Read its complete output, redirecting it to a temporary file first if necessary, and resolve relative paths from the skill directory it prints.npx -y @neta-art/neta-search-cli@latest skills use @xinsong854/character-theme-songTurn one of your characters into a theme song, with a player page where the lyrics scroll in time.
# Character Theme Song
One character becomes one song: a written song brief distilled from their material (tempo, key, structure, instrumentation, lyric motifs), rendered through the platform music model, delivered in a player page with time-synced lyrics, playlist-capable, exportable as BGM. The player is a published web Work; the audio lands in the world as media works.
Read this file fully before generating anything or writing files. Resolve relative paths from this skill's directory.
## Language
Reply in the user's language, whatever language this file is in. This holds for every message of the run, above all the final handover; translate what the scripts print, don't paste it. Text the user sees in the deliverable — Work title, page title, buttons, labels — follows the user's language; lyrics stay in the language asked for. Text the user typed stays as they wrote it.
## When to use / when not
Use when the user wants music *for a character* — an image song, a theme, an anthem — with or without lyrics, and a page to play it on.
Not for AMVs or beat-synced video edits of existing footage (amv-maker), not for mood background music for a scene without a character focus, not for remixing an existing commercial track. Say what this skill makes and stop.
## Inputs
| Item | Required | Counts as given when |
|---|---|---|
| Character | yes | the user names a character; "a song for the whole cast" counts for one shared anthem only if they say so |
| With lyrics | no — default yes, in the user's language | "instrumental" or "no lyrics" opts out; language defaults to the user's |
| Multi-language | no — default off | the user asks for two or three language versions of the same song |
If the character is missing: ask once, then stop. Otherwise build through to delivery.
## How it works (what the agent must keep)
1. **Distill a song brief, not vibes.** From the material extract: temperament, era/region, one central image, one tension. Turn them into concrete musical choices — see `references/song-brief.md` for the one-page brief format (speed in BPM, key, section table with bars and instrumentation, chord frames per section, a lyric motif bank). A brief the model can read is what separates a character song from generic epic music.
2. **Lyrics first, audio second.** Write full lyrics (or the instrumental note) into the brief before generating audio; the music prompt quotes the lyric's own imagery so melody and words agree.
3. **Generate via the skill's script only** (`scripts/gen.mjs`, copied from the platform template): submit with `--work-title`, poll, fallback models, never pay twice. One song = one generation pass; do not re-roll for taste without asking.
4. **Player page** (`templates/` + `references/player.md`): track list (the song, plus alternate language versions if made), cover art slot, time-synced lyrics with active-line highlight and drag-to-seek, per-song theme colors from the character's palette, and a plain "download / use as BGM" affordance that links the audio media works.
5. **Sync format**: `lyrics: [{t: seconds, text}, ...]`, strictly ascending; the playlist validator warns on non-monotonic timestamps. Karaoke highlight is line-level, not word-level.
## Steps
1. Read the character: `node /mods/neta/neta atom list` → `atom get <id>`. Extract temperament, era, central image, tension. → `$RUN/brief-notes.md`
2. Write `$RUN/song-brief.md` per `references/song-brief.md`; if lyrics are on, write all of them there, in the requested language(s).
3. Generate audio: `node scripts/gen.mjs --kind audio --state $RUN/gen.json --brief $RUN/song-brief.md --work-title "<song title>"`. Rerun the same command while it prints `generating` or `busy`; never submit again by hand. If it returns `refused` or `no-credits`, stop and tell the user.
4. Build the player into `$RUN/site/` from `templates/`: `js/data/album.js` with track entries `{id, title, sub, audio, cover, duration, lyrics}`.
5. Check: `node scripts/check.mjs $RUN/site` — lyrics timestamps ascending, every track has audio+duration, locale present; writes `$RUN/qa.json`.
6. Register and publish: see Deliver.
`$RUN` = `_runs/character-theme-song/<timestamp>/`. Never move the run folder afterwards.
## Deliver
A **web Work** (the player) plus the **audio media works** made in step 3.
- Player: `node /mods/neta/neta work init web works/webs/<slug> --title "<title>"` → build → `node /mods/neta/neta work publish web works/webs/<slug> --title "<same>"`.
- Core content to verify before handover: the track plays, the active lyric line highlights in time, seek works, the title is in the user's language.
Then, as the last step:
7. **Hand over with a card.** One `interaction-components` link card on its own line, target `{ "type": "work", "workId": "<id>" }`, the id from the publish output (fallback: `cohubWorkId` in `works/webs/<slug>/meta.json`). Then one or two lines: the song title, and that the audio works are on the board for use as BGM.
## Out of scope
- Do not change world settings or delete files that existed before the run.
- Do not modify memory, character cards, installed scripts, existing Works or roleplays.
- Make one song (plus its declared language variants); not an album unless asked.
- No video editing; the player links audio, it does not cut footage.
## When to stop
- Missing character: ask once, then stop.
- The music model refuses the brief or credits run out mid-generation: report what the script said and stop; a refused generation is not charged.
- Material too thin for lyrics (no voice, no story): propose instrumental in one line and proceed — do not invent quotes.
## Gotchas
- Never hard-code audio as base64 in the page; reference the media work files, or mobile Safari dies on 4 MB inline.
- Lyric timestamps must be **seconds as numbers** (not "01:20"); the validator is your friend — run it before wiring the player.
- The player must handle `lyrics: []` (instrumental) gracefully: show a motif line instead, never a blank panel or an error.
- One autoplay interaction is required before `.play()`; show the cover with a play button, not a blank player.
- Per-song theme colors come from the character palette, but keep the lyric text at ≥ 4.5:1 contrast in both themes.
- When making 2–3 language versions: same instrumental bed is fine, but regenerate per language — dubbing text over mismatched phrasing reads as broken.