# evidence-based-copywriting

Adopt this skill: https://proskills.md/skills/other/arome3-evidence-based-copywriting-skills-evidence-based-copywriting

Page: https://proskills.md/skills/other/arome3-evidence-based-copywriting-skills-evidence-based-copywriting
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/evidence-based-copywriting/SKILL.md
size: 8042
upstream: https://github.com/arome3/evidence-based-copywriting/blob/main/skills/evidence-based-copywriting/SKILL.md

````text
---
name: evidence-based-copywriting
description: Produces and audits externally published marketing copy where factual claims must survive scrutiny — landing pages, product pages, launch emails, one-pagers, search/social metadata. Every statistic, competitor comparison, capability description, and proof point is traced to a fetched source or the project's own documents, labeled, and adversarially verified before it ships. Use when writing or rewriting high-stakes marketing copy; when copy must pass legal, compliance, brand, or claims review; when the audience is skeptical technical or executive buyers; when the company has little or no customer proof yet (pre-launch, zero customers); or when auditing existing copy for unsupported claims, invented capabilities, unverified statistics, or AI-slop language.
license: MIT. See LICENSE for complete terms.
compatibility: Full source verification requires internet access (web search and URL fetching). A no-network fallback is defined in SKILL.md.
metadata:
  author: Abraham Onoja (Arnen Labs)
  version: "1.1.0"
---

# Evidence-Based Copywriting

## Overview

**A claim that cannot be traced to a source you fetched or to the project's own documents does not ship.** That single rule is also US law for advertisers: the FTC requires a "reasonable basis" for objective claims *before* they are disseminated, not after a challenge (see `references/evidence-standards.md`). This skill turns that standard into a working pipeline: ground → research → write → verify → ship.

The output is not just copy. It is copy plus its audit trail: a fact base, per-section annotations with labeled sources, flagged open decisions, and a checklist a reviewer can falsify.

## The two failures this skill exists to stop

Baseline testing shows capable writers (human and model) rarely invent logos or testimonials anymore. They fail in two subtler ways:

1. **Citation without verification.** Real-sounding statistics with plausible URLs, written from memory, never fetched — sometimes shipped with a "verify before launch" note. Stats go stale, get superseded, or never said that. A TODO is not substantiation.
2. **Capability and terms fabrication.** Invented product mechanisms ("agentless sensor", "read-only connector", "syscall baselining"), commercial terms ("rate locked for life", "source-code escrow"), and architecture details that no document establishes. These *feel* like copywriting latitude. They are unsubstantiated claims — the FTC doctrine covers implied claims, and invented terms become contract disputes.

If you notice yourself doing either, stop and route the item to the fact base as an open question.

## Workflow

Copy this checklist into your working notes and check items off as you complete them:

```
Evidence-Based Copy Pipeline
[ ] 1. GROUND    — fact base built from project documents; open questions listed
[ ] 2. RESEARCH  — external evidence fetched + verified; competitors mapped; buyer language sampled
[ ] 3. WRITE     — deliverable drafted from the template, claims labeled inline
[ ] 4. VERIFY    — adversarial review passed; deterministic checks pass
[ ] 5. SHIP      — checklist marked honestly; open decisions flagged to the owner
```

### 1. Ground

Fill in `templates/fact-base-template.md` from the project's own documents (strategy docs, spec, pricing sheet, founder answers). Read every document the project provides before writing anything.

- Every claim the copy will make about the product must trace to a fact-base row with a source. This includes mechanism, architecture, integrations, performance, team credentials, and commercial terms — not just headline features.
- Anything the copy needs that no document answers goes in **Open questions for the owner**. It blocks that copy, or ships as an explicit `[Open decision for the owner]` flag in the deliverable's annotations. Never resolve an unknown by writing something plausible.
- When the owner's own directives conflict (stated audience vs. requested tone, demanded proof vs. actual stage), write to the documented facts and flag the conflict as an open decision — never silently pick a side, and never let the louder directive override a documented fact.
- Record the **stage honesty** section faithfully: customer count, certifications actually held, claims that are forbidden at this stage. If the company has zero customers, the copy will say so — see the stage-honesty playbook in `references/copy-craft.md`.

### 2. Research

Three parallel tracks (dispatch subagents if available; otherwise run sequentially). Full protocol: `references/evidence-standards.md`.

