From b0a3a23699425ab8655cdef2605900d9a6ce7fad Mon Sep 17 00:00:00 2001 From: Corey Haines <34802794+coreyhaines31@users.noreply.github.com> Date: Wed, 4 Mar 2026 14:19:09 -0800 Subject: [PATCH 1/2] refactor: replace rigid imperatives with reasoning-based guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Audit all 32 SKILL.md files against Anthropic's skill-creator writing guidance ("why > MUST" pattern). Replaces ALWAYS/NEVER/MUST/IMPORTANT imperatives with explanations of WHY the guidance matters. 17 edits across 14 skills: - ad-creative: character limits reasoning, CTA headline reasoning - seo-audit: schema detection warning softened, reasoning added - programmatic-seo: subfolder vs subdomain reasoning - paid-ads: exclusion list reasoning - copywriting: honesty principle reasoning - cold-email: follow-up value reasoning - ai-seo: freshness signal reasoning - churn-prevention: post-cancel path reasoning - product-marketing-context: verbatim language reasoning - popup-cro: close button visibility reasoning - signup-flow-cro: label visibility reasoning - form-cro: label visibility reasoning - revops: fallback owner reasoning - ab-test-setup: DON'T → Avoid Co-Authored-By: Claude Opus 4.6 --- skills/ab-test-setup/SKILL.md | 2 +- skills/ad-creative/SKILL.md | 4 ++-- skills/ai-seo/SKILL.md | 2 +- skills/churn-prevention/SKILL.md | 2 +- skills/cold-email/SKILL.md | 2 +- skills/copywriting/SKILL.md | 2 +- skills/form-cro/SKILL.md | 2 +- skills/paid-ads/SKILL.md | 2 +- skills/popup-cro/SKILL.md | 2 +- skills/product-marketing-context/SKILL.md | 2 +- skills/programmatic-seo/SKILL.md | 2 +- skills/revops/SKILL.md | 2 +- skills/seo-audit/SKILL.md | 6 +++--- skills/signup-flow-cro/SKILL.md | 2 +- 14 files changed, 17 insertions(+), 17 deletions(-) diff --git a/skills/ab-test-setup/SKILL.md b/skills/ab-test-setup/SKILL.md index 2da0d1e..e8daf41 100644 --- a/skills/ab-test-setup/SKILL.md +++ b/skills/ab-test-setup/SKILL.md @@ -180,7 +180,7 @@ We'll know this is true when [metrics]. - Check segment quality - Document external factors -**DON'T:** +**Avoid:** - Peek at results and stop early - Make changes to variants - Add traffic from new sources diff --git a/skills/ad-creative/SKILL.md b/skills/ad-creative/SKILL.md index 7dd2709..ad1c39f 100644 --- a/skills/ad-creative/SKILL.md +++ b/skills/ad-creative/SKILL.md @@ -64,7 +64,7 @@ Pull performance data → Identify winning patterns → Generate new variations ## Platform Specs -**Always enforce these limits.** Never deliver creative that exceeds platform character limits. +Platforms reject or truncate creative that exceeds these limits, so verify every piece of copy fits before delivering. ### Google Ads (Responsive Search Ads) @@ -320,7 +320,7 @@ For large-scale creative production (Anthropic's growth team generates 100+ vari - **Writing headlines that only work together** — RSA headlines get combined randomly - **Ignoring character limits** — Platforms truncate without warning - **All variations sound the same** — Vary angles, not just word choice -- **No CTA headlines** — Always include action-oriented headlines +- **No CTA headlines** — RSAs need action-oriented headlines to drive clicks; include at least 2-3 - **Generic descriptions** — "Learn more about our solution" wastes the slot - **Iterating without data** — Gut feelings are less reliable than metrics - **Testing too many things at once** — Change one variable per test cycle diff --git a/skills/ai-seo/SKILL.md b/skills/ai-seo/SKILL.md index eb864f1..a3897e6 100644 --- a/skills/ai-seo/SKILL.md +++ b/skills/ai-seo/SKILL.md @@ -353,7 +353,7 @@ Monthly manual check: - **Ignoring AI search entirely** — ~45% of Google searches now show AI Overviews, and ChatGPT/Perplexity are growing fast - **Treating AI SEO as separate from SEO** — Good traditional SEO is the foundation; AI SEO adds structure and authority on top - **Writing for AI, not humans** — If content reads like it was written to game an algorithm, it won't get cited or convert -- **No freshness signals** — Undated content loses to dated content. Always show when content was last updated +- **No freshness signals** — Undated content loses to dated content because AI systems weight recency heavily. Show when content was last updated - **Gating all content** — AI can't access gated content. Keep your most authoritative content open - **Ignoring third-party presence** — You may get more AI citations from a Wikipedia mention than from your own blog - **No structured data** — Schema markup gives AI systems structured context about your content diff --git a/skills/churn-prevention/SKILL.md b/skills/churn-prevention/SKILL.md index ceae776..c04a7e8 100644 --- a/skills/churn-prevention/SKILL.md +++ b/skills/churn-prevention/SKILL.md @@ -375,7 +375,7 @@ Test one variable at a time: - **Guilt-trip copy** — "Are you sure you want to abandon us?" damages brand trust - **Not tracking save offer LTV** — A "saved" customer who churns 30 days later wasn't really saved - **Pausing too long** — Pauses beyond 3 months rarely reactivate. Set limits. -- **No post-cancel path** — Always make reactivation easy and trigger win-back emails +- **No post-cancel path** — Make reactivation easy and trigger win-back emails, because some churned users will want to come back --- diff --git a/skills/cold-email/SKILL.md b/skills/cold-email/SKILL.md index eddc6d3..b7547cc 100644 --- a/skills/cold-email/SKILL.md +++ b/skills/cold-email/SKILL.md @@ -100,7 +100,7 @@ See [subject-lines.md](references/subject-lines.md) for the full data. ## Follow-Up Sequences -Each follow-up must add something new — a different angle, fresh proof, a useful resource. Never "just checking in." +Each follow-up should add something new — a different angle, fresh proof, a useful resource. "Just checking in" gives the reader no reason to respond. - 3-5 total emails, increasing gaps between them - Each email should stand alone (they may not have read the previous ones) diff --git a/skills/copywriting/SKILL.md b/skills/copywriting/SKILL.md index f578d28..ed0ae5a 100644 --- a/skills/copywriting/SKILL.md +++ b/skills/copywriting/SKILL.md @@ -67,7 +67,7 @@ Each section should advance one argument. Build a logical flow down the page. 3. **Active over passive** — "We generate reports" not "Reports are generated" 4. **Confident over qualified** — Remove "almost," "very," "really" 5. **Show over tell** — Describe the outcome instead of using adverbs -6. **Honest over sensational** — Never fabricate statistics or testimonials +6. **Honest over sensational** — Fabricated statistics or testimonials erode trust and create legal liability ### Quick Quality Check diff --git a/skills/form-cro/SKILL.md b/skills/form-cro/SKILL.md index 81047f1..411d0b2 100644 --- a/skills/form-cro/SKILL.md +++ b/skills/form-cro/SKILL.md @@ -120,7 +120,7 @@ For each field, ask: 4. Logical grouping if many fields ### Labels and Placeholders -- Labels: Always visible (not just placeholder) +- Labels: Keep visible (not just placeholder) — placeholders disappear when typing, leaving users unsure what they're filling in - Placeholders: Examples, not labels - Help text: Only when genuinely helpful diff --git a/skills/paid-ads/SKILL.md b/skills/paid-ads/SKILL.md index 64620c4..7a68480 100644 --- a/skills/paid-ads/SKILL.md +++ b/skills/paid-ads/SKILL.md @@ -122,7 +122,7 @@ LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24 - **Lookalikes**: Base on best customers (by LTV), not all customers - **Retargeting**: Segment by funnel stage (visitors vs. cart abandoners) -- **Exclusions**: Always exclude existing customers and recent converters +- **Exclusions**: Exclude existing customers and recent converters — showing ads to people who already bought wastes spend **For detailed targeting strategies by platform**: See [references/audience-targeting.md](references/audience-targeting.md) diff --git a/skills/popup-cro/SKILL.md b/skills/popup-cro/SKILL.md index 0103c1f..bc60989 100644 --- a/skills/popup-cro/SKILL.md +++ b/skills/popup-cro/SKILL.md @@ -182,7 +182,7 @@ Before providing recommendations, understand: - Leave space to close (visible X, click outside) ### Close Button -- Always visible (top right is convention) +- Keep visible (top right is convention) — users who can't find the close button will bounce entirely - Large enough to tap on mobile - "No thanks" text link as alternative - Click outside to close diff --git a/skills/product-marketing-context/SKILL.md b/skills/product-marketing-context/SKILL.md index af050aa..e47cecb 100644 --- a/skills/product-marketing-context/SKILL.md +++ b/skills/product-marketing-context/SKILL.md @@ -47,7 +47,7 @@ For each section: 3. Confirm accuracy 4. Move to the next -**Important:** Push for verbatim customer language. Exact phrases are more valuable than polished descriptions. +Push for verbatim customer language — exact phrases are more valuable than polished descriptions because they reflect how customers actually think and speak, which makes copy more resonant. --- diff --git a/skills/programmatic-seo/SKILL.md b/skills/programmatic-seo/SKILL.md index 77c9cd9..aa07972 100644 --- a/skills/programmatic-seo/SKILL.md +++ b/skills/programmatic-seo/SKILL.md @@ -49,7 +49,7 @@ Hierarchy of data defensibility: 5. Public (anyone can use—weakest) ### 3. Clean URL Structure -**Always use subfolders, not subdomains**: +**Use subfolders, not subdomains** — subfolders consolidate domain authority while subdomains split it: - Good: `yoursite.com/templates/resume/` - Bad: `templates.yoursite.com/resume/` diff --git a/skills/revops/SKILL.md b/skills/revops/SKILL.md index 7591b16..3ef0119 100644 --- a/skills/revops/SKILL.md +++ b/skills/revops/SKILL.md @@ -133,7 +133,7 @@ Define response times and document them: ### Routing Rules Essentials - Route to the **most specific match** first, then fall back to general -- Always include a **fallback owner** — no lead should go unassigned +- Include a **fallback owner** — unassigned leads go cold fast and waste pipeline - Round-robin should account for **rep capacity and availability** (PTO, quota attainment) - Log every routing decision for audit and optimization diff --git a/skills/seo-audit/SKILL.md b/skills/seo-audit/SKILL.md index fab653d..a940b39 100644 --- a/skills/seo-audit/SKILL.md +++ b/skills/seo-audit/SKILL.md @@ -35,7 +35,7 @@ Before auditing, understand: ## Audit Framework -### ⚠️ Important: Schema Markup Detection Limitation +### Schema Markup Detection Limitation **`web_fetch` and `curl` cannot reliably detect structured data / schema markup.** @@ -46,7 +46,7 @@ Many CMS plugins (AIOSEO, Yoast, RankMath) inject JSON-LD via client-side JavaSc 2. **Google Rich Results Test** — https://search.google.com/test/rich-results 3. **Screaming Frog export** — if the client provides one, use it (SF renders JavaScript) -**Never report "no schema found" based solely on `web_fetch` or `curl`.** This has led to false audit findings in production. +Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false audit findings — these tools can't see JS-injected schema. ### Priority Order 1. **Crawlability & Indexation** (can Google find and index it?) @@ -382,7 +382,7 @@ Same format as above - Mobile-Friendly Test - Schema Validator -> **Note on schema detection:** `web_fetch` strips `