claude-code-arcane 1.0.0

package/skills/copy-editing/references/seven-sweeps-framework.md

@@ -0,0 +1,228 @@
+# Seven Sweeps Framework — Detailed Guide
+
+Edit copy through seven sequential passes, each focusing on one dimension. After each sweep, loop back to check previous sweeps aren't compromised.
+
+## Sweep 1: Clarity
+
+**Focus:** Can the reader understand what you're saying?
+
+**What to check:**
+- Confusing sentence structures
+- Unclear pronoun references
+- Jargon or insider language
+- Ambiguous statements
+- Missing context
+
+**Common clarity killers:**
+- Sentences trying to say too much
+- Abstract language instead of concrete
+- Assuming reader knowledge they don't have
+- Burying the point in qualifications
+
+**Process:**
+1. Read through quickly, highlighting unclear parts
+2. Don't correct yet — just note problem areas
+3. After marking issues, recommend specific edits
+4. Verify edits maintain the original intent
+
+**After this sweep:** Confirm the "Rule of One" (one main idea per section) and "You Rule" (copy speaks to the reader) are intact.
+
+---
+
+## Sweep 2: Voice and Tone
+
+**Focus:** Is the copy consistent in how it sounds?
+
+**What to check:**
+- Shifts between formal and casual
+- Inconsistent brand personality
+- Mood changes that feel jarring
+- Word choices that don't match the brand
+
+**Common voice issues:**
+- Starting casual, becoming corporate
+- Mixing "we" and "the company" references
+- Humor in some places, serious in others (unintentionally)
+- Technical language appearing randomly
+
+**Process:**
+1. Read aloud to hear inconsistencies
+2. Mark where tone shifts unexpectedly
+3. Recommend edits that smooth transitions
+4. Ensure personality remains throughout
+
+**After this sweep:** Return to Clarity Sweep to ensure voice edits didn't introduce confusion.
+
+---
+
+## Sweep 3: So What
+
+**Focus:** Does every claim answer "why should I care?"
+
+**What to check:**
+- Features without benefits
+- Claims without consequences
+- Statements that don't connect to reader's life
+- Missing "which means..." bridges
+
+**The So What test:**
+For every statement, ask "Okay, so what?" If the copy doesn't answer that question with a deeper benefit, it needs work.
+
+- Bad: "Our platform uses AI-powered analytics"
+- Good: "Our AI-powered analytics surface insights you'd miss manually — so you can make better decisions in half the time"
+
+**Common So What failures:**
+- Feature lists without benefit connections
+- Impressive-sounding claims that don't land
+- Technical capabilities without outcomes
+- Company achievements that don't help the reader
+
+**Process:**
+1. Read each claim and literally ask "so what?"
+2. Highlight claims missing the answer
+3. Add the benefit bridge or deeper meaning
+4. Ensure benefits connect to real reader desires
+
+**After this sweep:** Return to Voice and Tone, then Clarity.
+
+---
+
+## Sweep 4: Prove It
+
+**Focus:** Is every claim supported with evidence?
+
+**What to check:**
+- Unsubstantiated claims
+- Missing social proof
+- Assertions without backup
+- "Best" or "leading" without evidence
+
+**Types of proof to look for:**
+- Testimonials with names and specifics
+- Case study references
+- Statistics and data
+- Third-party validation
+- Guarantees and risk reversals
+- Customer logos
+- Review scores
+
+**Common proof gaps:**
+- "Trusted by thousands" (which thousands?)
+- "Industry-leading" (according to whom?)
+- "Customers love us" (show them saying it)
+- Results claims without specifics
+
+**Process:**
+1. Identify every claim that needs proof
+2. Check if proof exists nearby
+3. Flag unsupported assertions
+4. Recommend adding proof or softening claims
+
+**After this sweep:** Return to So What, Voice and Tone, then Clarity.
+
+---
+
+## Sweep 5: Specificity
+
+**Focus:** Is the copy concrete enough to be compelling?
+
+**What to check:**
+- Vague language ("improve," "enhance," "optimize")
+- Generic statements that could apply to anyone
+- Round numbers that feel made up
+- Missing details that would make it real
+
+**Specificity upgrades:**
+
+| Vague | Specific |
+|-------|----------|
+| Save time | Save 4 hours every week |
+| Many customers | 2,847 teams |
+| Fast results | Results in 14 days |
+| Improve your workflow | Cut your reporting time in half |
+| Great support | Response within 2 hours |
+
+**Common specificity issues:**
+- Adjectives doing the work nouns should do
+- Benefits without quantification
+- Outcomes without timeframes
+- Claims without concrete examples
+
+**Process:**
+1. Highlight vague words and phrases
+2. Ask "Can this be more specific?"
+3. Add numbers, timeframes, or examples
+4. Remove content that can't be made specific (it's probably filler)
+
+**After this sweep:** Return to Prove It, So What, Voice and Tone, then Clarity.
+
+---
+
+## Sweep 6: Heightened Emotion
+
+**Focus:** Does the copy make the reader feel something?
+
+**What to check:**
+- Flat, informational language
+- Missing emotional triggers
+- Pain points mentioned but not felt
+- Aspirations stated but not evoked
+
+**Emotional dimensions to consider:**
+- Pain of the current state
+- Frustration with alternatives
+- Fear of missing out
+- Desire for transformation
+- Pride in making smart choices
+- Relief from solving the problem
+
+**Techniques for heightening emotion:**
+- Paint the "before" state vividly
+- Use sensory language
+- Tell micro-stories
+- Reference shared experiences
+- Ask questions that prompt reflection
+
+**Process:**
+1. Read for emotional impact — does it move you?
+2. Identify flat sections that should resonate
+3. Add emotional texture while staying authentic
+4. Ensure emotion serves the message (not manipulation)
+
+**After this sweep:** Return to Specificity, Prove It, So What, Voice and Tone, then Clarity.
+
+---
+
+## Sweep 7: Zero Risk
+
+**Focus:** Have we removed every barrier to action?
+
+**What to check:**
+- Friction near CTAs
+- Unanswered objections
+- Missing trust signals
+- Unclear next steps
+- Hidden costs or surprises
+
+**Risk reducers to look for:**
+- Money-back guarantees
+- Free trials
+- "No credit card required"
+- "Cancel anytime"
+- Social proof near CTA
+- Clear expectations of what happens next
+- Privacy assurances
+
+**Common risk issues:**
+- CTA asks for commitment without earning trust
+- Objections raised but not addressed
+- Fine print that creates doubt
+- Vague "Contact us" instead of clear next step
+
+**Process:**
+1. Focus on sections near CTAs
+2. List every reason someone might hesitate
+3. Check if the copy addresses each concern
+4. Add risk reversals or trust signals as needed
+
+**After this sweep:** Return through all previous sweeps one final time.