- **Market evidence.** Find external statistics that support the problem narrative. HARD RULE: a claim may only be used if you fetched its source URL during this engagement and confirmed the claim appears there, as worded. Prefer primary publishers; date-stamp everything; check whether the publisher has superseded the number; record conflicts instead of picking the favorable reading.
- **Competitor mapping.** Fetch the competitor pages the copy must differentiate against. Record their positioning, claims, pricing, CTAs, and recurring phrases *verbatim* — both to position against and so the similarity screen in step 4 can prove your copy doesn't echo them. Comparative claims about competitors carry legal exposure (Lanham Act — see `references/evidence-standards.md`); quote exactly and date-stamp.
- **Buyer language.** Sample the buyer's own vocabulary from public sources (job postings, community podcasts/blogs, public forums). Never fabricate access to private communities; state limitations plainly.

**No-network fallback:** if you cannot fetch, you cannot verify. Mark every external claim `[UNVERIFIED — do not publish until fetched]`, state at the top of the deliverable that source verification has not run, and do not mark the final checklist item for source verification.

### 3. Write

Draft into `templates/deliverable-template.md`. Craft rules — voice, banned lexicon, hero specs, section architecture, proof strategy by company stage, metadata truth — are in `references/copy-craft.md`. The non-negotiables:

- Every factual sentence carries its register: verified fact (with link), internal product claim (with document path), projection/design target (labeled), strategic recommendation, or copywriting judgment. Annotations after each section list them.
- Superlatives only where the cited source itself uses them. Paraphrases preserve the source's unit, population, and date.
- Quotes are verbatim. Attributing an author's summary to survey respondents is quote drift, and quote drift is fabrication.
- Projections, design targets, and roadmap intentions are labeled as such at every occurrence, not just the first.
- What you deliberately *excluded* (stats that failed verification, superseded numbers) goes in the annotations. The exclusion list is part of the standard.

### 4. Verify

Two layers, both required:

- **Deterministic.** Run: `python3 scripts/check_copy.py DELIVERABLE.md` (banned lexicon + embedded word/char limits; exits non-zero on failure). Then run `python3 scripts/check_copy.py DELIVERABLE.md --urls` to produce the citation worksheet for the fact-check pass. Add project-specific banned terms with `--lexicon FILE`. *No-execution fallback:* if you cannot run scripts on this surface, apply the banned lexicon and the template's `check:` budgets manually, and record in the checklist that the deterministic pass was manual, not scripted.
- **Adversarial.** Independent review passes per `references/verification.md`: (a) web fact-check that re-fetches every cited URL and tests the copy's *exact phrasing* against it, (b) internal-fidelity check against the fact base, (c) constraints/compliance check, (d) skeptical-buyer persona read, (e) competitor-similarity screen. Fix all blockers; re-run the deterministic checks after edits.

### 5. Ship

Mark the deliverable's self-review checklist honestly — a checklist item a 
````

## File: README.md
upstream: https://github.com/arome3/evidence-based-copywriting/blob/main/README.md

````text
# evidence-based-copywriting

