post: on-brand social posts, built as code

A post is a post.json plus assets. The Remotion studio in packages/post-studio renders it to PNG (carousel, single, story, banner) or MP4 (reels). Follow the phases in order. Render nothing before the script is approved and the assets are ready.

Paths (resolve before anything else)

• Studio = the packages/post-studio folder of the motion-studio repo (it holds scripts/render.mjs, src/, public/brands/). If the agent was started inside the repo, it is <repo>/packages/post-studio. If this skill was installed globally, read the env var POST_STUDIO; if unset, ask the user for the path once. Call it $STUDIO.
• Posts folder, in this order: env POSTS_DIR -> field postsDir of "$STUDIO/config.local.json" -> ~/Posts. If config.local.json does not exist, ask where to save and create it from config.example.json.
• Paths may contain spaces, apostrophes or parentheses: always double-quote them in the shell.
• The studio must be installed once: cd "$STUDIO" && npm install && npx remotion browser ensure.

$STUDIO/
  public/brands/<brand>/brand.json + fonts/   design extracted from each project
  src/blocks, src/formats                     components (Board = the layout of every format)
  scripts/render.mjs                          npm run render -- "YYYY-MM-DD (topic)" [--slide=N]
  examples/                                   one post.json per format + carousel-dev with every block
$POSTS_DIR/
  YYYY-MM-DD (topic)/                         post.json, script.md, caption.md, sources.md, assets/, slide-NN.png | reels.mp4

Phase 0: Branding first (the rule that decides everything)

When this skill is activated, the very first thing you do is find the branding and design of the project you are working in. Do this before the interview, before any question about content.

1. Detect the project. The project is the current working directory (or the workspace the user is in). Look for design evidence: package.json, global CSS with custom properties, @font-face, Tailwind config or @theme, next/font, React Native/Expo theme files. If you find any of it, you are inside a project with a design.
2. Inside a project: its design is the brand. Extract it (Phase 1) and use it for every slide. Never replace it with a bundled brand. The bundled lz-landing and example brands are demos: use one of them only if the user explicitly asks for it.
3. Not inside a project (home folder, empty folder, the studio repo itself): do not guess. Ask the user which brand to use. Offer: an existing brand from ls "$STUDIO/public/brands", a project path or site URL to extract from, or a short brand interview to create a new one.
4. Never invent a color or a font. If a role is missing in the project, derive it from the closest one and say so in the summary.

Phase 1: Read the project's design

1. brand = the project folder name in kebab-case.
2. Follow references/read-design.md to extract colors, fonts, radius and tracking into $STUDIO/public/brands/<brand>/brand.json. Use search tools on the project files.
3. If public/brands/<brand>/brand.json already exists: compare with the project today, show only the differences, and update only if the user confirms.
4. Show a short summary (palette with hex values + fonts + the accent rule) and get a confirmation before moving on.

Phase 2: Alignment interview

Follow references/interview.md. Ask in rounds (at most 4 multiple-choice questions per round, concrete options, best option first). Then tighten the thesis until there is one sentence the reader must remember. Do not move on with a vague answer. Write the post content in the language the user writes in, unless they ask otherwise.

Phase 3: Research

• Post about the user's own project: read the repo (code, README, content). Those facts are the primary source.
• Post about a topic: search for primary sources (official docs, original research, changelogs), preferring the last 12 months.
• Record every claim in sources.md (claim -> URL or file). No number or factual claim goes into the art without a line in sources.md, including numbers and number. When in doubt, cut it.
• Button and menu names quoted in the art: confirm them in the language of the post; if you only find them in another language, note that in sources.md.

Phase 4: Script for approval

1. Present the detailed script visually to the user: an Artifact if your agent has that tool, otherwise plan mode or a structured message.
2. Follow references/script-template.md: slide by slide with layout, theme, exact text (with the marks ==highlight==, **emphasis**, __underline__, ~~strikethrough~~), blocks, visual, next, sticker, accent count; caption + hashtags; for reels, the time of each scene.
3. Pick a structure from references/formats.md (myth -> truth -> proof, trail, before & after, problem -> solution, introduction) or justify a free one.
4. Every post has at least 1 retention element (series chip, next-slide teaser, spoiler, phone, sticker, inverted final slide). Step-by-step on screen becomes phone; code becomes code; a strong data point becomes number or numbers.
   • For a reels that presents a system or app you can use the system-promo variant: the whole post renders as one continuous 3D showcase. Use layout cover for the first slide (intro), normal layouts with image (the screenshots) for the scenes, and cta for the end.
