marketing-machine

Argument: $ARGUMENTS — what to do. Examples: setup · write post about inventory turnover · review marketing/posts/12-report.md · card 12 · video intro · scan · everything

This skill owns the pipeline end to end. Nobody should need to read a README or run a script by hand: if something is missing, set it up; if a command fails, read its error and act on it.

Toolchain path: <TOOLCHAIN>. If that still reads as a placeholder (angle brackets intact), this skill arrived without init having run — resolve the path yourself, first match wins:

1. $CLAUDE_PLUGIN_ROOT is set in your environment → that directory IS the toolchain (plugin install; scripts, rules and templates travel with it).
2. A TOOLCHAIN file sits next to this SKILL.md → its single line is the path.
3. Neither → the toolchain is not on this machine yet. Clone it, then continue: git clone https://github.com/cagatayuncu/marketing-machine ../marketing-machine and use ../marketing-machine.

Every command below runs from the host repo root.

The chain

setup ──▶ scan ──▶ (human confirms facts) ──▶ write ──▶ visual / video ──▶ lint ──▶ report
  │                                                                          ▲
  └── config, fonts, brand roles, CI gate                    every output goes through here

Asked to do "everything", walk the whole chain and stop at the two points that genuinely need a human: confirming which product facts are true, and deciding which claims are defensible. Never invent an answer to either.

0 · Orient

First, check whether the machine is installed: is there a marketing.config.json at the repo root?

• No → go to §1 SETUP. Do not try anything else first; every other command needs the config.
• Yes → run doctor, then load context:

node <TOOLCHAIN>/scripts/doctor.mjs

If doctor reports a failure, fix it (§1.3 covers the two common ones). Do not proceed with a red doctor: a missing font or an unmapped brand role produces output that looks fine and is wrong.

Doctor also reports whether this machinery is current — skill copy (does the installed skill still match the toolchain that drives it) and toolchain version (is the toolchain behind its upstream repository). Neither blocks work, but do not swallow them: tell the user in one line and name the fix — init --refresh for a stale copy; git pull in the toolchain (or the plugin marketplace update) for an old version, then init --refresh. If the user says update, update first: producing content with yesterday's rules and then re-doing it is the expensive order. Offline is fine — an unreachable upstream reads as unknown, not as a problem to fix.

Then read marketing.config.json and these three files in full (do not skim):

1. <paths.context>/product-facts.md — what actually works. The single arbiter.
2. <paths.context>/claims.md — which claims are usable
3. <paths.context>/brand-voice.md — tone, bans, word preferences

Read at least two already-published pieces from <paths.posts> to calibrate the voice. If there are none yet, say so — the first piece has no reference and needs closer review.

---

1 · SETUP — setup

1.1 Install

Pick the agent target from what the repo already uses: .claude/ present → claude, .cursor/ → cursor, AGENTS.md → agents. If several or none, ask.

node <TOOLCHAIN>/scripts/init.mjs --agent <target>

Read the output carefully and relay it: it lists what was derived from the codebase and what could not be. That report is the only place naming the fields still needing a human.

1.2 Interview

init reports what it derived. Now ask about what a codebase cannot know. Ask these as one short conversation, not one question at a time, and write the answers where they belong.

Content language. init infers one from the locale files, but the product's interface languages and the marketing language are different decisions. A product whose UI ships in three languages may market in one; a product with no localisation at all still markets in something. Ask which language the copy will be written in, and if the product ships several, ask whether marketing follows all of them or starts with one.

If the answer differs from what was inferred:

node <TOOLCHAIN>/scripts/init.mjs --refresh --lang <code>

That re-derives the language-dependent pieces — the rule pack, the verification-table heading, the verify marker — while keeping paths, channels and anything already tuned. Do not hand-edit language.primary on its own; the rule pack and the in-content headings move with it.