package/skills/copy-editing/scripts/readability_scorer.py

@@ -0,0 +1,285 @@
+#!/usr/bin/env python3
+"""
+readability_scorer.py — Readability metrics for marketing copy
+Usage:
+  python3 readability_scorer.py --file copy.txt
+  echo "Your text here" | python3 readability_scorer.py
+  python3 readability_scorer.py          # demo mode
+  python3 readability_scorer.py --json
+"""
+
+import argparse
+import json
+import math
+import re
+import sys
+
+
+# ---------------------------------------------------------------------------
+# Word lists
+# ---------------------------------------------------------------------------
+
+FILLER_WORDS = [
+    "very", "really", "just", "actually", "basically", "literally",
+    "honestly", "totally", "absolutely", "definitely", "certainly",
+    "obviously", "clearly", "quite", "rather", "somewhat", "fairly",
+    "pretty", "simply", "truly", "genuinely", "essentially",
+]
+
+# Simple passive voice detection: "was/were/is/are/been/being + past participle"
+PASSIVE_PATTERN = re.compile(
+    r"\b(was|were|is|are|been|being|be|am)\s+(\w+ed|known|written|built|made|done|seen|given|taken|brought|thought|found|put|set|cut|read|let|hit|hurt|cost|led|felt|kept|left|meant|sent|spent|stood|told|wore|won|beat|lost|broke|chose|drove|flew|froze|grew|hid|rang|rode|rose|ran|sank|sang|spoke|swore|swam|threw|woke|wrote)\b",
+    re.IGNORECASE,
+)
+
+ADVERB_PATTERN = re.compile(r"\b\w+ly\b", re.IGNORECASE)
+
+# Syllable estimation: count vowel groups
+def count_syllables(word: str) -> int:
+    word = word.lower().strip(".,!?;:\"'")
+    if not word:
+        return 0
+    # Silent e
+    if word.endswith("e") and len(word) > 2:
+        word = word[:-1]
+    count = len(re.findall(r"[aeiou]+", word))
+    return max(1, count)
+
+
+def split_sentences(text: str) -> list:
+    # Split on sentence-ending punctuation
+    parts = re.split(r"(?<=[.!?])\s+", text.strip())
+    return [p.strip() for p in parts if p.strip()]
+
+
+def split_words(text: str) -> list:
+    return re.findall(r"\b[a-zA-Z]+\b", text)
+
+
+# ---------------------------------------------------------------------------
+# Metrics
+# ---------------------------------------------------------------------------
+
+def flesch_reading_ease(avg_sentence_len: float, avg_syllables: float) -> float:
+    """Flesch Reading Ease formula."""
+    score = 206.835 - (1.015 * avg_sentence_len) - (84.6 * avg_syllables)
+    return round(max(0.0, min(100.0, score)), 1)
+
+
+def flesch_kincaid_grade(avg_sentence_len: float, avg_syllables: float) -> float:
+    """Flesch-Kincaid Grade Level formula."""
+    grade = (0.39 * avg_sentence_len) + (11.8 * avg_syllables) - 15.59
+    return round(max(0.0, grade), 1)
+
+
+def ease_label(score: float) -> str:
+    if score >= 90: return "Very Easy (5th grade)"
+    if score >= 80: return "Easy (6th grade)"
+    if score >= 70: return "Fairly Easy (7th grade)"
+    if score >= 60: return "Standard (8-9th grade)"
+    if score >= 50: return "Fairly Difficult (10-12th grade)"
+    if score >= 30: return "Difficult (College)"
+    return "Very Confusing (Professional)"
+
+
+def analyze_text(text: str) -> dict:
+    sentences = split_sentences(text)
+    words = split_words(text)
+
+    if not words:
+        return {"error": "No readable text found."}
+
+    num_sentences = max(1, len(sentences))
+    num_words = len(words)
+
+    # Syllables
+    syllable_counts = [count_syllables(w) for w in words]
+    total_syllables = sum(syllable_counts)
+
+    avg_sentence_len = num_words / num_sentences
+    avg_word_len = sum(len(w) for w in words) / num_words
+    avg_syllables_per_word = total_syllables / num_words
+
+    fre = flesch_reading_ease(avg_sentence_len, avg_syllables_per_word)
+    fk_grade = flesch_kincaid_grade(avg_sentence_len, avg_syllables_per_word)
+
+    # Passive voice
+    passive_matches = PASSIVE_PATTERN.findall(text)
+    passive_count = len(passive_matches)
+    passive_pct = round(passive_count / num_sentences * 100, 1)
+
+    # Adverbs
+    adverb_matches = ADVERB_PATTERN.findall(text)
+    # Filter obvious non-adverbs
+    non_adverb = {"family", "early", "only", "likely", "nearly", "really",
+                  "daily", "weekly", "monthly", "yearly", "friendly", "lovely",
+                  "lonely", "lively", "elderly", "costly"}
+    adverbs = [a for a in adverb_matches if a.lower() not in non_adverb]
+    adverb_density = round(len(adverbs) / num_words * 100, 1)
+
+    # Filler words
+    text_lower = text.lower()
+    word_tokens_lower = [w.lower() for w in words]
+    filler_found = {fw: word_tokens_lower.count(fw) for fw in FILLER_WORDS if fw in word_tokens_lower}
+    filler_total = sum(filler_found.values())
+
+    # Scoring:
+    # FRE already 0-100 (higher = easier = better for marketing copy)
+    # Target for marketing: 60-80 range
+    fre_score = fre  # use as-is
+
+    return {
+        "stats": {
+            "word_count": num_words,
+            "sentence_count": num_sentences,
+            "avg_sentence_length": round(avg_sentence_len, 1),
+            "avg_word_length": round(avg_word_len, 1),
+            "avg_syllables_per_word": round(avg_syllables_per_word, 2),
+        },
+        "flesch_reading_ease": {
+            "score": fre,
+            "label": ease_label(fre),
+            "target": "60-80 for most marketing copy",
+        },
+        "flesch_kincaid_grade": {
+            "grade_level": fk_grade,
+            "note": f"Equivalent to grade {fk_grade} reading level",
+        },
+        "passive_voice": {
+            "count": passive_count,
+            "percentage": passive_pct,
+            "target": "<10%",
+            "pass": passive_pct < 10,
+        },
+        "adverb_density": {
+            "count": len(adverbs),
+            "percentage": adverb_density,
+            "examples": list(set(adverbs))[:8],
+            "target": "<5%",
+            "pass": adverb_density < 5,
+        },
+        "filler_words": {
+            "total_count": filler_total,
+            "breakdown": filler_found,
+            "target": "0-3 per 100 words",
+            "per_100_words": round(filler_total / num_words * 100, 1),
+        },
+        "overall_score": round(fre),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Demo text
+# ---------------------------------------------------------------------------
+
+DEMO_TEXT = """
+Marketing copy needs to be clear, direct, and persuasive. When you write for your audience, 
+you should always think about what they actually want to hear. Really good copy is basically 
+about solving problems. It is very important to avoid using overly complicated language that 
+might confuse the reader.
+
+The best headlines are written by experts who truly understand their customers. A strong 
+call-to-action is absolutely essential for any landing page. You need to make sure that 
+every single word is earning its place on the page.
+
+Studies show that shorter sentences improve comprehension. The average reader processes 
+information faster when sentences contain fewer than 20 words. This is genuinely proven 
+by research. Passive voice constructions are often used by writers who want to sound 
+authoritative, but they can actually make copy feel distant and unclear.
+
+Focus on benefits, not features. Tell the reader what they will gain. Use numbers when 
+you can — "save 3 hours per week" beats "save time" every single time. Specificity 
+builds trust. Vague promises are ignored.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Readability scorer for marketing copy — Flesch, passive voice, filler words."
+    )
+    parser.add_argument("--file", help="Path to text file")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    args = parser.parse_args()
+
+    if args.file:
+        with open(args.file, "r", encoding="utf-8", errors="replace") as f:
+            text = f.read()
+    elif not sys.stdin.isatty():
+        text = sys.stdin.read()
+        if not text.strip():
+            text = DEMO_TEXT
+            if not args.json:
+                print("No input provided — running in demo mode.\n")
+    else:
+        text = DEMO_TEXT
+        if not args.json:
+            print("No input provided — running in demo mode.\n")
+
+    result = analyze_text(text)
+
+    if "error" in result:
+        print(f"Error: {result['error']}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+        return
+
+    fre = result["flesch_reading_ease"]
+    fk = result["flesch_kincaid_grade"]
+    stats = result["stats"]
+    passive = result["passive_voice"]
+    adverbs = result["adverb_density"]
+    fillers = result["filler_words"]
+    score = result["overall_score"]
+
+    PASS = "✅"
+    FAIL = "❌"
+
+    print("=" * 62)
+    print(f"  READABILITY REPORT   Flesch Score: {fre['score']}/100")
+    print("=" * 62)
+    print(f"  {fre['label']}")
+    print(f"  Target: {fre['target']}")
+    print()
+    print(f"  📊 Stats")
+    print(f"     Words:              {stats['word_count']}")
+    print(f"     Sentences:          {stats['sentence_count']}")
+    print(f"     Avg sentence length:{stats['avg_sentence_length']} words")
+    print(f"     Avg word length:    {stats['avg_word_length']} chars")
+    print(f"     Syllables/word:     {stats['avg_syllables_per_word']}")
+    print()
+    print(f"  📐 Flesch-Kincaid Grade Level: {fk['grade_level']}")
+    print(f"     {fk['note']}")
+    print()
+
+    pv_icon = PASS if passive["pass"] else FAIL
+    print(f"  {pv_icon} Passive Voice: {passive['count']} instances ({passive['percentage']}%)")
+    print(f"     Target: {passive['target']}")
+
+    av_icon = PASS if adverbs["pass"] else FAIL
+    print(f"  {av_icon} Adverb Density: {adverbs['count']} adverbs ({adverbs['percentage']}%)")
+    if adverbs["examples"]:
+        print(f"     Examples: {', '.join(adverbs['examples'][:5])}")
+
+    filler_ok = fillers["per_100_words"] <= 3
+    fw_icon = PASS if filler_ok else FAIL
+    print(f"  {fw_icon} Filler Words: {fillers['total_count']} total ({fillers['per_100_words']} per 100 words)")
+    if fillers["breakdown"]:
+        top = sorted(fillers["breakdown"].items(), key=lambda x: -x[1])[:5]
+        print(f"     Top: {', '.join(f'{w}({c})' for w,c in top)}")
+
+    print()
+    print("=" * 62)
+    score_bar_len = round(score / 10)
+    bar = "█" * score_bar_len + "░" * (10 - score_bar_len)
+    print(f"  Readability Score:  [{bar}] {score}/100")
+    print("=" * 62)
+
+
+if __name__ == "__main__":
+    main()

package/skills/copywriting/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: copywriting
+description: "Write and improve marketing copy for homepages, landing pages, pricing, feature, and about pages. For email copy see email-sequence."
+argument-hint: ""
+category: "marketing-content"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+---
+
+# Copywriting
+
+You are an expert conversion copywriter. Your goal is to write marketing copy that is clear, compelling, and drives action.
+
+## Before Writing
+
+**Check for product marketing context first:**
+If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
+
+Gather this context (ask if not provided):
+
+### 1. Page Purpose
+- What type of page? (homepage, landing page, pricing, feature, about)
+- What is the ONE primary action you want visitors to take?
+
+### 2. Audience
+- Who is the ideal customer?
+- What problem are they trying to solve?
+- What objections or hesitations do they have?
+- What language do they use to describe their problem?
+
+### 3. Product/Offer
+- What are you selling or offering?
+- What makes it different from alternatives?
+- What's the key transformation or outcome?
+- Any proof points (numbers, testimonials, case studies)?
+
+### 4. Context
+- Where is traffic coming from? (ads, organic, email)
+- What do visitors already know before arriving?
+
+---
+
+## Copywriting Principles
+
+### Clarity Over Cleverness
+If you have to choose between clear and creative, choose clear.
+
+### Benefits Over Features
+Features: What it does. Benefits: What that means for the customer.
+
+### Specificity Over Vagueness
+- Vague: "Save time on your workflow"
+- Specific: "Cut your weekly reporting from 4 hours to 15 minutes"
+
+### Customer Language Over Company Language
+Use words your customers use. Mirror voice-of-customer from reviews, interviews, support tickets.
+
+### One Idea Per Section
+Each section should advance one argument. Build a logical flow down the page.
+
+---
+
+## Writing Style & Best Practices
+
+> See [references/writing-style-rules.md](references/writing-style-rules.md) for core style principles, quality checklist, directness examples, rhetorical techniques, and CTA copy guidelines.
+
+---
+
+## Page Structure Framework
+
+### Above the Fold
+
+**Headline**
+- Your single most important message
+- Communicate core value proposition
+- Specific > generic
+
+**Example formulas:**
+- "{Achieve outcome} without {pain point}"
+- "The {category} for {audience}"
+- "Never {unpleasant event} again"
+- "{Question highlighting main pain point}"
+
+**For comprehensive headline formulas**: See [references/copy-frameworks.md](references/copy-frameworks.md)
+
+**For natural transition phrases**: See [references/natural-transitions.md](references/natural-transitions.md)
+
+**Subheadline**
+- Expands on headline
+- Adds specificity
+- 1-2 sentences max
+
+**Primary CTA**
+- Action-oriented button text
+- Communicate what they get: "Start Free Trial" > "Sign Up"
+
+### Core Sections
+
+| Section | Purpose |
+|---------|---------|
+| Social Proof | Build credibility (logos, stats, testimonials) |
+| Problem/Pain | Show you understand their situation |
+| Solution/Benefits | Connect to outcomes (3-5 key benefits) |
+| How It Works | Reduce perceived complexity (3-4 steps) |
+| Objection Handling | FAQ, comparisons, guarantees |
+| Final CTA | Recap value, repeat CTA, risk reversal |
+
+**For detailed section types and page templates**: See [references/copy-frameworks.md](references/copy-frameworks.md)
+
+---
+
+## Page-Specific Guidance
+
+Apply the right framework per page type: Homepage (broad value prop, multiple audience paths), Landing Page (single message, single CTA, match headline to traffic source), Pricing Page (help choose the right plan, address anxiety), Feature Page (feature to benefit to outcome), About Page (story of why you exist + CTA).
+
+**For detailed page templates and formulas**: See [references/copy-frameworks.md](references/copy-frameworks.md)
+
+---
+
+## Output Format
+
+When writing copy, provide:
+
+### Page Copy
+Organized by section:
+- Headline, Subheadline, CTA
+- Section headers and body copy
+- Secondary CTAs
+
+### Annotations
+For key elements, explain:
+- Why you made this choice
+- What principle it applies
+
+### Alternatives
+For headlines and CTAs, provide 2-3 options:
+- Option A: [copy] — [rationale]
+- Option B: [copy] — [rationale]
+
+### Meta Content (if relevant)
+- Page title (for SEO)
+- Meta description
+
+---
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked when you notice them in context:
+
+- **Copy opens with "We" or the company name** → Flag it immediately; reframe to lead with the customer's outcome or problem.
+- **Value proposition is vague** (e.g., "the best platform for teams") → Push for specificity: who, what outcome, how long.
+- **Features are listed without benefits** → Add "which means..." bridges before delivering the draft.
+- **No social proof is provided** → Flag this as a conversion risk and ask for testimonials, numbers, or case study references.
+- **CTA uses weak verbs** (Submit, Learn More, Sign Up) → Propose action-outcome alternatives before finalising.
+
+---
+
+## Output Artifacts
+
+| When you ask for... | You get... |
+|---------------------|------------|
+| Homepage copy | Full page copy organized by section: headline, subheadline, CTA, social proof, benefits, how it works, objection handling, final CTA |
+| Landing page | Single-focus copy with headline, body, and one CTA — annotated with conversion rationale |
+| Headline options | 5 headline variants using different formulas (outcome, pain, question, bold claim, category) |
+| CTA copy | 3-5 CTA options with formula and rationale for each |
+| Page copy review | Section-by-section feedback on clarity, benefit framing, and CTA strength |
+
+---
+
+## Communication
+
+All output follows the structured communication standard:
+
+- **Bottom line first** — deliver the copy, then explain the choices
+- **What + Why + How** — every copy decision has a principle behind it
+- **Annotations are mandatory** — never ship copy without explaining the key choices
+- **Confidence tagging** — 🟢 strong recommendation / 🟡 test this / 🔴 needs proof to land
+
+Always provide alternatives for high-stakes elements (headline, CTA). Never deliver one option and call it done.
+
+---
+
+## Related Skills
+
+- **marketing-context**: USE as the foundation before writing — loads brand voice, ICP, and positioning context. NOT a substitute for this skill.
+- **copy-editing**: USE after your first draft is complete to systematically polish and improve. NOT for writing new copy from scratch.
+- **content-strategy**: USE when deciding what topics or pages to create before writing. NOT for the writing itself.
+- **social-content**: USE when adapting finished copy for social platforms. NOT for long-form page copy.
+- **marketing-ideas**: USE when brainstorming which marketing assets to build. NOT for writing the copy for those assets.
+- **content-humanizer**: USE when AI-drafted copy sounds robotic or templated. NOT for strategic decisions.
+- **ab-test-setup**: USE to design experiments testing copy variants. NOT for writing the copy itself.
+- **email-sequence**: USE for email copywriting specifically. NOT for page or landing page copy.