{"id":20870,"plugin_id":"plugins_6aa93d4d067c8191bdd2a1969bee8916","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:16:37.738Z","digest":"2a3a49e9041755d9abddaa25709ca535698ce23744686e1df7a6a1c039a2f23c","against":null,"payload":{"description":"Names every ad file and ad-set folder for both mediums, video and statics — authors and expands the export naming record into one delivery filename per market and ratio, derives a localized filename from its source, reserves the next global ad-set sequence numbers against the live filesystem, and composes ad-set folder names from the workspace grammar. Load whenever a render or an image is about to be saved or exported, whenever an ad-set folder is about to be created, or whenever a reference creative's filename needs decoding. The grammar itself is the workspace conventions skill's data; this skill is the one tool that applies it, and nobody hand-writes a filename or a sequence number beside it.","included_files":[{"relative_path":"scripts/naming.mjs","size_in_bytes":27193}],"name":"ad-naming","skill_md_contents":"---\nname: ad-naming\ndescription: Names every ad file and ad-set folder for both mediums, video and statics — authors and expands the export naming record into one delivery filename per market and ratio, derives a localized filename from its source, reserves the next global ad-set sequence numbers against the live filesystem, and composes ad-set folder names from the workspace grammar. Load whenever a render or an image is about to be saved or exported, whenever an ad-set folder is about to be created, or whenever a reference creative's filename needs decoding. The grammar itself is the workspace conventions skill's data; this skill is the one tool that applies it, and nobody hand-writes a filename or a sequence number beside it.\n---\n\n# Ad naming\n\nOne tool produces every delivery filename and every ad-set folder name, for a\nvideo ad and a static ad alike. Exported files enter a flat delivery folder\nwhere an automation reads the filename, and after launch the filename is the\nattribution key back to the creative. A wrong filename is a lost measurement,\nnot a cosmetic defect. Ad-set folders carry a global sequence number that must\nnever collide across dates, languages or mediums.\n\n**The grammar has one home and it is not here.** The token pattern, the\nper-medium constants, the funnel stages, the localization inheritance rule and\nthe folder pattern with its sequence discipline are the workspace conventions\nskill's `naming.json` and `foldering.json`. The script reads them at run time\nand fails loud if it cannot; a filename authored from remembered constants is\nexactly the fork this skill exists to end. If the script cannot find the\nworkspace skill, install it or stop and ask.\n\nThe script looks for the `juicylucy` skill where Codex does — a project's\n`.agents/skills`, then `~/.agents/skills`, then the plugin — so a local copy of\nthe conventions skill is the copy the tool names from, the same one the agent\nis reading. When that is the case it prints a note on every call; repeat it to\nthe user, because their filenames now differ from every other teammate's.\n`where` shows exactly which files are being read.\n\n## The rule\n\n**Never hand-write a filename or a sequence number.** Not to save a call, not\nbecause the pattern looks obvious, not to fill a date. The ratio, the market\ntoken, the date and the sequence number are the system's; you author creative\nname, funnel stage, source and style, and the tool does the rest.\n\n## The tool\n\n`<SKILLS_DIR>` below is the directory that holds the installed skills — the\nparent of this skill's own directory.\n\n```bash\nnode <SKILLS_DIR>/ad-naming/scripts/naming.mjs <command> [flags]\n```\n\n| Command   | Medium | What it does                                                                                                                   |\n| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |\n| `get`     | video  | Read the project's record (`export-naming.json`) and report which authored fields are still missing.                            |\n| `set`     | video  | Merge authored fields into the record, validating first; the date is stamped on the first write and never moved.               |\n| `expand`  | video  | One delivery filename per market for a ratio: `--ratio 9x16 --markets en,de,pt-br`.                                            |\n| `name`    | static | Name an image directly from its fields: `--medium static --creative-name … --funnel … --source … --style … --ratio … --markets …`. |\n| `inherit` | both   | The localized copy's filename from its source: only the leading market token changes (`--filename \"<source>\" --market de`).     |\n| `parse`   | both   | Decode a filename that already follows the grammar — a reference creative's, usually — into its fields.                        |\n| `reserve` | both   | The next global sequence numbers: scans `--root <campaign parent>` recursively at call time and returns a block of `--count N`. |\n| `folder`  | both   | Compose an ad-set folder name: `--seq 13 --language de --batch GEN --ads 8 --icp \"Mixed ICP\" --format \"Static Format\"`.        |\n| `where`   | both   | Which copy of the conventions every other command is reading, and from which root — the check when a filename looks unfamiliar. |\n\nEvery command validates against the grammar and refuses an invalid value with\nthe field named. A style outside the medium's vocabulary is accepted but\nreported, so a rephrasing does not quietly become a second name for the same\ntreatment.\n\n## Who calls it, and when\n\n**A video run** (`video-ad-production`, Step 6) authors one record per ad and\nexpands it once per ratio:\n\n```bash\nnode <SKILLS_DIR>/ad-naming/scripts/naming.mjs get --project .\nnode <SKILLS_DIR>/ad-naming/scripts/naming.mjs set --project . \\\n  --creative-name \"<name>\" --funnel <TOF|MOF|BOF> --source <source> --style <fb-style>\nnode <SKILLS_DIR>/ad-naming/scripts/naming.mjs expand --project . --ratio <ratio> --markets <codes>\n```\n\nResolve funnel, source and style from the reference creative's filename first\n(`parse`), then the brief, then ask — the video engine's `references/naming.md`\ncarries that order and the video treatment vocabulary. The record lives in the\nproject as `export-naming.json`; a project still carrying the older\n`naming.json` is told so by `get` and `set`, and that file is not read.\n\n**A statics run** (`static-ad-production`, `static-localization`) reserves its\nfolder numbers before creating folders and names each image before saving it:\n\n```bash\nnode <SKILLS_DIR>/ad-naming/scripts/naming.mjs reserve --root <campaign parent> --count <batches x languages>\nnode <SKILLS_DIR>/ad-naming/scripts/naming.mjs folder --seq <n> --language <code> --batch <descriptor> \\\n  --ads <count> --icp \"<Mix ICP|Mixed ICP|Unique ICP>\" --format \"<Static Format|Video Format|Mix Formats>\"\nnode <SKILLS_DIR>/ad-naming/scripts/naming.mjs name --medium static --creative-name \"<name>\" \\\n  --funnel <stage> --source <source> --style <style> --ratio <ratio> --markets <codes> [--date <YYYY.MM.DD>]\nnode <SKILLS_DIR>/ad-naming/scripts/naming.mjs inherit --filename \"<source filename>\" --market <code>\n```\n\n`reserve` is run **immediately before `mkdir`**, not earlier in the session: a\nnumber reserved earlier may have been claimed, and the scan that counts is the\none just before the folder is created. When a localization set inherits its\nsource's date, pass `--date`; otherwise the date is today's.\n\n## What the tool will not decide\n\n- **Which values to author.** Creative name, funnel stage, source and style\n  come from the reference's filename, the brief, or the user, in that order.\n  The tool validates them; it does not guess them.\n- **Whether a batch already exists.** Inspect the destination and the newest\n  neighbouring folders first (the workspace skill's `foldering.json` §\n  `grammar_not_template`); `reserve` reports the highest number it finds and\n  the next block, nothing about what those folders mean.\n- **Anything about one client.** Brand facts stay in the resolved `brand-*`\n  skill; batch facts stay with the run.\n\n## Checklist before saving or exporting\n\n- [ ] The workspace conventions skill resolved (the script did not fail loud), and if it noted a local copy, the user was told\n- [ ] Video: `get` read first; `set` reported `complete: true`; `expand` produced every filename\n- [ ] Statics: `reserve` run just before `mkdir`; every folder from `folder`; every file from `name` or `inherit`\n- [ ] No ratio, market token, date or sequence number typed by hand\n- [ ] Every delivered filename listed from the destination folder and checked against the tool's output\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}