If there is no rule pack for that language yet, say so plainly: only the structural rules will be enforced, the vocabulary bans will not, and someone has to write rules/lang.<code>.json for that half to exist.

Channel. Which surface is this for — a social feed, a blog, email, a landing page? It sets the card and video geometry, and it decides the post anatomy. Do not set up channels nobody asked for; config.channels ships three geometries and one of them is usually enough to start.

Audience. Fill <paths.context>/audience.md from the answers: who they are, the words they use for the problem, what they already tried, the first objection, and who this is explicitly not for. That last one matters — without it the copy drifts vague.

Product. product.oneLiner in the user's own words, and product.stage. Do not write the one-liner for them off the README; positioning is a judgment. brand.footerUrl if no domain was detected.

Leave any [VERIFY] marker you cannot resolve in place and report it. A marker is better than a guess.

1.3 Get doctor to green

Fonts. If doctor cannot resolve a font package, its error names the exact command. Run it in the toolchain directory, not the host repo — the fonts belong to the renderer:

cd <TOOLCHAIN> && npm i <package>

Save it rather than using --no-save: npm prunes unsaved packages on the next install, so a second font would silently delete the first.

If the family is not on a font CDN (a licensed or custom typeface), ask the user for the .woff2 files and set config.fonts.<role>.files to those paths instead of package.

Brand roles. If any of the six roles is unmapped, open the stylesheet named in config.brand.colorsSource, read the palette, and propose a mapping with your reasoning (bg ← the darkest surface, accent ← the interactive/primary color, and so on). Get agreement, then write it into config.brand.roles. Cards refuse to render until all six resolve, which is deliberate: wrong-brand artwork is worse than no artwork.

Even when all six auto-resolve, show the mapping and ask for a sanity check. It is guessed from names and can be confidently wrong.

ffmpeg is only needed for video. Leave it until someone actually wants an MP4.

Re-run doctor until it prints Ready.

1.4 Offer the CI gate

The rules are advisory until something runs them. Once doctor is green, offer to wire the gate:

node <TOOLCHAIN>/scripts/lint.mjs --warnings-as-errors

If the repo uses GitHub Actions, offer to add a workflow that runs it on changes under the config.paths directories. Ask before writing to .github/ — that is their build.

---

2 · SCAN — scan

node <TOOLCHAIN>/scripts/scan.mjs

Output lands in <paths.factsDraft> as a draft. Every line sits under the verify marker with a file:line reference.

You do not move the draft into product-facts.md yourself. A scanner sees that a symbol exists; it cannot see that the feature works end to end. What you do:

1. Read the draft.
2. Present it section by section, in the draft's order.
3. For each candidate ask: "does this work end to end, and what is the evidence?"
4. Move only what the user confirms into product-facts.md under WORKS. Everything else goes to PARTIAL or ABSENT, with the reason.

Spend the most time on section 1, the outbound-call inventory. If any claim about where data goes is planned, every row there has to be reviewed. One unreviewed call falsifies an absolute claim.

Then help fill claims.md. For each candidate claim: is it provable, and by what? The UNPROVABLE rows are the valuable ones — write them as rules in config.lint.projectRules so the build enforces them. A claim recorded only in claims.md is advice, and advice gets missed.

---

Drift — approved copy does not stay approved by itself

The linter re-resolves every file:line in the facts file and in post verification tables on every run: a cited file that is gone is a violation, a backticked evidence excerpt that no longer appears in the file is a warning, an excerpt that merely moved lines is a note carrying the new line number. What that means for you:

• When promoting rows from the draft, keep the backticked evidence excerpt next to the ref — a row with only file:line gets existence checking and nothing deeper. Refs are recognised when the path carries a directory (src/app.js:7); a bare root filename (package.json:5) is the linter's accepted blind spot, so re-check those rows yourself when the scan walk revisits them.
• A moved-line note is mechanical: apply the suggested line number, say what you did, move on.
• A gone/missing finding is NOT mechanical: re-walk that row with the human exactly like the original scan walk. Renamed feature → update ref and excerpt. Removed feature → retire the fact AND every post sentence that leans on it. Nothing gets re-approved silently.

