Marketing Machine

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: `. 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).

1. A TOOLCHAIN file sits next to this SKILL.md → its single line is the path.
2. 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 /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. /product-facts.md — what actually works. The single arbiter.
2. /claims.md — which claims are usable
3. /brand-voice.md — tone, bans, word preferences

Read at least two already-published pieces from `` 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 /scripts/init.mjs --agent 

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 /scripts/init.mjs --refresh --lang 

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..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 /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  && npm i 

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..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 /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 /scripts/scan.mjs

Output lands in ` 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

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.

1. 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.

1. Record the decision. Keep a ## Glossary table in /brand-voice.md

(term → what we write → why). Check it before writing; extend it when a new term is settled.

1. 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

/NN-slug.md. Template:

# Post NN — 

**Pattern:** 
**Audience:** 
**CTA:** 
**Lang:** 
**Visual:** 
**Alt text:** 

---

---

## 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 /scripts/lint.mjs 

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

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 /_template-card.html, keep the `` matching the archetype, delete the rest, fill the slots.

Invariants:

• Leave ` and ` 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: ` — 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 depen

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cagatayuncu
• Source: cagatayuncu/marketing-machine
• License: MIT

Install and usage instructions live in the source repository linked above.