# Copywriting Human Guide

## What This Is For
Writes and edits short product and marketing copy, including landing pages, CTAs, onboarding strings, product descriptions, email subjects, UI state copy, brand voice charts, and AI-ism. It gives the agent a clearer input/output frame for content production: what context to ask for, what decisions to make, and what usable artifact to return.

Use this as a human-readable version of the Copywriting agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions.

## When To Use This
- Use this when you need a repeatable process for copywriting.
- Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt.
- Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact.

## When Not To Use This
- Do not use this when you only need a quick factual answer.
- Do not use this when the work depends on private data you cannot share with the assistant.
- Do not use this as a replacement for legal, compliance, financial, or medical review.

## What You Need Before Starting
- The goal or business outcome you want.
- The audience, customer segment, or market context.
- Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance.
- Constraints such as tone, length, channel, deadline, region, or approval requirements.
- A clear definition of what a good final answer should look like.

## Step-By-Step Workflow
1. State the job clearly: "Use the Copywriting guide to help me with..."
2. Add context: audience, goal, offer, channel, source material, and constraints.
3. Ask the assistant to identify missing inputs before producing the final output.
4. Have the assistant follow the skill-specific guidance below.
5. Review the result against the final checklist and ask for revisions where needed.

## Skill-Specific Guidance
- Copy exists or user pasted copy to fix: **Mode B (Edit)**.
- Nothing written yet, or user wants something new: **Mode A (Write)**.
- Genuinely ambiguous ("improve this", no copy in scope): ask one question, then commit.
- **Page purpose.** The one action this page drives (sign up, book a demo, download).
- **Audience.** The specific reader: job title, pain, what they've already tried.
- **Product.** What it does; the concrete user outcome.
- **Traffic source.** Where the reader comes from (cold ad, warm email, organic search, referral).
- **A voice file in the repo:** `VOICE.md`, `BRAND.md`, `docs/voice.md`, or a tone-of-voice doc. This is the authoritative source when it exists.
- **Existing copy:** copy files, README headers, or shipped marketing pages.
- **Inference:** B2B SaaS direct and confident, consumer apps warmer, developer tools terse and honest. Ask for brand guidelines alongside the draft, not instead of it.
- **Marketing copy:** load `references/frameworks.md`, plus `references/page-types.md` when the target is a homepage, landing, pricing, feature, or about page.
- Apply the chosen framework visibly

## Decision Points And Nuance
The original skill emphasizes: Reference files, Mode A: Writing new copy, Step 1: Gather context, Step 2: State the brief, then write, Step 3: Discover brand voice, Step 4: Choose framework and load references, Step 5: Write 2-3 alternatives, Step 6: Recommend and explain, Step 7: Verify every line before handing back, Mode B: Editing existing copy.

Use these questions to steer the work:
- What is the intended audience or buyer?
- What source material must be preserved?
- What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion?
- What examples represent the desired quality bar?
- What should the assistant avoid?

## Common Mistakes
- Two modes, auto-detected (do not ask):
- Settle all four before writing, from the user or from the files. Where the files do not settle one, infer it and name the inference in Step 2; the failure mode is an invented audience or goal presented as fact.
- Find voice signals before inventing one; never default to generic corporate warmth. Work down this order and stop at the first hit:
- | Frustrated (error, failure, block) | Empathetic, solution-first, never blaming | "Payment failed. Your card was declined. Try a different card." |
- | High-trust audience, low awareness | Show Don't Tell |
- **Rebuild:** The copy is generic, contradictory, or has no discernible perspective. Run the full workflow with latitude to reconstruct it from the brief, but never invent proof.
- When replacing AI-isms, rewrite the sentence; don't swap the flagged word for a synonym.
- The never-write set. Applies in both modes, so it lives here rather than behind a reference load:

## Copy-And-Paste Prompt
```text
Use the Copywriting human guide.

My goal:
[Describe the business outcome]

Audience:
[Describe who this is for]

Context and source material:
[Paste notes, examples, links, or existing copy]

Constraints:
[Tone, length, channel, timeline, must-include items, must-avoid items]

Before producing the final output, ask me for any missing information that would materially improve the result.
```

## Final Checklist
- [ ] The output matches the original goal.
- [ ] The audience and context are reflected in the answer.
- [ ] Important constraints and source material were preserved.
- [ ] The assistant made the relevant decisions explicit.
- [ ] The final artifact is ready to use, review, or hand to the next person.

## Source
This guide was generated from the mblode/agent-skills skill entry for `copywriting`.