---

3 · WRITE — write <channel> <topic>

Everything in the copy comes from this repository. Not from what products in this category usually claim, not from the README's own marketing language, not from what would sound good. The chain is: the scan found it in the code → a human confirmed it → it is WORKS in product-facts.md → it may appear in a sentence → the sentence carries its file:line in the verification table.

If you want to write something and cannot trace it back through that chain, you have two honest options: leave a verify marker and ask, or leave it out. Reaching for generic category copy is how a tool like this becomes worthless.

Settle the topic

Which audience, which angle, which call-to-action level? Decide, and record it in the post's header block. If the user keeps a "will not write" list, respect it: say why and stop.

Write

Anatomy: hook → enlarge the problem → turn → evidence → limitation sentence → one question.

• The product name does not appear in the first two lines.
• No em dash inside a sentence. Split the sentence.
• The limitation sentence is not optional. Copy that only says good things is not believed.
• Use unicode bold only on digits and on words with no language-specific letters.
• Where you are unsure of a fact, leave the verify marker with a reason. Do not invent.

Terminology — the product's words, not the dictionary's

When the copy language is not English, technical terms are a decision, not a translation. A literal dictionary rendering of a domain term ("tenant" → the residential word for a renter) reads as machine output and burns trust in one line.

1. The product's own locale strings are the authority. Before writing, look the term up in the product's i18n files (config.scan.i18nLocales). Whatever the product shows its users is what the post says — even when that is the untranslated English term.
2. No product translation → industry form wins. If the product has not translated the term, keep the form practitioners actually use in that language (often the English term as-is). Never coin a literal translation for marketing that the product itself does not use.
3. Record the decision. Keep a ## Glossary table in <paths.context>/brand-voice.md (term → what we write → why). Check it before writing; extend it when a new term is settled.
4. Make repeat offenses mechanical. A form that must never appear again goes into marketing/rules/project.json as a rule, so the linter fails the build instead of you remembering.

Save

<paths.posts>/NN-slug.md. Template:

# Post NN — <title>

**Pattern:** <one sentence describing the structure>
**Audience:** <who>
**CTA:** <level>
**Lang:** <code — the language THIS post is written in>
**Visual:** <file, or "none" + reason>
**Alt text:** <what the card conveys>

---

<the copy>

---

## Verification notes

| Claim | Source |
|---|---|
| ... | file:line |

The verification table is mandatory. Every number in the body must appear in it; the linter checks this and fails the build when it does not.

Lint (not optional)

node <TOOLCHAIN>/scripts/lint.mjs <file>

A VIOLATION blocks publication. Fix it and run again. Tell the user briefly what you changed. Weigh WARNING and NOTE items with judgment: some are deliberate choices, and when they are, record the reason in the post's header block.

Vocabulary rules are chosen per FILE, from the post's **Lang:** header (or a name.<code>.md suffix). In a repo publishing in more than one language, write that header on every post — without it each file is checked against every loaded language pack at once, and you get one guaranteed false warning per post per foreign pack.

What the linter cannot see, and you must: whether the limitation sentence is any good, whether each claim maps to a WORKS fact, audience coherence, hook strength.

---

4 · VISUAL — card <post>

Decision table — first match wins

What the post contains	Format	Why
Something visible in the product UI and full enough to carry the frame	Screenshot	A real screen beats a drawing. Do not build a card; ask for the screen.
A step-by-step flow or process	Flow card	Order reads at a glance
Two states compared (before/after, right/wrong)	Comparison card	Contrast is what a visual does best
A measurement, ratio or headline number	Number card	A number disappears in prose and holds in a card
A numbered teaching list	List card	Raises saves
The product's motion is the point	Video	Motion cannot be described, only shown
Several sequential ideas that each deserve a frame	Carousel (PDF)	LinkedIn document posts hold attention per-swipe
A confession, an opinion, an engineering diary, a conceptual argument	NO VISUAL	Text posts work better in this column