5. Respect the limits in references/formats.md, including at most 2 extra blocks per slide.
6. Stop using tools after presenting the script and ask for explicit approval. Adjust and present again if asked.

Phase 5: Asset preparation

Before building the JSON and rendering, the physical files must exist.

1. Create "$POSTS_DIR/YYYY-MM-DD (topic)/assets/".
2. Follow references/asset-prep.md.
3. Use your image-generation tool for backgrounds and illustrations, if the script asks for them.
4. Use ffmpeg and ImageMagick to cut videos or resize images (for example 9:16 for phone screens).
5. Make sure avatars and stickers have an alpha channel. View the image or run identify to check.
6. Move on only when everything listed under "Assets needed" in the script exists in assets/.

Phase 6: Build and render

1. Save in "$POSTS_DIR/YYYY-MM-DD (topic)/": script.md (the approved one), sources.md, caption.md.
2. Create post.json pointing at the files prepared in Phase 5.

   {
     "id": "YYYY-MM-DD-topic-kebab", "brand": "<brand>", "format": "carousel|single|story|banner-linkedin|reels",
     "variant": "4x5|1x1 (single) · cover|post (banner-linkedin) · system-promo (reels 3D showcase)", "title": "...",
     "section": "Tuesday · Myth", "series": { "name": "Myth", "number": 1 },
     "background": "plain|orbs", "music": { "file": "track.mp3", "start": 40, "volume": 0.7 },
     "slides": [{
       "layout": "cover|text|list|screenshot|phone|number|code|cta", "theme": "light|tinted|dark|accent",
       "emoji": "🏖️", "kicker": "what nobody tells you", "label": "...",
       "title": "Text with ==highlight==, **emphasis**, __underline__ or ~~strikethrough~~", "body": "...",
       "items": ["plain line", { "title": "card", "sub": "subtitle", "emoji": "⏱️", "icon": "check" }],
       "image": "screenshot.png", "fit": "cover|contain", "avatar": "me-cutout.png", "badge": { "text": "...", "type": "live|ready|wip" },
       "facts": ["..."], "button": "...",
       "screens": [{ "label": "Android", "steps": ["Chrome", "More", "Install"] }, { "label": "Dashboard", "image": "dashboard.png" }],
       "number": { "value": "01", "caption": "of 06 steps" },
       "numbers": [{ "value": "4", "label": "cities" }],
       "code": [{ "label": "before", "file": "bad.js", "lines": ["if (x === 1) {", "}"] }],
       "tip": { "label": "tip", "meta": "time: 1h", "text": "..." },
       "sticker": { "hint": "Poll: \"Have you installed an app like this?\"" },
       "next": "it rained out of nowhere",
       "duration": 3
     }]
   }

3. Render: cd "$STUDIO" && npm run render -- "YYYY-MM-DD (topic)". The script validates accents, assets, screens, code, numbers and sticker first.

Phase 7: Verify (mandatory before delivering)

• View every generated .png and look for: cut or overlapping text, fallback fonts (Arial/Georgia instead of the brand font), emoji turned into boxes (missing emoji font on the system), marks in the right place, contrast, story safe zones, content running into the footer, avatar covering text, code overflowing its window.
• Dimensions: file "<folder>"/*.png. For reels: ffprobe -v error -show_entries stream=width,height,duration -of csv=p=0 "<folder>/reels.mp4".
• Reels: extract 3 frames to a temporary folder (ffmpeg -ss <t> -i "<folder>/reels.mp4" -frames:v 1 <tmp>/f.png) and view them.
• Problem found: fix post.json (or the component) and re-render only the affected slide (--slide=N).
• Deliver: the folder path, the list of arts, the content of caption.md (with the sticker text, if any) and what you adjusted during verification.