## Source Skill Notes
These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic.

# Copywriting

- **IS:** short conversion copy (landing pages, hero, subheads, CTAs, product descriptions, onboarding strings, email subjects); product-state strings (destructive CTAs, error, success, empty, loading, permission copy); stripping AI writing tells from any copy.
- **IS NOT:** long-form articles, posts, or anything written as a person rather than a brand (use the external `ghostwriter` skill; `blog` for long-form), slide or deck copy (use `presentation-creator`), API/product/reference docs (use `docs-writing`), in-session assistant talk (use `eli5`), or deciding which action exists, its scope, consequence, reversibility, or reachable states (use `product-design`; this skill writes final wording once those are decided).

Two modes, auto-detected (do not ask):

- Copy exists or user pasted copy to fix: **Mode B (Edit)**.
- Nothing written yet, or user wants something new: **Mode A (Write)**.
- Genuinely ambiguous ("improve this", no copy in scope): ask one question, then commit.

## Reference files

| File | Read when |
|------|-----------|
| `references/frameworks.md` | Pick a framework (Write Step 4); audit against the nine frameworks (Edit Step 3) |
| `references/page-types.md` | Copy norms for a known page type (Write Step 4) |
| `references/word-lists.md` | Flag Tier 1/2/3 AI vocabulary (Edit Step 4) |
| `references/ai-patterns.md` | Flag structural, sentence-level, and drafting AI tells; P0/P1/P2 triage (Edit Step 4) |
| `references/sweeps.md` | Run the seven line-level sweeps, then the hyphenation pass (Edit Step 5) |
| `references/ui-states.md` | The copy is a product state or action label, not marketing (Write Step 4; Edit Step 6 before using `[STATE-COPY]`) |
| `references/voice-chart.md` | No usable voice file exists and the product needs one (Write Step 3; Edit Step 1) |

---

## Mode A: Writing new copy

```
Writing progress:
- [ ] Step 1: Gather context
- [ ] Step 2: State the brief, then write
- [ ] Step 3: Discover brand voice
- [ ] Step 4: Choose framework and load references
- [ ] Step 5: Write 2-3 alternatives
- [ ] Step 6: Recommend and explain
- [ ] Step 7: Verify every line before handing back
```

### Step 1: Gather context

Settle all four before writing, from the user or from the files. Where the files do not settle one, infer it and name the inference in Step 2; the failure mode is an invented audience or goal presented as fact.

1. **Page purpose.** The one action this page drives (sign up, book a demo, download).
2. **Audience.** The specific reader: job title, pain, what they've already tried.
3. **Product.** What it does; the concrete user outcome.
4. **Traffic source.** Where the reader comes from (cold ad, warm email, organic search, referral).

Traffic source sets temperature: cold needs more Why; warm can lead with How or What.

### Step 2: State the brief, then write

State the brief and keep going. Mark every field you inferred rather than were told, so the user can correct it against real copy instead of against a question:

```
Brief:
- Page: [page type]
- Goal: [single action]
- Reader: [specific audience]
- Core outcome: [what changes for the reader]
- Tone: [inferred from brand voice or user-stated]
- Traffic temperature: [cold / warm / hot]

Inferred (correct me): [fields you guessed]
```

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.

### Step 3: Discover brand voice

Find voice signals before inventing one; never default to generic corporate warmth. Work down this order and stop at the first hit:

1. **A voice file in the repo:** `VOICE.md`, `BRAND.md`, `docs/voice.md`, or a tone-of-voice doc. This is the authoritative source when it exists.
2. **The user's own voice, on request only.** When the user asks for their voice ("in my voice", "sound like me") and the brand is theirs, read `$GHOSTWRITER_HOME/soul.md`, falling back to `~/.config/ghostwriter/soul.md`. Never apply a personal voice to a client's or employer's brand, and never quote the file back.
3. **Existing copy:** copy files, README headers, or shipped marketing pages.
4. **Inference:** B2B SaaS direct and confident, consumer apps warmer, developer tools terse and honest. Ask for brand guidelines alongside the draft, not instead of it.

**A discovered voice outranks the word lists.** If the voice file or the shipped copy uses a listed word as a signature, keep it; the lists catch generic AI vocabulary, not a deliberate house style. Locale and spelling convention come from the voice too.

Note in the brief which source you used, and mark the voice as inferred when it came from step 4. When no voice file exists and the product will need one, load `references/voice-chart.md` and offer to write `VOICE.md` alongside the copy.