AGENTS.md
Oddlynew Copy and Messaging Principles
Read this first. This is a skill organization: a small, maintained body of knowledge that an agent reads before writing or reviewing website copy, product and interface text, emails, sales material, or text whose first reader is an AI agent. It sits beside the UX and UI Principles for Websites organization, which owns layout, interaction and visual design; this organization owns the words and the thinking that produces them. It grows by research passes and by corrections from real copy work, never by pasting. Maintained by Oddlynew GmbH.
Purpose and audience
State what the recognised authorities on copywriting, persuasion psychology, positioning, content design and web reading research agree on, where they disagree, and what the evidence says, so that an agent can write copy that is right for its audience without re-researching. Audience: any agent or person writing website, product, sales or agent-facing copy, and the product organizations that apply it. This organization holds no customer names, customer quotes, internal numbers or product-specific wording, so it can be shared, followed or listed on its own.
Start here
Principles: the canonical distilled rules, with a one-page "Rules at a glance". Read it before any copy task.
From product strategy to page copy: the eight-step method from customer evidence to a tested page, the awareness-to-page table, the low-traffic testing playbook and the reusable strategy and messaging templates (positioning statement, PR/FAQ, strategic narrative, switch interview, message house, audience brief, language bank, claims register, teardown).
Copy review playbook: the five-pass review, the microcopy checklist, AI-assisted drafting rules, the voice and tone template, and how to learn from corrections.
Find the right note by task
Two hops for each task: the Principles section that holds the rules, then the one block that turns them into a checklist, method or template. Read the product's own voice, glossary and claims documents first (How a product organization uses this).
Routes
Sources: one note per body of work, recording what was read, URLs and dates, evidence class and limits. Where a note's rules differ from Principles, Principles holds; where its method or template differs from From product strategy to page copy or the Copy review playbook, those hold. The notes:
Copywriting canon: Hopkins, Ogilvy, Schwartz, Caples, Schwab, Sugarman, Halbert, Wiebe, Wynter, Harry Dry, Shapiro, Handley, Graham, 37signals, exemplars; frameworks and headline formulas, where the schools disagree, and working rules for website copy.
Psychology of persuasion and its replication record: what holds up, what failed, and the EU and German legal floor.
Positioning, customer research and product narrative: Dunford, Moore, JTBD schools, Mom Test, Torres, voice-of-customer research, Working Backwards, Raskin, Cagan, Rumelt, Shape Up, Sierra, message house and messaging hierarchy, naming, ubiquitous language.
Content design, UX writing, voice and tone: Richards, Podmajersky, Yifrah, public style guides, microcopy patterns, plain language and readability formulas, German specifics, localization, AI-era writing.
How people read the web and what copy changes measurably do: NN/g reading research, plain language evidence, conversion and experimentation research, testing, SEO and AI answer engines, WCAG.
Mentioning AI, disclosure evidence and the EU legal floor: algorithm aversion and disclosure research, AI Act article 50, the Commission guidelines and code of practice, GDPR and UWG, trust and privacy copy.
Writing for an agent reader, specs, citation evidence and the fit check: llms.txt, vendor and MCP guidance, answer-engine citation evidence, the fit-check honesty protocol, tool-description checklist, setup and consent copy.
Activation, plan and limit copy for agent-operated products: first-run and empty-state copy, a use-case page checklist, a first-run study design, developer copy, capacity and limit messages, plan cards, German price display.
Conflicts and open questions: genuine source tensions and uncovered evidence. Never silently erase a disagreement.
Myths: unsupported, failed and misapplied claims with verdicts. Check before citing a memorable number.
Research log: append-only pass history and the queued passes with ready-to-run briefs.
Loop: Recheck the legal blocks: once a month, recheck the EU and German legal blocks in four Source notes (persuasion; mentioning AI; activation, plan and limit copy; content design) against their official sources and update their "Last checked" lines.
How a product organization uses this
This organization gives method and evidence; a product's own words live in the product's organization. There each product keeps its voice and tone document (template in the playbook), its glossary, its message house, its claims register (template), its language banks, its copy audits, its persona-panel rounds and its teardowns. The product organization's AGENTS.md or voice document routes copy work here for method; this organization never points to a specific product.
Where a product owner and this organization disagree, the product owner wins for that product's words. A lesson from product work that generalizes returns here as a rewritten principle and a Research log entry, stated without the product's data.
How to work here
Read Principles, then your product organization's voice, glossary and claims documents, then the process or playbook section your task needs (Find the right note by task). Do not read every source note by default.
Every rule carries its evidence next to it: a source note block here, or a URL with the date read. A claim without evidence is marked as such.
Update the owner that holds the changed claim or method. Rewrite a principle as if the new understanding had always been known; the Research log keeps the history.
Research passes: one coordinating session owns each pass, and its log entry names every agent and model. Read Principles and the Research log first, pick sources not yet covered or claims not yet verified, verify at least one earlier claim against its primary source, and record the pass even when nothing changed. Run passes with agents from different providers; disagreement goes to Conflicts.
After real copy work, follow Learn from corrections in the playbook.
Work as a participant in a multi-agent system: a brief for another agent names the documents it must read here and where it writes its outcome.
Writing rules
English. No em or en dashes. High signal per sentence; the point first.
Short quotations only; distil in your own words and cite.
Neutral placeholders in templates and examples; no customer data.
Legal notes cover EU and German law only and are orientation, not legal advice; for any other market, check local law. A claim's legal check is recorded in the product's claims register.
Ownership and status
Maintained by Oddlynew through research passes recorded in the Research log. This is a public organization: anyone can read it, signed in or not.