The default is no visual. Do not make decorative cards; an empty card weakens the post.

The trap in the screenshot row: copy happening inside the product UI does not by itself earn a screenshot. The test is whether that one screen element can carry the whole frame alone. A full panel can; a single-line warning strip cannot. If it cannot, fall back to the structure in the post's spine (flow, comparison, number).

State the decision in one sentence with its reason, then proceed.

Build the card

Copy <paths.cards>/_template-card.html, keep the <section> matching the archetype, delete the rest, fill the slots.

Invariants:

• Leave <!--FONTS--> and <!--TOKENS--> in place. Colors and fonts come from config; never write a hex value or a font name into the card.
• Identity text uses placeholders: {{brand.wordmark.text}}, {{brand.footerUrl}}. A placeholder with no value behind it fails the render.
• Logo: when config.brand.logo is set, the header shows the logo image, not the text wordmark: <img src="{{brand.logoData}}" style="height:40px" alt="" /> — the renderer inlines the file. Set the height only and let width follow; never stretch or recolor it. No brand.logo in config → text wordmark, and do not use {{brand.logoData}} at all.
• At most config.lint.cardMaxWords words. A card is one idea, not a summary of the post.
• The card does not repeat the copy; it completes it.

Layout discipline — a card that renders is not yet a card that reads:

• Normal flow only. No absolute positioning for text, no negative margins, no fixed pixel heights on text containers — that is exactly how list numbers end up printed over the headline. Space with flex/grid and gap; let every box grow with its content.
• Reserve wrap room. Any headline may take one line more than you expect, in any language. Nothing below it may depend on where it happens to end.
• A list marker and its text share one flex row (align-items: center); rows never share coordinates with anything else.
• Between distinct blocks (headline / list / footer) leave at least one line-height of air. A crowded card reads as broken even when nothing technically overlaps.

Not the same card twice:

• Before building, open the last two or three files in <paths.cards> (and <paths.scenes> for video). If this one would repeat the same skeleton — same archetype, same alignment, same scale rhythm — change the composition deliberately: flip the alignment, trade the list for a grid, let the number dominate the frame, move the emphasis elsewhere. Brand stays fixed (roles, fonts, wordmark); composition must not fossilise into one layout wearing different words.

node <TOOLCHAIN>/scripts/render-card.mjs <name>
node <TOOLCHAIN>/scripts/lint.mjs --only card

If the render fails, read the error and act on it — it names the cause and the fix. Pass anything you cannot resolve through verbatim; do not paper over it.

Carousel, languages, themes

• Carousel: author <name>.slide1.html ... <name>.slideN.html (each an ordinary card, same invariants, ONE shared geometry), then carousel <name> binds them into <paths.out>/<name>.pdf. Slide 1 must stand alone — the feed shows it before any swipe. One idea per slide; the last slide carries the wordmark and the URL. Slides live in paths.cards like any other card; carousel <name> --png also writes each slide as a PNG, which is how you do the look-at-it pass below on a document.
• Languages: put translatable copy into <name>.copy.json ({ "langs": { "en": {...}, "tr": {...} } }) and reference it as {{copy.<key>}} in the card. card <name> renders every language; terminology follows the Glossary exactly as in posts. Layout QA applies PER LANGUAGE — text lengths differ. A carousel reads the same decks: <name>.copy.json covers every slide of <name>, a <name>.slideN.copy.json overrides it for one slide, and the output becomes <name>.<lang>.pdf. Every slide that declares languages must declare the SAME ones, or the run refuses by name.
• Themes: when config.brand.themes exists, card <name> --theme all renders every role set. A theme is a full set of six roles; never hand-build a "light version" by editing colors into the HTML.
• Live capture (record): a <name>.drive.json drives the REAL product and records it — provenance is driven-app by definition and the file refuses anything else. Prefer it over a simulation whenever the product can actually be driven; never present either as a screen recording.
• Claims registry: when config.paths.claims exists, cite claim:<id> in verification tables instead of repeating file:line. Retiring a claim in the registry flags every post that cites it (and paths.published adds the live URL to the finding). Keep the registry the single place a claim's status changes.
• Metrics journal: after a post has real numbers, add **Metrics:** impressions=N reactions=N comments=N to its header. report aggregates by pattern — read it before choosing the next post's angle; it describes, you judge.

