Claude Skill

copywriting

Use when asked to write or fix product/marketing copy, landing pages, UI strings, brand voice, AI tells, an end-of-article CTA, or a hook/lede. Not for whole articles: use technical-article-writer.

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download outlinedriven-outline-driven-development-.devin_skills_copywriting-b0e8ce8.zip · 19 KB
Part of outlinedriven/outline-driven-development — 145 skills

Install

skills CLI npx skills add https://github.com/OutlineDriven/outline-driven-development/tree/main/.devin/skills/copywriting
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install outlinedriven-outline-driven-development@llmmart
Git git clone https://github.com/OutlineDriven/outline-driven-development.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole outlinedriven/outline-driven-development collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Copywriting

Contract

Field Bound contract
Trigger Write or fix product or marketing copy, landing pages, UI strings, or brand voice, or remove AI tells (page); design or review a bottom-of-article CTA (cta); write a hook, lede, or accroche for long-form content (hook).
Authority Reversible local. Writes only user-facing copy and brand voice outputs in the working tree; cta and hook modes emit chat output only. Rollback is version control. No remote mutation.
Side effect Creates or edits copy files and brand voice outputs in page mode; cta and hook modes produce conversation only.
Done Page: copy is free of AI-isms, matches the voice chart, and fits the page type. Cta: the full recommendation structure is composed. Hook: the user has selected a hook and its commitments are named.

Inputs

  • Mode selector: page, cta, or hook. Auto-detect from the ask: a bottom-of-article call-to-action routes to cta; a hook, lede, or accroche for long-form content routes to hook; anything else routes to page. An explicit mode argument overrides auto-detection.
  • Mode page: copy to fix, or a page type and goal. Select the editing branch when copy exists or the user pasted it; the writing branch when nothing is written yet. For a genuinely ambiguous request ("improve this" with no copy in scope), ask one question, then commit.
  • Mode cta: article context, primary objective, audience and relationship, funnel stage, and mechanism preference, collected in the interview step.
  • Mode hook: topic, audience, target language (EN, FR, or both), approximate length, and publication venue; an optional existing draft opening, treated as Option 0 and never silently discarded.
  • Optional inputs, settled before writing: page purpose, audience, product, traffic source, and any voice file (VOICE.md, BRAND.md, docs/voice.md). If an input is missing, infer it and name the inference so the user can correct it against real copy.

Procedure

Auto-detect the mode. Do not ask which mode; infer it from the ask.

Mode page: writing new copy

  1. Gather context. Settle four fields before writing, from the user or from files; infer and name any field the files do not settle. (1) Page purpose: the one action this page drives. (2) Audience: the specific reader, their job title, pain, and what they have already tried. (3) Product: what it does and the concrete user outcome. (4) Traffic source: where the reader comes from. Traffic source sets temperature: cold needs more Why; warm can lead with How or What. Done when: all four context fields are settled from the user or files, with inferences named.

  2. State the brief, then write. State the brief and keep going; mark every inferred field so the user corrects it against copy, not against a question. Stop and ask before writing only when a wrong guess makes the work useless or unsafe: the copy ships in this turn with no review, or the goal is genuinely unknown and each candidate goal produces different copy. Done when: the brief is stated with inferred fields marked, or the run stops because a wrong guess would make the work useless.

  3. Discover brand voice. Check these sources in order and stop at the first match. (1) A voice file in the repo (VOICE.md, BRAND.md, docs/voice.md); authoritative when it exists. (2) Existing copy: README headers, copy files, or shipped marketing pages. (3) Inference: B2B SaaS direct and confident, consumer apps warmer, developer tools terse and honest. A discovered voice outranks the word lists: if the voice file or shipped copy uses a listed word as a signature, keep it. Locale and spelling convention come from the voice. When no voice file exists and the product will need one, offer to write VOICE.md alongside the copy using the voice chart structure below. Voice is constant (the brand personality); tone adapts to the reader's state: Done when: brand voice is discovered from the first matching source, with locale and spelling convention recorded.

    Reader state Tone Example
    Frustrated (error, failure, block) Empathetic, solution-first, never blaming "Payment failed. Your card was declined. Try a different card."
    Confused (first use, complex feature) Patient, one step at a time "Connect your bank to see spending insights. We'll walk you through it."
    Confident (routine task, return visit) Efficient, minimal "Saved"
    Cautious (high stakes, data loss) Serious, transparent, no nudging "Delete account? You'll lose all data and this can't be undone."
    Successful (completion) Positive, proportional, brief "Your changes are live."

    A tone shift is not voice drift; drift is when the copy reads as a different brand, not the same brand in a different moment.

  4. Choose framework and load page norms. Route on what the copy is. Product-state copy (error, empty, success, loading, permission) or an action label: apply the UI state copy rules below and stop; persuasion frameworks do not apply to a button that deletes something. Marketing copy: pick the primary framework from the brief and layer freely: Done when: the framework is chosen and page norms are loaded, or UI state copy rules are applied for product-state copy.

    Situation Lead framework
    Cold traffic, unfamiliar product Why/How/What (Simon Sinek)
    Feature-heavy product Benefit Not Feature
    High-trust audience, low awareness Show Don't Tell
    Transactional page, known intent CTA Clarity
    Long-form sales page Problem → Agitate → Solution (PAS)

    The nine frameworks: Why/How/What (lead with Why, not What; order Why → How → What), PAS (name the pain, amplify the cost, present the solution), AIDA (Attention → Interest → Desire → Action for cold traffic), StoryBrand (customer is hero, product is guide; never make the product the hero), BAB (Before → After → Bridge; warmer and aspirational vs PAS confrontational), Show Don't Tell (replace adjectives with a specific fact, number, or scenario), Benefit Not Feature (lead with the outcome for the user; mention the mechanism only after the benefit is clear), Sentence Economy (every sentence earns its space; cut openers like "In order to", "It is important to note that"), CTA Clarity (action verb + what they get + qualifier; never two CTAs with the same verb on one screen). For a known page type, apply its norms:

    • Homepage: establish what the product is and who it is for; pick the highest-value segment and write for them. Sections in order: hero (lead with Why), social proof above fold, problem/pain, solution/benefits (one benefit per point), how it works, testimonials, final CTA. Do not add a secondary CTA that dilutes the primary action.
    • Landing page: drive one action; message must match what brought the reader. Headline mirrors the ad or email promise. PAS for problem-aware traffic, AIDA for cold. One CTA only; strip navigation and footer links.
    • Pricing page: help visitors choose. Name plans by buyer type, not tier ("Solo / Team / Company" beats "Basic / Pro / Enterprise"). Sections: value restatement, plan comparison (2-4 plans), feature differentiators, FAQ, social proof by tier, risk reversal near the CTA.
    • Feature page: connect a feature to an outcome for visitors already evaluating. Feature → Benefit → Outcome chain. Skip broad setup; go straight to the specific outcome with a number or example.
    • About page: build trust; every element passes the "so what does this mean for me?" test. Mission as a customer benefit, origin story tied to the customer's frustration, human team, 3-5 customer-relevant values, a CTA pointing to the product.
  5. Write 2-3 alternatives. Label them Option A, B, C. Three for a page, hero, or campaign; two for a single string like a CTA or subject line. Each applies the chosen framework visibly, leads with Why, uses no banned word, includes a headline, subhead, and at least one CTA, and is structurally different, not the same idea with new adjectives. Done when: 2-3 labeled alternatives are written, each structurally different with no banned words.

  6. Recommend and explain. Pick one; state which and why in one sentence. For each unpicked option, give one specific edit note. Done when: one option is recommended with a one-sentence reason and one edit note per unpicked option.

  7. Verify every line before handing back. Check each line of every option: leads with Why, names a concrete outcome, no banned word, no em dash or stand-in. Check the option whole: it does not hand the brief's wording back (prompt echo), and every specific the user supplied appears rather than a stock default. New copy containing a banned word is not an option to present; rewrite it first. Done when: every line of every option passes the verification checks (Why-led, concrete outcome, no banned word, no em dash, no prompt echo, specifics present).

Mode page: editing existing copy