An [Agent Skill](https://agentskills.io/specification) that produces marketing copy where **every factual claim is traced to a fetched source or the project's own documents, labeled, and adversarially verified before it ships** — landing pages, product pages, launch emails, one-pagers, and search/social metadata.

Built for teams whose copy has to survive skeptical technical buyers, legal and compliance review, and diligence: the discipline it enforces is the same standard US regulators already apply to advertisers (FTC prior-substantiation doctrine, 16 CFR Parts 255/465), packaged as a working pipeline instead of a policy document.

## Why this exists

Testing capable AI writers on realistic briefs shows they no longer fail by inventing customer logos — they fail two subtler ways:

1. **Citation without verification** — real-sounding statistics with plausible URLs, written from memory, never fetched, sometimes shipped with a "verify before launch" note.
2. **Capability and terms fabrication** — invented product mechanisms, architecture details, and commercial terms ("rate locked for life") that no document establishes, because those *feel* like copywriting latitude rather than claims.

This skill exists to stop both, and to make the result auditable: the output is copy **plus** its fact base, per-section source annotations, flagged open decisions, and a falsifiable self-review checklist.

## The pipeline

```mermaid
flowchart LR
    G[1 · Ground<br/>fact base from<br/>project documents] --> R[2 · Research<br/>fetch-verified evidence,<br/>competitors, buyer language]
    R --> W[3 · Write<br/>labeled claims,<br/>annotated sections]
    W --> V[4 · Verify<br/>5-lens adversarial panel<br/>+ deterministic checks]
    V --> S[5 · Ship<br/>honest checklist,<br/>open decisions flagged]
    V -->|blockers| W
```

## What's inside

All paths below live under `skills/evidence-based-copywriting/` (the repo is packaged as both a Claude Code plugin and a Codex plugin, each self-hosting its own marketplace):

| Path | What it is |
|---|---|
| `SKILL.md` | The pipeline, Iron Laws, rationalization table, red flags |
| `references/evidence-standards.md` | Verification protocol, source hierarchy, the US legal floor (with primary citations), and an evidence-trap catalog from live adversarial reviews |
| `references/copy-craft.md` | Voice contract, research-grounded banned lexicon, hero specs and the five-second test, section architecture, stage-honesty proof playbook, metadata facts vs. folklore |
| `references/verification.md` | The five-reviewer adversarial panel, severity rubric, fix protocol |
| `references/enterprise-integration.md` | How the standard slots into claims registries, MLR/FINRA-style review gates, and brand-voice governance |
| `templates/fact-base-template.md` | Fill first — every product claim must trace to it |
| `templates/deliverable-template.md` | Write into — annotations, machine-checkable limits, checklist |
| `scripts/check_copy.py` | Deterministic checks: banned lexicon, embedded word/char limits, citation worksheet (stdlib Python, CI-friendly) |

## Install

**Claude Code — recommended (two commands, updates managed for you):**

```
/plugin marketplace add arome3/evidence-based-copywriting
/plugin install evidence-based-copywriting@evidence-based-copywriting
```

The skill then appears as `evidence-based-copywriting:evidence-based-copywriting` and triggers automatically on high-stakes copy work.

**Claude Code — manual (personal or per-project):**

```bash
git clone https://github.com/arome3/evidence-based-copywriting.git /tmp/ebc &&
cp -R /tmp/ebc/skills/evidence-based-copywriting ~/.claude/skills/
```

For one project, copy into `.claude/skills/` inside the repo and commit it.

**OpenAI Codex — plugin (recommended):**

```
codex plugin marketplace add arome3/evidence-based-copywriting
```

Then install `evidence-based-copywriting` from the plugin list. Quick single-skill alternative, inside Codex:

```
$skill-installer install https://github.com/arome3/evidence-based-copywriting/tree/main/skills/evidence-based-copywriting
```

**Codex / Copilot CLI / Gemini CLI — manual:** copy `skills/evidence-based-copywriting/` into `~/.agents/skills/` (the cross-runtime user skills directory; use `.agents/skills/` inside a repo for project scope). Invoke with `$evidence-based-copywriting` or let it trigger implicitly.

**Claude.ai** (Pro/Max/Team/Enterprise, code execution enabled): download `evidence-based-copywriting-skill.zip` from the [latest release](https://github.com/arome3/evidence-based-copywriting/releases/latest) and upload via Settings → Features → Skills.

**Claude API**: upload the same release zip via the Skills API (`/v1/skills`, beta header `skills-2025-10-02`) with the code-execution tool enabled. Note the API sandbox has no network access, so the skill runs in its documented no-network fallback (claims are marked unverified rather than silently trusted).

Skills don't sync across surfaces — install where you work.

## Use

Ask for what you need in plain language — the skill triggers on high-stakes copy work:

> Write the landing page for [product] using our strategy docs in ./docs — follow the evidence-based-copywriting standard.

> Audit ./site/index.html against the evidence-based-copywriting skill and report every unsupported claim.

Standalone checks without an agent:

```bash
python3 skills/evidence-based-copywriting/scripts/check_copy.py your-copy.md          # lexicon + limits
python3 skills/evidence-based-copywriting/scripts/check_copy.py your-copy.md --urls   # citation worksheet
```

## What it is not

- **Not a brand voice guide.** It is a claims layer; it defers tone and terminology to your style guide and layers evidence discipline underneath.
- **Not legal advice.** It raises copy to the general FTC floor and produces reviewer-ready artifacts; regulated industries still route output through counsel and compliance.
- **Not a growth-hacking playbook.** It will refuse the tactics that work until the first skeptical reader checks one claim.

## License

MIT — see [LICENSE](LICENSE).
````