Look at what you rendered (not optional)

Open the PNG and inspect it before showing it to anyone. The renderer checks values — fonts, roles, placeholders — not composition; overlap is invisible to it. Check, in order: nothing overlaps anything, nothing clips at a canvas edge, no text is truncated mid-word, every block has the air the layout rules demand, and the logo (if any) is sharp and unstretched. If any check fails, fix the HTML and render again. A card ships only after this pass — in every language it ships in, since text length changes the layout.

For a carousel, render the slides with carousel <name> --png and inspect those. The PDF is the deliverable, not the review surface: it is not something you can open and look at.

Alt text (not optional)

Do not copy the words on the card; write what the card conveys. Someone using a screen reader should get the same information without seeing it.

• Bad: "Product card. No more queueing for a report."
• Good: "Four-step flow: ask in plain language, see the query, get the result, add it to the dashboard. Below: the query runs on your own machine."

Update the post file

Fill in **Visual:** and **Alt text:**. If the decision was no visual, write the reason.

---

5 · VIDEO — video <scene>

Full contract: references/video-guide.md. In short:

Video comes from HTML too, through the same pipeline as a card. The only difference is that a scene declares a timeline.

node <TOOLCHAIN>/scripts/record.mjs <name> --shot 6.5   # one frame — check this first
node <TOOLCHAIN>/scripts/record.mjs <name>              # the MP4

Always check a frame before rendering 450 of them.

Three rules when writing a scene, none negotiable:

1. Every visual is a pure function of t. No CSS transition/animation/@keyframes, no setTimeout/requestAnimationFrame driving visuals, no state accumulating across __seek calls.
2. Use a fixed rate, not a fixed duration (typing, scrolling). Longer copy in another language must not look pasted in.
3. On-screen strings must match the product's real strings exactly. Copy them from the product's own i18n source; do not retype. A missing key should fail the build rather than leave a hole in the video.

Provenance is mandatory. With config.provenance.required on, every scene must declare:

window.__provenance = 'simulation';   // real-recording | driven-app | simulation

A code-reconstructed interface is not a screen recording and must never be shared as one. Record this in the post file too. The linter reads the declaration out of the scene, so omitting a file does not get you past it.

When it is not enough: if the post's argument rests on evidence ("don't believe me, look"), a real recording is always stronger. Produce the clip so the post is not blocked, but leave the real recording on the table and say so.

---

6 · REVIEW — review <file>

For copy that came from somewhere else.

node <TOOLCHAIN>/scripts/lint.mjs <file>

That is the mechanical part. Add these passes yourself; the linter cannot see them:

1. Claim verification. Pull out every capability sentence. Is it WORKS in product-facts.md? If not, that is a violation. If PARTIAL, does it need framing?
2. Limitation quality. Present, and does it state a real limit rather than decoration?
3. Audience and tone. Written to one audience? If it is reaching for two, which one wins? Any blaming tone?
4. CTA fit. Right level for this kind of post? Is the product even in a state to support it?

Report in this severity order: VIOLATION (cannot publish) → WARNING (publishable but weaker) → SUGGESTION (optional).

Then give the corrected copy in full. Fix only violations; do not rewrite the author's voice or structure. Do not try to make someone else's copy "better".

Do not modify the file unless asked — a report is often enough.

---

Invariants