Set the edit posture first. Point edit: the user named one line, word, or section; change only the target plus minimum connective tissue; do not turn a point edit into a page audit. Restoration: the copy has a clear voice, angle, or opinion; preserve its vocabulary level, emphasis, omissions, sentence shape, and positioning; fix specific failures without rebalancing the argument. Rebuild: the copy is generic, contradictory, or has no perspective; reconstruct from the brief, but never invent proof.

  1. Read all copy-bearing files. Scan every reader-facing surface: README headers, landing components, hero, CTAs, product descriptions, feature lists, onboarding strings, meta descriptions, email subjects. Read the voice file too if one exists; it settles register and locale and overrides the word lists for any word it names as a signature. Ask which files if unclear; never audit copy not read in context. Done when: every copy-bearing file is read, including the voice file if one exists.
  2. Set the value proposition. Write one sentence before auditing: "[User] can now [do X] without [old pain]." Every flag and rewrite serves it. If the sentence cannot be written confidently, ask; the copy is unfixable until the value proposition is clear. Done when: the value proposition is stated in one sentence or the run stops because it cannot be written confidently.
  3. Audit against persuasion frameworks. Check every major copy block against the nine frameworks and carry forward only the highest-impact problems; the flag budget is set in Step 6. Done when: every major copy block is checked against the nine frameworks with only highest-impact problems carried forward.
  4. Remove AI writing patterns. If the user asked for AI pattern removal, run this first, before the sweeps. Flag each AI-ism with [AI-ISM] plus its type. Tier 1 words (always replace): delve, landscape (metaphor), tapestry, realm, paradigm, embark, beacon, testament to, robust, comprehensive, cutting-edge, leverage (verb), pivotal, underscores, meticulous, seamless, game-changer, utilise, nestled, vibrant, deep dive, unpack, showcase, unlock, intricate, holistic, actionable, impactful, learnings, thought leadership, best practices, synergy, in order to, due to the fact that, serve as, commence, keen (as intensifier). Tier 2 clusters (flag when 2+ in one paragraph): harness, navigate, foster, elevate, unleash, streamline, empower, bolster, spearhead, resonate, revolutionise, facilitate, underpin, nuanced, crucial, ecosystem (metaphor), myriad, plethora, catalyse, transformative, cornerstone, paramount, burgeoning, nascent, overarching. Tier 3 (flag only at high density, ~3%+): significant, innovative, effective, dynamic, compelling, unprecedented, exceptional, remarkable, sophisticated, world-class, state-of-the-art. Structural patterns: formulaic openings ("In the rapidly evolving world of..."), rhetorical-question openers, engagement hooks ("Here's the thing", "Plot twist:"), copula avoidance ("serves as", "features", "boasts"), synonym cycling, vague attributions ("Experts believe"), significance inflation, false ranges, em dashes and --/spaced-hyphen stand-ins (zero, in headings and body alike; a single occurrence is a failure). Chatbot artefacts (remove entirely): "I hope this helps", "Great question", "Let's dive in", any "let's + verb" transition, chain-of-thought leaking ("Let me think step by step", "Step 1:"), acknowledgement loops. Drafting tells (survive a word-level pass; check separately): prompt echo (the draft reuses the brief's own phrasing), generic default over the supplied specific (a real number or name replaced by a category placeholder), uniform confidence (every line lands at the same pitch). Severity triage: P0 (credibility killers: cutoff disclaimers, chatbot artefacts, vague attributions, significance inflation, a supplied specific replaced by a generic default) fix immediately; P1 (prompt echo, Tier 1 words, template phrases, "let's" openers, formulaic openings, engagement hooks, bold overuse, any em dash) fix before publishing; P2 (generic conclusions, compulsive rule of three, uniform paragraph length, announced honesty, copula avoidance, overused transitions, Tier 2 clusters) fix when time allows. A clean P0+P1 pass is publishable. Done when: AI writing patterns are flagged with [AI-ISM] labels and triaged by severity, or skipped when not requested.
  5. Run seven sweeps. Run all seven in order; each targets a distinct failure mode. Flag everything before fixing. (1) Clarity: confusing structure, unclear pronouns, undefined jargon, claims readable two ways. Flags [JARGON], [VAGUE]. (2) Voice and tone: formal/casual shifts, register mismatch; identify the dominant voice and standardise to it. Flag [VOICE-DRIFT] on the line that reads as a different brand, not where the same brand meets a different moment. (3) So what: every claim answers "why should the reader care?". Flags [DEAD-WEIGHT], [FEATURE-NOT-BENEFIT]. (4) Prove it: back every claim with a named testimonial, case study, stat, or third-party validation. Flag [NO-PROOF]; use [PLACEHOLDER: add proof: stat / testimonial / example] when the proof is unknown. (5) Specificity: replace vague time, quantity, and outcome with concrete detail. Flag [VAGUE]. (6) Emotion: name the pain the reader already feels before selling the outcome; mirror the reader's actual state at this point in the page. Flag [PAIN-NOT-NAMED]. (7) Zero risk: remove friction at and near CTAs; address objections, add trust signals, clarify the next step, add risk reversal. Flag [WEAK-CTA] on any CTA standing alone without a qualifier or trust signal. Finish with the compound adjective hyphenation pass: hyphenate a multi-word modifier before the noun it describes ("a 7-day free trial", "real-time updates", "{{days}}-day free trial"); leave it open when it stands alone as a noun phrase ("The trial lasts 7 days"); never hyphenate an -ly adverb ("a fully managed service"). Fix hyphenation silently rather than flagging it. Done when: all seven sweeps are run in order with flags applied before fixes, and the hyphenation pass is complete.
  6. Flag weakest elements. Attach an inline label to every weak line, using exactly these labels: [WHAT-NOT-WHY] (leads with product, not motivation), [FEATURE-NOT-BENEFIT], [TELL-NOT-SHOW] (adjective claim without proof), [VAGUE], [PASSIVE], [VOICE-DRIFT], [PAIN-NOT-NAMED], [DEAD-WEIGHT], [JARGON], [NO-PROOF], [WEAK-CTA], [STATE-COPY] (vague, leaky, or dead-end state string, or a destructive CTA labeled Confirm/OK/bare verb; apply the UI state copy rules below before using this label), [AI-ISM]. Flag the 3-7 weakest elements, prioritised by impact; over-flagging dilutes into a list nobody acts on. One occurrence is one flag; do not stack [TELL-NOT-SHOW] and [AI-ISM] on the same word. Done when: the 3-7 weakest elements are flagged with inline labels, prioritised by impact.
  7. Rewrite flagged sections. Cut hard (same meaning in half the words). Lead with Why, not What. Name the concrete outcome, not the capability. Replace adjectives with proof. Make CTAs outcome-specific. Every sentence adds new information or gets cut. A CTA stays short. When replacing AI-isms, rewrite the sentence; do not swap the flagged word for a synonym. Done when: every flagged section is rewritten with the same meaning in fewer words, leading with Why and naming concrete outcomes.
  8. Output before/after diff. For each flagged section, show the original, the labels, the rewritten text, and one sentence explaining the change. End with a summary: issue count, top pattern, and confidence (note if copy context was limited). Verify each "After" line: leads with Why, names a concrete outcome, no banned word, no em dash or stand-in, and every fact, number, and link from the "Before" still present. Then apply the leave-it-alone test: every change must fix a named failure from the audit; if it is merely different, restore the original. Done when: a before/after diff is output for each flagged section with labels, rationale, and a summary, and every "After" line passes verification.

Mode cta: end-of-article call-to-action

The archetype decision tree, the exact recommendation structure, and the operating principles live in references/cta-playbook.md.

  1. Interview. Ask the five inputs in order, one at a time with 2-4 tappable options, skipping any already supplied; fall back to free text only when the answer cannot be enumerated. (1) Article context: personal or independent blog or essay, newsletter or paid publication, brand or company content-marketing blog, other. (2) Primary objective: newsletter or email subscription, social follow, lead generation (gated asset), product or service signup or free trial, demo or sales call booking, direct purchase, community join, engagement (reply, comment, share), reader support (paid sub or tip), try-it or direct action, other; if the user lists more than one, ask which is primary, because choosing multiple objectives is the dominant cause of CTA failure. (3) Audience and relationship: first-time visitor, returning reader not subscribed, existing subscriber or customer, mixed or unknown. (4) Funnel stage: TOFU (discovery, no buying intent), MOFU (evaluating, comparing), BOFU (ready to act), not applicable. (5) Mechanism preference, asked only if a mechanism could legitimately help (for skeptical or repeat-reader audiences default to none or value-only without asking): none or value-only, curiosity gap, reciprocity (free asset first), discount or offer, urgency (real deadline), scarcity or FOMO, social proof. Capture volunteered constraints (length limit, brand voice, no popups, language, formality). Done when: all five inputs are collected or reported missing.
  2. Diagnose. Map the inputs to one archetype via the decision tree in references/cta-playbook.md. Done when: the inputs are mapped to one archetype.
  3. Compose the recommendation in the exact structure given in references/cta-playbook.md: archetype with rationale, content copy (headline, body, button, risk reversal), form (placement, visual weight, layout, proof), mechanism, A/B test plan, and a WCAG 2.2 accessibility check. Done when: the recommendation is composed in the exact structure with all sections filled.
  4. Anti-pattern warnings. After the recommendation, list 2-3 anti-patterns the user is at risk of given their inputs, as a contrarian check. Failure modes to call out by name: multiple competing CTAs, generic "Subscribe for more" or "Learn More", mechanism mismatch (urgency or scarcity where none exists), SaaS landing-page voice on a personal essay, proofless ask, "Book a Demo" on TOFU content, open-ended reply questions on social. Done when: 2-3 anti-patterns are listed as a contrarian check.
  5. Enforce the operating principles in references/cta-playbook.md during composition: one primary CTA per post, publication voice, specificity over cleverness, proof co-located with the ask, mechanisms only when the context supports them, and pushback on bad asks. Done when: the operating principles are enforced during composition.
  6. Language and style. Adapt copy to the user's stated brand voice, the article's language (never default to English), the publication's existing cadence, and the reader's expertise level. Honor formality cues (tu/vous, du/Sie) and flag the choice. If non-English, translate the content section but keep structure headings in English. Done when: copy is adapted to brand voice, language, cadence, and expertise level with formality cues flagged.
  7. Offer next moves. Suggest 2-3 follow-ups: steelman the opposite CTA, a variant for a different audience or platform, or an end-to-end article review for CTA-supporting signals. Done when: 2-3 follow-ups are suggested.

Mode hook: hook, lede, or accroche

A hook's only job is to make the reader want sentence 2, through one of five levers (a strong hook usually pulls two at once): open a gap, break a prediction, drop into a scene, promise a payoff, borrow weight. The five levers in detail, the type-fit table, the 18-hook catalog, the anti-pattern cull, and language handling live in references/hook-catalog.md.

  1. Confirm the brief. Ask before generating if a material input field is missing. Done when: the brief is confirmed or missing material fields are requested.
  2. Pick 3-4 hooks from the catalog that are genuinely different, different levers, not three flavors of the same technique. Diversification rule: across the options include at minimum one intellectual hook (contrarian, definition reversal, historical analogy, curiosity gap), one sensory hook (in medias res, concrete detail), and one reader-direct hook (conditional, direct problem, promise). Done when: 3-4 genuinely different hooks are selected, each pulling a different lever.
  3. Write 2 candidates per hook, specific to the user's article. The two candidates within one hook explore different angles (different anecdote, statistic, or scene), not rewordings of each other. Done when: 2 candidates per hook are written, each exploring a different angle.
  4. Apply the quality gates to every candidate: specific beats abstract (replace "many companies" with "Stripe, Shopify, Vercel"; replace "recently" with a date; replace "studies show" with the actual finding or cut the claim); the first sentence must force the second (read each candidate cold; if sentence 2 would not be clicked after sentence 1, rewrite); match technique to article type using the type-fit table. Done when: every candidate passes the quality gates.
  5. Run the anti-pattern cull on every candidate. If a candidate matches any entry, rewrite it before presenting. Done when: every candidate passes the cull or is rewritten.
  6. Present and let the user pick. Present using the Output format, ask the user through the question tool, and wait. Do not pick for them. Done when: options are presented and the user is asked to pick.
  7. Name the commitment. After the pick, name what the choice commits the rest of the article to. A contrarian hook commits paragraphs 2-3 to defending the non-consensus claim. A scene opener commits the next section to resolving or productively delaying the scene. Done when: the chosen hook's opening commitments are named in one sentence.

UI state copy rules (for product-state strings and the [STATE-COPY] label)

  • Destructive CTAs (rule/destructive-names-action, rule/no-confirm-ok-labels): Verb plus Noun naming the exact object ("Delete project", not "Confirm" or "OK"). Never label a consequential action Confirm, OK, Yes, or a bare verb.
  • Canonical verbs (rule/canonical-verb): one verb per operation, used consistently; pick the verb whose consequence matches (Delete = permanent, Remove = detach without destroying, Archive = reversibly hide, Discard = drop unsaved edits, Cancel = abandon an in-progress action).
  • Error (rule/error-states-recovery): state what happened, why when known, and the recovery action; never raw exceptions or a bare "Something went wrong". Separate field-level from surface-level errors; preserve everything the user typed.
  • Success (rule/success-state-specific): confirm in past tense what happened to which object, proportional to the action.
  • Empty (rule/empty-state-action): name the object and offer the first action; no dead ends. Three types: never-had-any (guide the first step), filtered-to-zero (clear the filter), user-cleared (confirm completion; the one empty state that needs no CTA).
  • Loading (rule/loading-state-specific): say what loads and, for long operations, roughly how long; keep the triggering control's label stable.
  • Permission (rule/permission-benefit-first): state the user benefit before the permission ask; ask in context when the feature is first used.
  • Copy without the screen (rule/reads-without-seeing): copy must work when heard; field errors read sensibly after their label; link and button text names the destination or action; no directional words ("above", "below", "here").
  • Length budgets (size for the tightest surface first; leave 30-40% headroom for translation): button or CTA 2-4 words; title 3-6 words; error message 12-18 words including the recovery step; any sentence the user must act on 14 words (8 reads at full comprehension).

Banned words

The never-write set, absolute unless a voice file names one as a signature: delve, leverage (verb), robust, seamless, holistic, paradigm, game-changing, cutting-edge, innovative, synergy, revolutionary, effortless, world-class, powerful, showcase, unlock. Also ban "simple" as a claim ("our simple onboarding"): never earned upfront, reads as an unkept promise.

Voice chart structure (when offering to write VOICE.md)

Three to five concepts. Each concept has three parts: (1) a brand principle, one word or short phrase; (2) two or three adjectives naming how it shows up in writing; (3) a Do and Don't pair of real interface or page strings. The Don't side is the useful half: make it the plausible near-miss the team actually ships, not a strawman. Start from shipped copy, not brand values. Record locale and spelling convention, house spellings, and any word the brand uses deliberately that a generic list would flag. Name what the voice is not ("Confident, not boastful").

Failure and recovery

  • Invented audience or goal. Copy written without a goal and value proposition reads well and solves the wrong problem. If a context field cannot be settled from files or the user, infer it and name the inference; never present an inference as a fact. Stop and ask only when a wrong guess makes the work useless or unsafe.
  • Invented proof. Never fabricate a number, testimonial, or statistic. Use [PLACEHOLDER: add proof: ...] and let the user supply it.
  • Locale or voice regression. A US-spelling rewrite on an en-AU product ships as a regression across every string it touches. Check existing copy and the voice file before switching spelling or tone; a discovered voice outranks the word lists.
  • Point-edit scope creep. Do not turn a named point edit into a page audit; change only the target plus minimum connective tissue.
  • Restoration over-reach. Do not rebalance the argument or replace a clear lead with a cleverer one; fix named failures only.
  • AI-ism reintroduced or specific dropped. A rewrite that reintroduces an AI tell, or quietly drops a fact, number, or link from the original, is a regression; restore and rewrite again.
  • Non-convergent result. If the value proposition cannot be stated in one sentence, the copy is unfixable until it is clarified; report this blocked state with the unresolved value proposition rather than shipping copy that does not serve one.
  • Missing cta inputs. If any of the five required inputs cannot be obtained, stop and report which input is missing rather than guessing; a CTA designed on assumed inputs produces the universal failure mode (generic "Subscribe for more").
  • Multiple primary objectives (cta). If the user insists on more than one primary objective after pushback, flag it as a failure mode, deliver the strongest single-primary recommendation, and note the competing objectives as anti-patterns.
  • No valid archetype (cta). If the input combination maps to no archetype (for example, product or demo on a personal blog where the author is not the product), report the conflict and propose the closest valid alternative. Do not fabricate an archetype.
  • Missing hook brief. If topic, audience, language, length, or publication venue is unclear and material, stop and ask before generating. Do not invent a brief.
  • Anti-pattern match (hook). If a candidate matches the cull list, rewrite it before presenting. Never present a matched candidate.
  • No genuine choice (hook). If the 3-4 options collapse to flavors of one technique, regenerate across different levers per the diversification rule before presenting.
  • User says "more" or "none" (hook). Produce 3 different hooks (different techniques), not new candidates for the same hooks.
  • User says "blend 1A and 2B" (hook). Write one combined hook and check in again before proceeding.
  • Unverifiable statistic or quote (hook). If a candidate leans on a number or quote that cannot be cited accurately, replace it with a verifiable detail or cut the claim. Do not present an unsupported authority hook.
  • Partial results are never presented as done. The done predicate (free of AI-isms, matches the voice, fits the page type) must hold for every line handed back; lines that fail it are rewritten or withheld. Cta mode returns either the full structure or the blocked result naming the missing input; hook mode never presents fewer than 3 distinct options, and stops with the blocker named if 3 cannot be produced.
  • Non-mutation rule for cta and hook: those modes write nothing outside the conversation; recovery is re-running the interview or regenerating in conversation.

Output

Return, in order: for page mode, the writing-branch brief with marked inferences, 2-3 labeled alternatives, recommendation, edit notes, and pass result, or the editing-branch before/after diffs with labels, rationale, issue count, top pattern, and confidence; then VOICE.md only when offered and accepted. For cta mode, a single in-conversation recommendation: archetype selection with rationale, copy (headline, body, button, risk reversal), form (placement, visual weight, layout, proof), mechanism, A/B test plan, WCAG 2.2 accessibility check, 2-3 anti-pattern warnings, and 2-3 suggested next moves. For hook mode: working title, 3-4 numbered hook types with two A/B candidates each, the user's selection prompt, and after selection the chosen hook plus one sentence naming what it commits the opening to.

Files (outline-driven-development)
  • agents
    • openai.yaml 208 B
      interface:
        display_name: "Copywriting"
        short_description: "Use when asked to write or fix product/marketing copy, landing pages, UI strings, brand voice, AI tells, an end-of-article CTA, or a hook/lede."
      
  • references
    • cta-playbook.md 4.2 KB
      # CTA playbook
      
      Reference for `Mode cta` in the copywriting skill: the archetype decision tree, the recommendation structure, and the operating principles.
      
      ## Archetype decision tree
      
      ```
      context = INDEPENDENT / PERSONAL
      ├── objective = newsletter / email      → A: Author-signature subscribe
      ├── objective = try-it / direct action  → B: Inline action + source link
      ├── objective = reader support / tip    → C: Reader-supported funding link
      ├── objective = community               → D: Proof-counted community invite
      ├── objective = social follow           → A (variant: lead with social links)
      ├── objective = engagement              → E: Specific reply prompt
      └── objective = product / demo          → FLAG. Valid only where the author IS
          the product (consultants, solo founders, indie devs). Frame as "if you hit
          this, here's how I help", never "Book a Demo" verbatim.
      
      context = NEWSLETTER PUBLICATION
      ├── objective = growth / subs           → F: Share/restack + native widget
      ├── objective = engagement              → E: Specific reply prompt
      ├── objective = paid conversion         → G: Value-gap tease
      ├── objective = monetization / sponsor  → H: Inline sponsor block (not bottom)
      ├── objective = community               → D
      └── objective = direct purchase         → K (rare; BOFU only)
      
      context = BRAND / CONTENT MARKETING
      ├── stage = TOFU                        → I: Transitional asset (lead magnet)
      ├── stage = MOFU                        → J: Direct + transitional pair
      ├── stage = BOFU                        → K: Direct CTA + risk reversal
      ├── stage = Not applicable              → L: Value-statement subscribe (fallback)
      └── objective = engagement              → E (rarely right here)
      ```
      
      ## Recommendation structure
      
      Compose the recommendation in this exact structure:
      
      ```markdown
      ## Recommended CTA
      
      **Archetype:** [letter + name] **Why this fits:** [1-2 sentences naming the input combination]
      
      ### Content (copy)
      **Headline / value line:** > [exact text]
      **Body / proof line (1-2 lines):** > [exact text]
      **Button copy:** > [exact text]
      **Risk reversal / subtext (if applicable):** > [exact text, or "Omit: would feel forced"]
      
      ### Form (structure)
      - **Placement:** [end-only / end + sticky / end + mid-article repeat]
      - **Visual weight:** [low / medium / high, with justification]
      - **Layout:** [single button / button + text link / native widget cluster / one-line signature]
      - **Proof to co-locate:** [subscriber count / star count / testimonial / named recommenders / logo wall / none]
      
      ### Mechanism
      [Named mechanism + 1 sentence on why appropriate, OR "None: value statement carries it. Mechanisms would erode trust for this audience."]
      
      ### A/B test plan
      - **First test:** [single variable]
      - **Why this one first:** [1 sentence]
      - **Sample size consideration:** [qualitative volume check, or skip A/B - traffic too low]
      
      ### Accessibility check
      - **Color contrast:** [target ratio + concrete pairing if colors known]
      - **Touch target:** [size requirement]
      - **Semantic markup:** [<button> vs. <a> vs. form]
      - **ARIA:** [only if non-obvious]
      - **Keyboard / focus:** [requirement]
      - **Color-independence:** [non-color affordance]
      ```
      
      ## Operating principles
      
      - One primary CTA per post. Multiple competing CTAs is the dominant failure mode.
      - Match the voice of the publication. A personal-essay footer that reads like a SaaS landing page collapses credibility.
      - Specificity beats cleverness. "Get one essay a week on indie filmmaking" beats "Subscribe to our awesome newsletter." The "I want to ___" completion test is the cleanest filter for button copy.
      - Proof co-located with the ask. Place the honest signal (subscriber count, testimonial, logos, star count) inside or adjacent to the CTA block.
      - Mechanisms are tools, not garnish. Add urgency, scarcity, FOMO, or discount only when the context genuinely supports them; theatrical mechanisms erode trust.
      - Push back on bad asks. If the user wants a CTA that will fail (e.g., "Book a Demo" at the bottom of a beginner tutorial for first-time visitors), say so, propose the alternative, explain why, then deliver the original only with the failure mode flagged.
      
    • hook-catalog.md 9.6 KB
      # Hook catalog
      
      Reference for `Mode hook` in the copywriting skill: the five levers, the type-fit table, the 18-hook catalog, the anti-pattern cull, and language handling.
      
      ## The five levers
      
      A hook's only job is to make the reader want sentence 2. It does that through one of five levers, and a strong hook usually pulls two at once:
      
      1. **Open a gap**: pose something incomplete the reader needs to close (curiosity gap, question, open loop).
      2. **Break a prediction**: state something that violates the reader's prior (contrarian, definition reversal, surprising statistic).
      3. **Drop into a scene**: load sensory or specific detail that builds a vivid frame (in medias res, concrete detail, time anchor).
      4. **Promise a payoff**: name an outcome the reader wants (benefit, conditional, direct problem).
      5. **Borrow weight**: lean on a name, number, or quote that carries embedded authority (authority hook, statistic, quote with disagreement).
      
      ## Type-fit table
      
      | Article type | Strong hooks | Avoid |
      |---|---|---|
      | Technical deep-dive | concrete detail, statistic, contrarian, direct problem | personal confession, scene opener |
      | Personal essay | in medias res, personal confession, time anchor, definition reversal | bold claim, direct problem |
      | Opinion / contrarian | bold claim, definition reversal, contrarian, quote + disagreement | gentle setup, dictionary opener |
      | Tutorial / how-to | direct problem (PAS), promise, conditional | scene opener, historical analogy |
      | Reported / investigative | concrete detail, time anchor, in medias res, statistic | bold claim, definition reversal |
      | Listicle | curiosity gap, counted stakes, conditional | personal confession, in medias res |
      | Longform analysis | historical analogy, statistic, contrarian | direct problem |
      | Newsletter issue | personal confession + open loop, conditional, curiosity gap | dictionary opener |
      
      ## The 18-hook catalog
      
      Each entry explains what the hook does, gives one example (EN or FR), and states when to use or avoid it.
      
      1. **Curiosity Gap**: open an information gap the reader wants closed. EN: "How does Shen Yun make any money? Short answer: they don't." Use when the gap can honestly be closed in 2-3 sentences and the reader cares about it. Avoid vague gaps ("You won't believe what happened next") the reader cannot even guess at.
      2. **Contrarian**: knock down a consensus belief the reader holds. EN: "Prevailing wisdom claims the best way to achieve what we want in life is to set specific, actionable goals." Use when a defensible non-consensus view exists and 200-400 words are available to defend it. Avoid strawmen and contrarianism for its own sake.
      3. **Bold Claim / Promise**: state the outcome upfront, before the proof. EN: "At 60 miles an hour the loudest noise in this new Rolls-Royce comes from the electric clock." Use when the promise can be delivered concretely. Avoid promises larger than the payoff; they destroy trust permanently.
      4. **Scene Opener / In Medias Res**: drop the reader inside a specific moment, no setup. EN: "Frank Sinatra, holding a glass of bourbon in one hand and a cigarette in the other, stood in a dark corner of the bar between two attractive but fading blondes who sat waiting for him to say something." Use for longform, profile, reported piece, essay. Avoid short technical pieces where the reader has not earned the scene.
      5. **Surprising Statistic**: lead with a number that violates the prior. EN: "You have five seconds to get people's attention." Use when the number is genuinely surprising and citable accurately. Avoid vague stats ("studies show 90%...") and stats that confirm the reader's prior.
      6. **Question**: pose a question the reader actually wants answered. EN: "If you collected lists of techniques for doing great work in a lot of different fields, what would the intersection look like?" Use when the reader was implicitly carrying the question. Avoid "Have you ever wondered...?", "Did you know...?", "What if I told you...?", they presuppose curiosity not yet formed.
      7. **Quote + Disagreement**: borrow weight, then twist. EN: "Steve Jobs said people don't know what they want until you show it to them. For SaaS, this is exactly backwards." Use when a real quote exists that supports or genuinely contrasts the point. Avoid misattributed Einstein/Seneca/Confucius/Bouddha platitudes.
      8. **Personal Confession**: admit something vulnerable, then universalize. EN: "I cheated on my husband." Use for personal byline, essay, newsletter. Avoid corporate byline, technical articles, and performative vulnerability ("I almost didn't write this...").
      9. **Concrete Specific Detail**: replace abstraction with a single vivid detail. EN: "John Laroche is a tall guy, skinny as a stick, pale-eyed, slouch-shouldered, and sharply handsome, despite the fact that he is missing all his front teeth." Use for profile, reported piece, contrarian biographical setup. Avoid specificity that does not advance the thesis (clutter).
      10. **Pattern Interrupt**: break expected rhythm with a fragment. EN: "This is not an article about productivity. It's an article about identity." Use for rhythm-driven content and opinion pieces. Avoid using it every article; it becomes its own pattern fast.
      11. **Direct Problem (PAS)**: name the pain, sharpen it, hint at solution. FR: "Vos articles ne sont pas lus. 80% des lecteurs décrochent dès le deuxième paragraphe. Et la solution n'est pas celle que vous croyez." Use for tutorial, how-to, sales-adjacent content. Avoid manufactured problems; the pain must be real and recognizable.
      12. **Promise / Benefit**: state a specific, bounded outcome. EN: "By the end of this article, you'll know exactly when to use goroutines and when not to." Use for tutorial, how-to. Avoid vague promises ("Learn how to be more productive"); add a time bound or a number to anchor it.
      13. **Historical Analogy**: open with a vignette from history, pivot to the present. EN: "In 1965, Robert Lucas wrote a four-page paper that broke macroeconomics." Use for longform analysis, opinion piece, idea essay. Avoid tutorials and news pieces; reads as indulgent.
      14. **Definition Reversal**: "X is not what you think. It's Y." EN: "Procrastination isn't laziness. It's a fight between two parts of your brain." Use for opinion piece, contrarian deep dive. Avoid when the reframe is just a slight angle; sounds gimmicky.
      15. **Authority Borrow**: lead with a name plus a specific action. EN: "When Steve Jobs returned to Apple in 1997, he killed 70% of the product line in his first year." Use for business piece, profile, analytical essay. Avoid name-dropping without payoff; the action must be specific and relevant.
      16. **Time Anchor**: lead with a specific date, hour, or moment. FR: "Octobre 2005, Bondy. Trois journalistes installent un blog dans un appartement de la cité Blanqui." Use for reported piece, retrospective, "why now" framing. Avoid vague anchors ("recently", "these past few years"); use a specific date or cut the framing.
      17. **Conditional ("If you... then this")**: self-segment the reader. EN: "If you write for a living, you've probably been taught to start with context. Don't." Use for tutorial, advice piece, segmented audience. Avoid conditions too broad ("If you've ever felt stuck...") that segment nobody.
      18. **Open Loop**: start something, withhold the resolution. EN: "He pressed Send and waited. Forty-seven seconds later, the company was worth 4 billion dollars less." Use for longform where the journey matters as much as the answer. Avoid unresolved loops; they create disproportionate betrayal when the article ends without paying off.
      
      ## Anti-pattern cull
      
      Never propose any of these. Run every candidate through this list before presenting; if a candidate matches, rewrite.
      
      - "In today's fast-paced world..." / "À l'heure du tout-numérique" / "À l'ère de l'IA" / "Dans un monde où..."
      - "Have you ever wondered...?" / "Vous êtes-vous déjà demandé...?"
      - Dictionary opener played straight ("Productivity, defined as...")
      - "In this article, I'll discuss..." / "Dans cet article, nous allons voir..."
      - Generic stats without source ("90% of people...", "Les études montrent...")
      - Misattributed Einstein / Seneca / Confucius / Bouddha quotes
      - "I'm not an expert, but..." / "Je ne suis pas spécialiste mais..."
      - Three rhetorical questions in a row
      - "Imagine waking up..." without a specific scene
      - "Hot take:", "Unpopular opinion:", "Voici la vérité que personne ne veut entendre..."
      - "At [Company], we believe..." / "Chez [Entreprise], nous pensons..."
      - "Recently,..." / "Récemment,..." without a specific date
      - "You're not alone."
      - Current AI tells: "It's not just X, it's Y", "Picture this:", "Imagine a world where...", "What if I told you...", "Whether you're a seasoned X or a curious newcomer...", "In the realm of...", "Navigating the landscape of...", "Unlock the power of...", "Dive into...", "Buckle up,", "Let's dive in", "Crucially,/Notably,/Importantly,/Essentially," as sentence openers. French AI tells: "Dans un monde en constante évolution", "Plongez dans...", "Découvrez comment...", "Par ailleurs,...", "Notamment,...", "Il est crucial de...".
      
      ## Language handling
      
      If the audience is French, write in French and apply the _attaque journalistique_ register: concrete scene-setting, restrained tone, dated anchors, formal "vous" or restrained tutoiement. Do not translate American hype tropes literally ("You'll never believe..." becomes "Vous n'allez pas en croire vos yeux", which reads as scam in French); French marketing-skepticism is higher and high promises trigger _réactance_ faster. If English, default to direct-response register for marketing or tutorial content and longform register for essays and reported pieces. If bilingual, produce hooks in both languages and label clearly.
      
  • SKILL.md 30.6 KB
    ---
    name: copywriting
    description: 'Use when asked to write or fix product/marketing copy, landing pages, UI strings, brand voice, AI tells, an end-of-article CTA, or a hook/lede. Not for whole articles: use technical-article-writer.'
    ---
    
    # Copywriting
    
    ## Contract
    
    | Field | Bound contract |
    |---|---|
    | Trigger | Write or fix product or marketing copy, landing pages, UI strings, or brand voice, or remove AI tells (page); design or review a bottom-of-article CTA (cta); write a hook, lede, or accroche for long-form content (hook). |
    | Authority | Reversible local. Writes only user-facing copy and brand voice outputs in the working tree; cta and hook modes emit chat output only. Rollback is version control. No remote mutation. |
    | Side effect | Creates or edits copy files and brand voice outputs in page mode; cta and hook modes produce conversation only. |
    | Done | Page: copy is free of AI-isms, matches the voice chart, and fits the page type. Cta: the full recommendation structure is composed. Hook: the user has selected a hook and its commitments are named. |
    
    ## Inputs
    
    - Mode selector: `page`, `cta`, or `hook`. Auto-detect from the ask: a bottom-of-article call-to-action routes to `cta`; a hook, lede, or accroche for long-form content routes to `hook`; anything else routes to `page`. An explicit mode argument overrides auto-detection.
    - Mode page: copy to fix, or a page type and goal. Select the editing branch when copy exists or the user pasted it; the writing branch when nothing is written yet. For a genuinely ambiguous request ("improve this" with no copy in scope), ask one question, then commit.
    - Mode cta: article context, primary objective, audience and relationship, funnel stage, and mechanism preference, collected in the interview step.
    - Mode hook: topic, audience, target language (EN, FR, or both), approximate length, and publication venue; an optional existing draft opening, treated as Option 0 and never silently discarded.
    - Optional inputs, settled before writing: page purpose, audience, product, traffic source, and any voice file (`VOICE.md`, `BRAND.md`, `docs/voice.md`). If an input is missing, infer it and name the inference so the user can correct it against real copy.
    
    ## Procedure
    
    Auto-detect the mode. Do not ask which mode; infer it from the ask.
    
    ### Mode page: writing new copy
    
    1. **Gather context.** Settle four fields before writing, from the user or from files; infer and name any field the files do not settle. (1) Page purpose: the one action this page drives. (2) Audience: the specific reader, their job title, pain, and what they have already tried. (3) Product: what it does and the concrete user outcome. (4) Traffic source: where the reader comes from. Traffic source sets temperature: cold needs more Why; warm can lead with How or What. Done when: all four context fields are settled from the user or files, with inferences named.
    2. **State the brief, then write.** State the brief and keep going; mark every inferred field so the user corrects it against copy, not against a question. Stop and ask before writing only when a wrong guess makes the work useless or unsafe: the copy ships in this turn with no review, or the goal is genuinely unknown and each candidate goal produces different copy. Done when: the brief is stated with inferred fields marked, or the run stops because a wrong guess would make the work useless.
    3. **Discover brand voice.** Check these sources in order and stop at the first match. (1) A voice file in the repo (`VOICE.md`, `BRAND.md`, `docs/voice.md`); authoritative when it exists. (2) Existing copy: README headers, copy files, or shipped marketing pages. (3) Inference: B2B SaaS direct and confident, consumer apps warmer, developer tools terse and honest. A discovered voice outranks the word lists: if the voice file or shipped copy uses a listed word as a signature, keep it. Locale and spelling convention come from the voice. When no voice file exists and the product will need one, offer to write `VOICE.md` alongside the copy using the voice chart structure below. Voice is constant (the brand personality); tone adapts to the reader's state: Done when: brand voice is discovered from the first matching source, with locale and spelling convention recorded.
    
       | Reader state | Tone | Example |
       |---|---|---|
       | Frustrated (error, failure, block) | Empathetic, solution-first, never blaming | "Payment failed. Your card was declined. Try a different card." |
       | Confused (first use, complex feature) | Patient, one step at a time | "Connect your bank to see spending insights. We'll walk you through it." |
       | Confident (routine task, return visit) | Efficient, minimal | "Saved" |
       | Cautious (high stakes, data loss) | Serious, transparent, no nudging | "Delete account? You'll lose all data and this can't be undone." |
       | Successful (completion) | Positive, proportional, brief | "Your changes are live." |
    
       A tone shift is not voice drift; drift is when the copy reads as a different brand, not the same brand in a different moment.
    
    4. **Choose framework and load page norms.** Route on what the copy is. Product-state copy (error, empty, success, loading, permission) or an action label: apply the UI state copy rules below and stop; persuasion frameworks do not apply to a button that deletes something. Marketing copy: pick the primary framework from the brief and layer freely: Done when: the framework is chosen and page norms are loaded, or UI state copy rules are applied for product-state copy.
    
       | Situation | Lead framework |
       |---|---|
       | Cold traffic, unfamiliar product | Why/How/What (Simon Sinek) |
       | Feature-heavy product | Benefit Not Feature |
       | High-trust audience, low awareness | Show Don't Tell |
       | Transactional page, known intent | CTA Clarity |
       | Long-form sales page | Problem → Agitate → Solution (PAS) |
    
       The nine frameworks: **Why/How/What** (lead with Why, not What; order Why → How → What), **PAS** (name the pain, amplify the cost, present the solution), **AIDA** (Attention → Interest → Desire → Action for cold traffic), **StoryBrand** (customer is hero, product is guide; never make the product the hero), **BAB** (Before → After → Bridge; warmer and aspirational vs PAS confrontational), **Show Don't Tell** (replace adjectives with a specific fact, number, or scenario), **Benefit Not Feature** (lead with the outcome for the user; mention the mechanism only after the benefit is clear), **Sentence Economy** (every sentence earns its space; cut openers like "In order to", "It is important to note that"), **CTA Clarity** (action verb + what they get + qualifier; never two CTAs with the same verb on one screen). For a known page type, apply its norms:
    
       - Homepage: establish what the product is and who it is for; pick the highest-value segment and write for them. Sections in order: hero (lead with Why), social proof above fold, problem/pain, solution/benefits (one benefit per point), how it works, testimonials, final CTA. Do not add a secondary CTA that dilutes the primary action.
       - Landing page: drive one action; message must match what brought the reader. Headline mirrors the ad or email promise. PAS for problem-aware traffic, AIDA for cold. One CTA only; strip navigation and footer links.
       - Pricing page: help visitors choose. Name plans by buyer type, not tier ("Solo / Team / Company" beats "Basic / Pro / Enterprise"). Sections: value restatement, plan comparison (2-4 plans), feature differentiators, FAQ, social proof by tier, risk reversal near the CTA.
       - Feature page: connect a feature to an outcome for visitors already evaluating. Feature → Benefit → Outcome chain. Skip broad setup; go straight to the specific outcome with a number or example.
       - About page: build trust; every element passes the "so what does this mean for me?" test. Mission as a customer benefit, origin story tied to the customer's frustration, human team, 3-5 customer-relevant values, a CTA pointing to the product.
    
    5. **Write 2-3 alternatives.** Label them Option A, B, C. Three for a page, hero, or campaign; two for a single string like a CTA or subject line. Each applies the chosen framework visibly, leads with Why, uses no banned word, includes a headline, subhead, and at least one CTA, and is structurally different, not the same idea with new adjectives. Done when: 2-3 labeled alternatives are written, each structurally different with no banned words.
    6. **Recommend and explain.** Pick one; state which and why in one sentence. For each unpicked option, give one specific edit note. Done when: one option is recommended with a one-sentence reason and one edit note per unpicked option.
    7. **Verify every line before handing back.** Check each line of every option: leads with Why, names a concrete outcome, no banned word, no em dash or stand-in. Check the option whole: it does not hand the brief's wording back (prompt echo), and every specific the user supplied appears rather than a stock default. New copy containing a banned word is not an option to present; rewrite it first. Done when: every line of every option passes the verification checks (Why-led, concrete outcome, no banned word, no em dash, no prompt echo, specifics present).
    
    ### Mode page: editing existing copy
    
    Set the edit posture first. **Point edit:** the user named one line, word, or section; change only the target plus minimum connective tissue; do not turn a point edit into a page audit. **Restoration:** the copy has a clear voice, angle, or opinion; preserve its vocabulary level, emphasis, omissions, sentence shape, and positioning; fix specific failures without rebalancing the argument. **Rebuild:** the copy is generic, contradictory, or has no perspective; reconstruct from the brief, but never invent proof.
    
    1. **Read all copy-bearing files.** Scan every reader-facing surface: README headers, landing components, hero, CTAs, product descriptions, feature lists, onboarding strings, meta descriptions, email subjects. Read the voice file too if one exists; it settles register and locale and overrides the word lists for any word it names as a signature. Ask which files if unclear; never audit copy not read in context. Done when: every copy-bearing file is read, including the voice file if one exists.
    2. **Set the value proposition.** Write one sentence before auditing: "[User] can now [do X] without [old pain]." Every flag and rewrite serves it. If the sentence cannot be written confidently, ask; the copy is unfixable until the value proposition is clear. Done when: the value proposition is stated in one sentence or the run stops because it cannot be written confidently.
    3. **Audit against persuasion frameworks.** Check every major copy block against the nine frameworks and carry forward only the highest-impact problems; the flag budget is set in Step 6. Done when: every major copy block is checked against the nine frameworks with only highest-impact problems carried forward.
    4. **Remove AI writing patterns.** If the user asked for AI pattern removal, run this first, before the sweeps. Flag each AI-ism with `[AI-ISM]` plus its type. **Tier 1 words** (always replace): delve, landscape (metaphor), tapestry, realm, paradigm, embark, beacon, testament to, robust, comprehensive, cutting-edge, leverage (verb), pivotal, underscores, meticulous, seamless, game-changer, utilise, nestled, vibrant, deep dive, unpack, showcase, unlock, intricate, holistic, actionable, impactful, learnings, thought leadership, best practices, synergy, in order to, due to the fact that, serve as, commence, keen (as intensifier). **Tier 2 clusters** (flag when 2+ in one paragraph): harness, navigate, foster, elevate, unleash, streamline, empower, bolster, spearhead, resonate, revolutionise, facilitate, underpin, nuanced, crucial, ecosystem (metaphor), myriad, plethora, catalyse, transformative, cornerstone, paramount, burgeoning, nascent, overarching. **Tier 3** (flag only at high density, ~3%+): significant, innovative, effective, dynamic, compelling, unprecedented, exceptional, remarkable, sophisticated, world-class, state-of-the-art. **Structural patterns:** formulaic openings ("In the rapidly evolving world of..."), rhetorical-question openers, engagement hooks ("Here's the thing", "Plot twist:"), copula avoidance ("serves as", "features", "boasts"), synonym cycling, vague attributions ("Experts believe"), significance inflation, false ranges, em dashes and `--`/spaced-hyphen stand-ins (zero, in headings and body alike; a single occurrence is a failure). **Chatbot artefacts** (remove entirely): "I hope this helps", "Great question", "Let's dive in", any "let's + verb" transition, chain-of-thought leaking ("Let me think step by step", "Step 1:"), acknowledgement loops. **Drafting tells** (survive a word-level pass; check separately): prompt echo (the draft reuses the brief's own phrasing), generic default over the supplied specific (a real number or name replaced by a category placeholder), uniform confidence (every line lands at the same pitch). **Severity triage:** P0 (credibility killers: cutoff disclaimers, chatbot artefacts, vague attributions, significance inflation, a supplied specific replaced by a generic default) fix immediately; P1 (prompt echo, Tier 1 words, template phrases, "let's" openers, formulaic openings, engagement hooks, bold overuse, any em dash) fix before publishing; P2 (generic conclusions, compulsive rule of three, uniform paragraph length, announced honesty, copula avoidance, overused transitions, Tier 2 clusters) fix when time allows. A clean P0+P1 pass is publishable. Done when: AI writing patterns are flagged with `[AI-ISM]` labels and triaged by severity, or skipped when not requested.
    5. **Run seven sweeps.** Run all seven in order; each targets a distinct failure mode. Flag everything before fixing. (1) **Clarity:** confusing structure, unclear pronouns, undefined jargon, claims readable two ways. Flags `[JARGON]`, `[VAGUE]`. (2) **Voice and tone:** formal/casual shifts, register mismatch; identify the dominant voice and standardise to it. Flag `[VOICE-DRIFT]` on the line that reads as a different brand, not where the same brand meets a different moment. (3) **So what:** every claim answers "why should the reader care?". Flags `[DEAD-WEIGHT]`, `[FEATURE-NOT-BENEFIT]`. (4) **Prove it:** back every claim with a named testimonial, case study, stat, or third-party validation. Flag `[NO-PROOF]`; use `[PLACEHOLDER: add proof: stat / testimonial / example]` when the proof is unknown. (5) **Specificity:** replace vague time, quantity, and outcome with concrete detail. Flag `[VAGUE]`. (6) **Emotion:** name the pain the reader already feels before selling the outcome; mirror the reader's actual state at this point in the page. Flag `[PAIN-NOT-NAMED]`. (7) **Zero risk:** remove friction at and near CTAs; address objections, add trust signals, clarify the next step, add risk reversal. Flag `[WEAK-CTA]` on any CTA standing alone without a qualifier or trust signal. Finish with the compound adjective hyphenation pass: hyphenate a multi-word modifier before the noun it describes ("a 7-day free trial", "real-time updates", "`{{days}}-day free trial`"); leave it open when it stands alone as a noun phrase ("The trial lasts 7 days"); never hyphenate an `-ly` adverb ("a fully managed service"). Fix hyphenation silently rather than flagging it. Done when: all seven sweeps are run in order with flags applied before fixes, and the hyphenation pass is complete.
    6. **Flag weakest elements.** Attach an inline label to every weak line, using exactly these labels: `[WHAT-NOT-WHY]` (leads with product, not motivation), `[FEATURE-NOT-BENEFIT]`, `[TELL-NOT-SHOW]` (adjective claim without proof), `[VAGUE]`, `[PASSIVE]`, `[VOICE-DRIFT]`, `[PAIN-NOT-NAMED]`, `[DEAD-WEIGHT]`, `[JARGON]`, `[NO-PROOF]`, `[WEAK-CTA]`, `[STATE-COPY]` (vague, leaky, or dead-end state string, or a destructive CTA labeled Confirm/OK/bare verb; apply the UI state copy rules below before using this label), `[AI-ISM]`. Flag the 3-7 weakest elements, prioritised by impact; over-flagging dilutes into a list nobody acts on. One occurrence is one flag; do not stack `[TELL-NOT-SHOW]` and `[AI-ISM]` on the same word. Done when: the 3-7 weakest elements are flagged with inline labels, prioritised by impact.
    7. **Rewrite flagged sections.** Cut hard (same meaning in half the words). Lead with Why, not What. Name the concrete outcome, not the capability. Replace adjectives with proof. Make CTAs outcome-specific. Every sentence adds new information or gets cut. A CTA stays short. When replacing AI-isms, rewrite the sentence; do not swap the flagged word for a synonym. Done when: every flagged section is rewritten with the same meaning in fewer words, leading with Why and naming concrete outcomes.
    8. **Output before/after diff.** For each flagged section, show the original, the labels, the rewritten text, and one sentence explaining the change. End with a summary: issue count, top pattern, and confidence (note if copy context was limited). Verify each "After" line: leads with Why, names a concrete outcome, no banned word, no em dash or stand-in, and every fact, number, and link from the "Before" still present. Then apply the leave-it-alone test: every change must fix a named failure from the audit; if it is merely different, restore the original. Done when: a before/after diff is output for each flagged section with labels, rationale, and a summary, and every "After" line passes verification.
    
    ### Mode cta: end-of-article call-to-action
    
    The archetype decision tree, the exact recommendation structure, and the operating principles live in `references/cta-playbook.md`.
    
    1. **Interview.** Ask the five inputs in order, one at a time with 2-4 tappable options, skipping any already supplied; fall back to free text only when the answer cannot be enumerated. (1) Article context: personal or independent blog or essay, newsletter or paid publication, brand or company content-marketing blog, other. (2) Primary objective: newsletter or email subscription, social follow, lead generation (gated asset), product or service signup or free trial, demo or sales call booking, direct purchase, community join, engagement (reply, comment, share), reader support (paid sub or tip), try-it or direct action, other; if the user lists more than one, ask which is primary, because choosing multiple objectives is the dominant cause of CTA failure. (3) Audience and relationship: first-time visitor, returning reader not subscribed, existing subscriber or customer, mixed or unknown. (4) Funnel stage: TOFU (discovery, no buying intent), MOFU (evaluating, comparing), BOFU (ready to act), not applicable. (5) Mechanism preference, asked only if a mechanism could legitimately help (for skeptical or repeat-reader audiences default to none or value-only without asking): none or value-only, curiosity gap, reciprocity (free asset first), discount or offer, urgency (real deadline), scarcity or FOMO, social proof. Capture volunteered constraints (length limit, brand voice, no popups, language, formality). Done when: all five inputs are collected or reported missing.
    2. **Diagnose.** Map the inputs to one archetype via the decision tree in `references/cta-playbook.md`. Done when: the inputs are mapped to one archetype.
    3. **Compose the recommendation** in the exact structure given in `references/cta-playbook.md`: archetype with rationale, content copy (headline, body, button, risk reversal), form (placement, visual weight, layout, proof), mechanism, A/B test plan, and a WCAG 2.2 accessibility check. Done when: the recommendation is composed in the exact structure with all sections filled.
    4. **Anti-pattern warnings.** After the recommendation, list 2-3 anti-patterns the user is at risk of given their inputs, as a contrarian check. Failure modes to call out by name: multiple competing CTAs, generic "Subscribe for more" or "Learn More", mechanism mismatch (urgency or scarcity where none exists), SaaS landing-page voice on a personal essay, proofless ask, "Book a Demo" on TOFU content, open-ended reply questions on social. Done when: 2-3 anti-patterns are listed as a contrarian check.
    5. **Enforce the operating principles** in `references/cta-playbook.md` during composition: one primary CTA per post, publication voice, specificity over cleverness, proof co-located with the ask, mechanisms only when the context supports them, and pushback on bad asks. Done when: the operating principles are enforced during composition.
    6. **Language and style.** Adapt copy to the user's stated brand voice, the article's language (never default to English), the publication's existing cadence, and the reader's expertise level. Honor formality cues (tu/vous, du/Sie) and flag the choice. If non-English, translate the content section but keep structure headings in English. Done when: copy is adapted to brand voice, language, cadence, and expertise level with formality cues flagged.
    7. **Offer next moves.** Suggest 2-3 follow-ups: steelman the opposite CTA, a variant for a different audience or platform, or an end-to-end article review for CTA-supporting signals. Done when: 2-3 follow-ups are suggested.
    
    ### Mode hook: hook, lede, or accroche
    
    A hook's only job is to make the reader want sentence 2, through one of five levers (a strong hook usually pulls two at once): open a gap, break a prediction, drop into a scene, promise a payoff, borrow weight. The five levers in detail, the type-fit table, the 18-hook catalog, the anti-pattern cull, and language handling live in `references/hook-catalog.md`.
    
    1. **Confirm the brief.** Ask before generating if a material input field is missing. Done when: the brief is confirmed or missing material fields are requested.
    2. **Pick 3-4 hooks** from the catalog that are genuinely different, different levers, not three flavors of the same technique. Diversification rule: across the options include at minimum one intellectual hook (contrarian, definition reversal, historical analogy, curiosity gap), one sensory hook (in medias res, concrete detail), and one reader-direct hook (conditional, direct problem, promise). Done when: 3-4 genuinely different hooks are selected, each pulling a different lever.
    3. **Write 2 candidates per hook**, specific to the user's article. The two candidates within one hook explore different angles (different anecdote, statistic, or scene), not rewordings of each other. Done when: 2 candidates per hook are written, each exploring a different angle.
    4. **Apply the quality gates** to every candidate: specific beats abstract (replace "many companies" with "Stripe, Shopify, Vercel"; replace "recently" with a date; replace "studies show" with the actual finding or cut the claim); the first sentence must force the second (read each candidate cold; if sentence 2 would not be clicked after sentence 1, rewrite); match technique to article type using the type-fit table. Done when: every candidate passes the quality gates.
    5. **Run the anti-pattern cull** on every candidate. If a candidate matches any entry, rewrite it before presenting. Done when: every candidate passes the cull or is rewritten.
    6. **Present and let the user pick.** Present using the Output format, ask the user through the question tool, and wait. Do not pick for them. Done when: options are presented and the user is asked to pick.
    7. **Name the commitment.** After the pick, name what the choice commits the rest of the article to. A contrarian hook commits paragraphs 2-3 to defending the non-consensus claim. A scene opener commits the next section to resolving or productively delaying the scene. Done when: the chosen hook's opening commitments are named in one sentence.
    
    ### UI state copy rules (for product-state strings and the `[STATE-COPY]` label)
    
    - Destructive CTAs (`rule/destructive-names-action`, `rule/no-confirm-ok-labels`): Verb plus Noun naming the exact object ("Delete project", not "Confirm" or "OK"). Never label a consequential action Confirm, OK, Yes, or a bare verb.
    - Canonical verbs (`rule/canonical-verb`): one verb per operation, used consistently; pick the verb whose consequence matches (Delete = permanent, Remove = detach without destroying, Archive = reversibly hide, Discard = drop unsaved edits, Cancel = abandon an in-progress action).
    - Error (`rule/error-states-recovery`): state what happened, why when known, and the recovery action; never raw exceptions or a bare "Something went wrong". Separate field-level from surface-level errors; preserve everything the user typed.
    - Success (`rule/success-state-specific`): confirm in past tense what happened to which object, proportional to the action.
    - Empty (`rule/empty-state-action`): name the object and offer the first action; no dead ends. Three types: never-had-any (guide the first step), filtered-to-zero (clear the filter), user-cleared (confirm completion; the one empty state that needs no CTA).
    - Loading (`rule/loading-state-specific`): say what loads and, for long operations, roughly how long; keep the triggering control's label stable.
    - Permission (`rule/permission-benefit-first`): state the user benefit before the permission ask; ask in context when the feature is first used.
    - Copy without the screen (`rule/reads-without-seeing`): copy must work when heard; field errors read sensibly after their label; link and button text names the destination or action; no directional words ("above", "below", "here").
    - Length budgets (size for the tightest surface first; leave 30-40% headroom for translation): button or CTA 2-4 words; title 3-6 words; error message 12-18 words including the recovery step; any sentence the user must act on 14 words (8 reads at full comprehension).
    
    ### Banned words
    
    The never-write set, absolute unless a voice file names one as a signature: delve, leverage (verb), robust, seamless, holistic, paradigm, game-changing, cutting-edge, innovative, synergy, revolutionary, effortless, world-class, powerful, showcase, unlock. Also ban **"simple"** as a claim ("our simple onboarding"): never earned upfront, reads as an unkept promise.
    
    ### Voice chart structure (when offering to write `VOICE.md`)
    
    Three to five concepts. Each concept has three parts: (1) a brand principle, one word or short phrase; (2) two or three adjectives naming how it shows up in writing; (3) a Do and Don't pair of real interface or page strings. The Don't side is the useful half: make it the plausible near-miss the team actually ships, not a strawman. Start from shipped copy, not brand values. Record locale and spelling convention, house spellings, and any word the brand uses deliberately that a generic list would flag. Name what the voice is not ("Confident, not boastful").
    
    ## Failure and recovery
    - Invented audience or goal. Copy written without a goal and value proposition reads well and solves the wrong problem. If a context field cannot be settled from files or the user, infer it and name the inference; never present an inference as a fact. Stop and ask only when a wrong guess makes the work useless or unsafe.
    - Invented proof. Never fabricate a number, testimonial, or statistic. Use `[PLACEHOLDER: add proof: ...]` and let the user supply it.
    - Locale or voice regression. A US-spelling rewrite on an en-AU product ships as a regression across every string it touches. Check existing copy and the voice file before switching spelling or tone; a discovered voice outranks the word lists.
    - Point-edit scope creep. Do not turn a named point edit into a page audit; change only the target plus minimum connective tissue.
    - Restoration over-reach. Do not rebalance the argument or replace a clear lead with a cleverer one; fix named failures only.
    - AI-ism reintroduced or specific dropped. A rewrite that reintroduces an AI tell, or quietly drops a fact, number, or link from the original, is a regression; restore and rewrite again.
    - Non-convergent result. If the value proposition cannot be stated in one sentence, the copy is unfixable until it is clarified; report this blocked state with the unresolved value proposition rather than shipping copy that does not serve one.
    - Missing cta inputs. If any of the five required inputs cannot be obtained, stop and report which input is missing rather than guessing; a CTA designed on assumed inputs produces the universal failure mode (generic "Subscribe for more").
    - Multiple primary objectives (cta). If the user insists on more than one primary objective after pushback, flag it as a failure mode, deliver the strongest single-primary recommendation, and note the competing objectives as anti-patterns.
    - No valid archetype (cta). If the input combination maps to no archetype (for example, product or demo on a personal blog where the author is not the product), report the conflict and propose the closest valid alternative. Do not fabricate an archetype.
    - Missing hook brief. If topic, audience, language, length, or publication venue is unclear and material, stop and ask before generating. Do not invent a brief.
    - Anti-pattern match (hook). If a candidate matches the cull list, rewrite it before presenting. Never present a matched candidate.
    - No genuine choice (hook). If the 3-4 options collapse to flavors of one technique, regenerate across different levers per the diversification rule before presenting.
    - User says "more" or "none" (hook). Produce 3 different hooks (different techniques), not new candidates for the same hooks.
    - User says "blend 1A and 2B" (hook). Write one combined hook and check in again before proceeding.
    - Unverifiable statistic or quote (hook). If a candidate leans on a number or quote that cannot be cited accurately, replace it with a verifiable detail or cut the claim. Do not present an unsupported authority hook.
    - Partial results are never presented as done. The done predicate (free of AI-isms, matches the voice, fits the page type) must hold for every line handed back; lines that fail it are rewritten or withheld. Cta mode returns either the full structure or the blocked result naming the missing input; hook mode never presents fewer than 3 distinct options, and stops with the blocker named if 3 cannot be produced.
    - Non-mutation rule for cta and hook: those modes write nothing outside the conversation; recovery is re-running the interview or regenerating in conversation.
    
    ## Output
    Return, in order: for page mode, the writing-branch brief with marked inferences, 2-3 labeled alternatives, recommendation, edit notes, and pass result, or the editing-branch before/after diffs with labels, rationale, issue count, top pattern, and confidence; then `VOICE.md` only when offered and accepted. For cta mode, a single in-conversation recommendation: archetype selection with rationale, copy (headline, body, button, risk reversal), form (placement, visual weight, layout, proof), mechanism, A/B test plan, WCAG 2.2 accessibility check, 2-3 anti-pattern warnings, and 2-3 suggested next moves. For hook mode: working title, 3-4 numbered hook types with two A/B candidates each, the user's selection prompt, and after selection the chosen hook plus one sentence naming what it commits the opening to.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related