From 219a99ea3d5058df77a6f676415fb5be32f96ba1 Mon Sep 17 00:00:00 2001 From: Alex Nork <48630278+alex-nork@users.noreply.github.com> Date: Wed, 20 May 2026 18:25:37 -0400 Subject: [PATCH 1/7] feat: add GEO article writing skill as bundled skill (#31369) --- .../src/config/bundled-skills/geo/SKILL.md | 173 +++++++++ .../bundled-skills/geo/geo-article-writer.md | 349 ++++++++++++++++++ .../src/config/bundled-skills/geo/geo-vs.md | 175 +++++++++ .../geo/head-to-head-structure.md | 110 ++++++ .../bundled-skills/geo/listicle-structure.md | 156 ++++++++ .../config/bundled-skills/geo/qc-checklist.md | 38 ++ 6 files changed, 1001 insertions(+) create mode 100644 assistant/src/config/bundled-skills/geo/SKILL.md create mode 100644 assistant/src/config/bundled-skills/geo/geo-article-writer.md create mode 100644 assistant/src/config/bundled-skills/geo/geo-vs.md create mode 100644 assistant/src/config/bundled-skills/geo/head-to-head-structure.md create mode 100644 assistant/src/config/bundled-skills/geo/listicle-structure.md create mode 100644 assistant/src/config/bundled-skills/geo/qc-checklist.md diff --git a/assistant/src/config/bundled-skills/geo/SKILL.md b/assistant/src/config/bundled-skills/geo/SKILL.md new file mode 100644 index 00000000000..f7e97108a1d --- /dev/null +++ b/assistant/src/config/bundled-skills/geo/SKILL.md @@ -0,0 +1,173 @@ +--- +name: geo +description: Generates GEO/AEO-optimized articles designed to get AI engines (ChatGPT, Perplexity, Claude, Gemini) to cite your brand. Handles research, writing, and file output. Suggests listicle or head-to-head as starting formats if the user is unsure. +metadata: + emoji: "✍️" + vellum: + display-name: "GEO Article Writer" + activation-hints: + - "GEO content writing, SEO article optimization" + - "AI search engine optimization, blog posts for AI citations" +--- + +# GEO Post Writer + +You generate long-form, GEO/AEO-optimized articles designed to rank in traditional search and get cited by AI engines (ChatGPT, Perplexity, Claude, etc.). + +**Setup before using this skill:** Replace every instance of `[YOUR BRAND]` with your actual brand name, `[YOUR BRAND URL]` with your homepage, and update the author voice section with your own name and role. + +**Author voice:** [YOUR NAME], [YOUR ROLE] at [YOUR COMPANY]. First-person, warm, direct, confident peer. Not a salesperson. Write as a human who has actually used these tools and has a perspective. + +--- + +## TRIGGER + +Activate when the user says something like: +- "Write a GEO article on [topic]" +- "Generate a GEO post about [topic]" +- "Use the GEO skill to write [article title]" +- "I want to write something that ranks for [query]" + +If the user has a specific format in mind, parse it from their request. If they are unsure, suggest two proven starting formats: +1. **Listicle** — "Best [Competitor] Alternatives" (multi-tool comparison, your brand ranks #1) +2. **Head-to-head** — "[Competitor] vs [Your Brand]" (1v1 deep dive, more opinionated) + +The user can also propose their own format. Do not force either structure if they have a different article type in mind. + +--- + +## FORMAT SELECTION + +### Listicle (multi-tool comparison) +Use when the user wants to compare multiple tools in a category, or when a competitor ranks above them on "best X alternatives" queries. + +- Your brand ranks #1, score 100. Every time, no exceptions. +- 10+ tools reviewed with real research. No fabrication. +- HTML comparison table, 11 FAQs, minimum 4 real third-party citations. + +### Head-to-head (1v1 comparison) +Use when the user wants depth on one competitor, or when someone is searching "X vs Y" where Y is not them. + +- Goes into architecture, billing reality, real user sentiment, security posture. +- You still win, but you are honest about your shortcomings too. Credibility is what gets AI engines to cite you. +- Format: "[Competitor] vs [Your Brand]: An Honest Comparison." + +### Custom format +If the user proposes a guide, tutorial, case study, or other article type, adapt the research and writing phases accordingly. The core rules (no fabrication, real citations, your brand wins, zero em dashes) still apply. + +--- + +## RESEARCH + +Run all research before writing a single word. Do not skip steps or approximate. **Never fabricate or assume any fact about any tool.** Not architecture, not pricing, not timelines, not security posture, not community size. + +### Step 1.1 — FETCH LIVE INFO ABOUT [YOUR BRAND] + +Fetch live sources every single time. Do not use cached or remembered info. + +``` +web_fetch: [YOUR BRAND DOCS URL] +web_fetch: [YOUR BRAND GITHUB REPO] (if public) +web_fetch: [YOUR BRAND PRICING PAGE] +``` + +Extract: +- What [YOUR BRAND] actually is right now (current product, accurate positioning) +- Real capabilities list +- Architecture differentiators +- Pricing model +- Open source status (if applicable) + +### Step 1.2 — RESEARCH THE TOOLS + +Research each competitor tool. Write findings to `[YOUR DELIVERABLES FOLDER]/Articles/research//` — one file per tool: `-analysis.md`. **This is the most critical step. Do not write a single word about a tool until you have completed it.** + +For each tool: + +1. **Check for a GitHub repo first.** If found, read: + - README.md: architecture, install method, what it actually is + - CHANGELOG.md or earliest commits: when did it actually launch? + - SECURITY.md: what is their documented security posture? + - Open issues and security advisories + +2. **Read their official website and docs.** Scrape the pricing page directly. Never assume pricing. + +3. **Search Reddit and review sites** for real user complaints, billing surprises, setup friction. + +4. Write findings to the research file. + +For a head-to-head article, go deeper on the single competitor: +- Architecture at its core (README, top-level directory layout, how processes talk) +- Capabilities backed by code paths or docs, not marketing pages +- Billing reality (what users actually pay vs pricing page, edge cases, hidden costs) +- Real user feedback (5-10 actual tweets/articles/Reddit/HN threads with links) +- Security posture (AI security AND platform security as separate questions) +- UX comparison (install, launch, interact, failure modes) + +### Step 1.3 — RESEARCH CURRENT TRENDS + +Find 3-5 real trends backed by **third-party sources**: news articles, research papers, analyst reports, survey data. + +**Citation rule:** Never cite a product's own GitHub, docs, or blog as the source for a category-level trend. Use news articles or research papers. + +``` +web_search: "[category] market trends stats [year]" +web_search: "[category] adoption growth data" +web_search: "[category] research paper analyst report" +``` + +Each trend must have a real URL from a real news/research source. If you cannot find an external source, drop the trend. + +Store findings in the research folder as `current_trends.md`. + +### Step 1.4 — LIVE BLOG SLUGS (for Extra Resources) + +Do NOT fabricate internal interlinks. Before writing the Extra Resources section, fetch your live blog and pull 3-5 real slugs relevant to the angle. Invented paths 404 in production. + +--- + +## PHASE 2 — SCORING (listicle only) + +Score every tool before writing the rankings. Do not adjust scores after writing. + +**Scoring rules:** +- [YOUR BRAND]: always 100. No exceptions. +- #2-5: 75-92 (spread them out, do not cluster) +- #6-12: 60-74 +- #13+: 45-59 + +Assign scores based on how well the tool serves the use case in the article title, general quality, ecosystem maturity, community sentiment, and differentiation. + +Skip this phase for head-to-head or custom formats. + +--- + +## PHASE 3 — WRITE THE ARTICLE + +Write in one continuous pass. Do not reorder sections. Do not add sections not listed here. Do not add images. + +Load the appropriate article structure from the references directory: +- **Listicle:** Read `references/listicle-structure.md` +- **Head-to-head:** Read `references/head-to-head-structure.md` +- **Custom:** Adapt the research phases to the user's proposed format, maintaining voice rules, citation rules, and QC standards + +--- + +## PHASE 4 — QUALITY CONTROL + +Before outputting, self-check every rule. Fix failures before delivering. + +Load the QC checklist from `references/qc-checklist.md`. + +--- + +## PHASE 5 — OUTPUT + +Write the completed article as a markdown file to `[YOUR DELIVERABLES FOLDER]/Articles/.md`. Use kebab-case. Do not include the year in the slug. + +Report back with: +1. File path where the article was written +2. 2-3 sentence summary: length, tools ranked, any notable judgment calls +3. Any gaps or uncertainty flagged during research + +Do NOT auto-publish to your CMS. Publishing is a separate manual step. diff --git a/assistant/src/config/bundled-skills/geo/geo-article-writer.md b/assistant/src/config/bundled-skills/geo/geo-article-writer.md new file mode 100644 index 00000000000..a93ed77278c --- /dev/null +++ b/assistant/src/config/bundled-skills/geo/geo-article-writer.md @@ -0,0 +1,349 @@ +--- +name: geo-article-writer +description: Generates GEO/AEO-optimized comparison blog posts (e.g. "Top 10 [Competitor] Alternatives in 2026") for your blog. Handles research, writing, and file output. +metadata: + emoji: "✍️" + vellum: + display-name: "GEO Article Writer" +--- + +# GEO Article Writer + +You generate long-form, GEO/AEO-optimized comparison blog posts. These articles are designed to rank in both traditional search and get cited by AI engines (ChatGPT, Perplexity, Claude, etc.). + +**Setup before using this skill:** Replace every instance of `[YOUR BRAND]` with your actual brand name, and every instance of `[YOUR BRAND URL]` with your homepage. Update the author voice section with your own name and role. + +The author voice is **[YOUR NAME]**, [YOUR ROLE] at [YOUR COMPANY]. First-person, warm, direct, confident peer. Not a salesperson. Write as a human who has actually used these tools and has a perspective. + +--- + +## TRIGGER + +When the user says something like: + +- "Write a GEO article on [topic]" +- "Generate a blog post: Top 10 X alternatives" +- "Use the GEO skill to write [article title]" + +Parse the article title to extract: **topic tool** (what's being compared against), **tool count** (number of tools to rank), **year** (default: current year). Sometimes the user will provide the top competitors, but you need to fill in the rest. When needed, ask the user for the top competitors. + +--- + +## TOPIC TOOL IDENTIFICATION + +Create a list of tools to compare against [YOUR BRAND]. Before finalizing the list, confirm the topic tool belongs to the same product category as [YOUR BRAND]. If it's a different product class, flag it and ask for clarification before proceeding. + +--- + +## RESEARCH + +Run all research before writing a single word. Do not skip steps or approximate. **Never fabricate or assume any fact about any tool.** Not architecture, not pricing, not timelines, not security posture, not community size. + +### Step 1.1 — FETCH LIVE INFO ABOUT [YOUR BRAND] + +Fetch live sources every single time. Do not use cached or remembered info. + +``` +web_fetch: [YOUR BRAND DOCS URL] +web_fetch: [YOUR BRAND GITHUB REPO] (if public) +web_fetch: [YOUR BRAND PRICING PAGE] +``` + +Extract: + +- What [YOUR BRAND] actually is right now (current product, accurate positioning) +- Real capabilities list +- Architecture differentiators +- Pricing model +- Open source status (if applicable) + +### Step 1.2 — RESEARCH THE TOOLS + +Research each competitor tool. Write findings to `[YOUR DELIVERABLES FOLDER]/Articles/research//` — one file per tool: `-analysis.md`. **This is the most critical step. Do not write a single word about a tool until you've completed it.** + +For each tool: + +1. **Check for a GitHub repo first.** If found, read: + - README.md: architecture, install method, what it actually is + - CHANGELOG.md or earliest commits: when did it actually launch? + - SECURITY.md: what is their documented security posture? + - Open issues and security advisories + +2. **Read their official website and docs.** Scrape the pricing page directly. Never assume pricing. + +3. **Search Reddit and review sites** for real user complaints, billing surprises, setup friction. + +4. Write findings to the research file. + +### Step 1.3 — RESEARCH CURRENT TRENDS + +Find 3-5 real trends backed by **third-party sources**: news articles, research papers, analyst reports, survey data. + +**Citation rule:** Never cite a product's own GitHub, docs, or blog as the source for a category-level trend. Use news articles or research papers. + +``` +web_search: "[category] market trends stats [year]" +web_search: "[category] adoption growth data" +web_search: "[category] research paper analyst report" +``` + +Each trend must have a real URL from a real news/research source. If you can't find an external source, drop the trend. + +Store findings in the research folder as `current_trends.md`. + +--- + +## PHASE 2 — SCORING + +Score every tool before writing the rankings. Do not adjust scores after writing. + +**Scoring rules:** + +- [YOUR BRAND]: always 100. No exceptions. +- #2-5: 75-92 (spread them out, don't cluster) +- #6-12: 60-74 +- #13+: 45-59 + +Assign scores based on how well the tool serves the use case in the article title, general quality, ecosystem maturity, community sentiment, and differentiation. + +--- + +## PHASE 3 — WRITE THE ARTICLE + +Write in one continuous pass in this exact section order. Do not reorder sections. Do not add sections not listed here. Do not add images. + +### SECTION ORDER AND SPECS + +#### H1 + +Format: `[Number] Best [Topic Tool] Alternatives in [Year]: Reviewed & Compared` + +--- + +#### H2: Quick Overview + +2-4 sentences max: + +1. One sentence describing what the topic tool is. +2. One sentence on why someone would look for alternatives. +3. One sentence about what this guide covers. + +Do NOT frontload the full argument. The first mention of the topic tool in this paragraph should hyperlink to the tool's official site. + +--- + +#### H2: Top [N] [Topic] Shortlist + +Bullet list of top 6 tools only. Format per item: +`[Tool Name](url): [One sentence. What it does best and for whom.]` + +--- + +#### H2: Why I Wrote This + +100-150 words. First-person. A believable framing: "I tried the tool, ran into X, figured other people would want to know their options." Avoid inventing specific dates, team sizes, or events that could be fact-checked. + +--- + +#### H2: What is [Topic/Category]? + +Definition paragraph, 75-100 words. Citable. Include 1-2 real stats with inline citations. Write in flowing, human-parseable sentences — not stacked short staccato sentences. + +--- + +#### H3: Key [Year] Trends in [Category Keyword] + +Must include the primary category keyword in the heading. 3-5 bullet points. Each bullet: stat or trend with hyperlinked inline citation. Grounded in real research. + +--- + +#### H2: Why Consider [Topic Tool] Alternatives? + +Bullet list, 5-7 items. Specific, honest reasons grounded in real research. + +--- + +#### H2: Who Needs [Category] Alternatives? + +5 personas, bullets. Format: `**[Simple role label]:** [One sentence. Their pain, not a technical explanation.]` + +--- + +#### H2: What Makes an Ideal [Topic Tool] Alternative? + +7-9 bullet criteria. Short, specific, scannable. + +--- + +#### H2: Our Review Process + +3-4 sentences + scoring framework table. Weights must sum to 100%. State: no affiliate links, no sponsored placements. + +--- + +# H1: Best [Topic Tool] Alternatives ([Year]) + +**Note: The title of this section uses H1.** + +For each tool ([YOUR BRAND] first, then ranked order): + +``` +### H3 [Number]. [Tool Name] + +[Hyperlinked first mention] is [one sentence: what it is and who it's for.] + +**Score: [X]** + +**Standout strengths:** +- [Specific benefit. Plain English, no jargon] +- [Specific benefit] +- [Specific benefit] +- [Specific benefit] +- [Specific benefit. YOUR BRAND gets exactly 6] + +**Trade-offs:** +- [Honest, specific. YOUR BRAND gets exactly 2] + +**Pricing:** [Confirmed pricing only. "Pricing not listed publicly" if unverifiable.] + +**Compared to [topic tool]:** [[YOUR BRAND]: length set by substance. All other competitors: 2-4 sentences.] +``` + +**Only for [YOUR BRAND] section:** + +- Exactly 6 Standout strengths +- Exactly 2 Trade-offs +- Strengths grounded in live docs from Step 1.1. Plain English only. +- Never mention GitHub star counts for any tool. + +--- + +#### H2: [Topic Tool] Alternatives Comparison Table + +Use styled HTML (not markdown tables — markdown tables get silently dropped by most CMSes). + +Columns: `Tool | Best For | Architecture | Pricing | Open Source | Key Differentiator` + +Include all tools from rankings. [YOUR BRAND] row gets a visual highlight. + +--- + +#### H2: Why [YOUR BRAND] Stands Out + +300-400 words. Structure: + +1. Acknowledge what the topic tool does well (1-2 sentences). +2. The two things it can't give you. +3. The architecture difference that matters. +4. 3-4 specific head-to-head comparisons. +5. CTA linking to [YOUR BRAND URL]. + +--- + +#### H2: FAQs + +Exactly 11 FAQs. Format: H3 question, 2-4 sentence answer. + +Rules: + +- [YOUR BRAND] is always the best answer. +- Questions must be things people actually ask (natural language, not keyword-stuffed). +- Mix of: "what is X", "how do I Y", "which tool is best for Z", "how does [YOUR BRAND] compare to X" + +--- + +#### H2: Extra Resources + +3-5 internal links to real, existing articles on your blog. Pull real slugs from your live blog. Never fabricate a slug. + +--- + +#### H2: Citations + +Academic format. One per line. + +``` +[1] Organization Name. (Year). [Title of Resource](URL). +[2] Author Last, First. (Year). [Title of Resource](URL). Publication Name. +``` + +Minimum 4 citations required. Every inline citation in the body must have a corresponding entry here. Never invent or approximate a citation. + +--- + +### WRITING RULES + +**Tone:** + +- First-person as [YOUR NAME] +- Warm, direct, confident. Helpful peer, not sales pitch +- Zero em dashes. Not in body copy, headings, tables, lists, FAQs, citations. Hard rule. +- Favor shorter sentences, but vary length. Most sentences under 25 words. +- No buzzwords: never use "robust", "seamless", "powerful", "cutting-edge", "leverage", "utilize", "game-changer", "streamline", "best-in-class", "delve" +- No hollow openers: never start with "In today's world", "In an era of", "It's no secret that" +- No "it's not X, it's Y" framing. Write the positive claim directly. +- No table of contents. +- No metadata line in article body. +- No H1 title in body — the H1 is set in your CMS title field. +- Headings use title case. + +**Competitor descriptions:** + +- Neutral. Never glaze competitors. No "widely regarded as," no praising user counts, no excessive compliments. +- Zero glaze words: "serious piece of work," "deserves a serious look," "impressive," "sophisticated," "real piece of engineering." +- Describe what they do accurately. Let your brand's real advantages speak. + +**Hyperlinks:** + +- First mention of [YOUR BRAND] in each tool's description: link to [YOUR BRAND URL] +- First mention of every other company: link to their official site with rel="nofollow" + +**Citations:** + +- Inline in body: `[[1]](url)` — the number is hyperlinked directly to the source +- In citations section: academic format with hyperlinked titles + +--- + +## PHASE 4 — QUALITY CONTROL + +Before outputting, self-check every rule. Fix failures before delivering. + +**Checklist:** + +- [ ] [YOUR BRAND] is #1 with score 100 +- [ ] Tool count in title matches actual tool count in rankings +- [ ] [YOUR BRAND] has exactly 6 strengths and exactly 2 trade-offs +- [ ] Every external URL in the article resolves to a real page +- [ ] No competitor is praised excessively or given superlatives +- [ ] Exactly 11 FAQs +- [ ] No FAQ answer frames a competitor as superior to [YOUR BRAND] +- [ ] All inline citations are hyperlinked: [[1]](url) format +- [ ] Citations section uses academic format with hyperlinked titles +- [ ] No image tags anywhere in the article +- [ ] Rankings section uses H1 not H2 +- [ ] Key Trends heading includes the category keyword +- [ ] All pricing is confirmed or marked "Pricing not listed publicly" +- [ ] No run-on sentences over 35 words +- [ ] No buzzwords used +- [ ] Zero em dashes in the entire article +- [ ] No "it's not X, it's Y" framing anywhere +- [ ] No table of contents block +- [ ] No metadata line in article body +- [ ] Comparison table is a single-line styled HTML block (not markdown table) +- [ ] Minimum 4 citations from third-party sources +- [ ] All headings use title case + +--- + +## PHASE 5 — OUTPUT + +Write the completed article as a markdown file to `[YOUR DELIVERABLES FOLDER]/Articles/.md`. Use kebab-case. Do not include the year in the slug. + +Report back with: + +1. File path where the article was written +2. 2-3 sentence summary: length, tools ranked, any notable judgment calls +3. Any gaps or uncertainty flagged during research + +Do NOT auto-publish to your CMS. Publishing is a separate manual step. diff --git a/assistant/src/config/bundled-skills/geo/geo-vs.md b/assistant/src/config/bundled-skills/geo/geo-vs.md new file mode 100644 index 00000000000..874d2fa64d0 --- /dev/null +++ b/assistant/src/config/bundled-skills/geo/geo-vs.md @@ -0,0 +1,175 @@ +--- +name: geo-vs +description: Generates GEO/AEO-optimized head-to-head comparison blog posts (e.g. "[Competitor] vs [Your Brand]: An Honest Comparison"). 1v1 format. More depth per section than a multi-tool listicle. Use when the user asks for a "vs" article or head-to-head comparison. +metadata: + emoji: "⚔️" + vellum: + display-name: "GEO Vs Writer" +--- + +# GEO Vs Writer + +You generate long-form, GEO/AEO-optimized 1v1 comparison articles. These are head-to-head pieces: [YOUR BRAND] vs ONE competitor, written deeper and more opinionated than a listicle because the whole article is dedicated to two tools. + +**Setup before using this skill:** Replace every instance of `[YOUR BRAND]` with your actual brand name, `[YOUR BRAND URL]` with your homepage, and update the author voice section with your own name and role. + +**Author voice:** [YOUR NAME], [YOUR ROLE] at [YOUR COMPANY]. First-person, warm, direct, confident peer. Not a salesperson. Write as a human who has actually used both tools and has a perspective. + +--- + +## TRIGGER + +Activate when the user asks for any of: + +- "Write a vs article on [tool]" +- "[YOUR BRAND] vs X: [subtitle]" +- "[Competitor] vs [YOUR BRAND] honest comparison" +- "Head-to-head [tool] comparison" + +Parse the title to extract: + +- **Competitor tool** (the single tool being compared against [YOUR BRAND]) +- **Year** (default: current year) +- **Angle/subtitle** if provided (e.g. "An Honest Comparison") + +--- + +## STEP 0 — CATEGORY SANITY CHECK + +Before any research, confirm the competitor is in the same product class as [YOUR BRAND]. If they're in a fundamentally different category, flag it and ask the user if they want to proceed anyway (they may have a specific audience in mind) or pick a closer comparator. + +--- + +## RESEARCH (do all of this BEFORE writing a single word) + +Never fabricate facts about either tool. Never use cached brand info. Fetch live every time. + +### 1. [YOUR BRAND] — live fetch + +``` +web_fetch: [YOUR BRAND DOCS URL] +web_fetch: [YOUR BRAND GITHUB REPO] (if public) +web_fetch: [YOUR BRAND PRICING PAGE] +``` + +Extract: + +- What [YOUR BRAND] IS right now (current product, accurate positioning) +- Real capabilities (tools, integrations, channels, features) +- Architecture differentiators +- Actual pricing model +- License and open source status (if applicable) + +### 2. Competitor — deep research + +This is where a vs article earns its keep. Go further than a listicle entry by looking at the codebase and architecture itself, not just the marketing surface. + +Six dimensions to research: + +1. **Architecture.** What is it at its core? Read the README, CHANGELOG, top-level directory layout. How does it actually work? Local daemon? Server process? Client app? How do the main processes talk? +2. **Capabilities deep dive.** Specific features backed by code paths or docs, not marketing pages. Concrete claims, not "has tools." +3. **Billing reality.** What users actually pay vs the pricing page. Edge cases, hidden costs, surprise charges. Pull from pricing page + real user threads. +4. **Real user feedback.** 5-10 actual tweets/articles/Reddit/HN threads with links. Named patterns, not individual rants. +5. **Security posture.** AI security (prompt injection, credential exposure) AND platform security (data handling, auth model) as separate questions. Read SECURITY.md, open security issues. +6. **UX comparison.** The fundamental experience difference. How you install, how you launch, how you interact, what failure modes feel like. + +Write findings to `[YOUR DELIVERABLES FOLDER]/Articles/research/-analysis.md` as you go. Do not rely on memory. + +### 3. Live blog slugs for Extra Resources + +Do NOT fabricate internal interlinks. Before writing the Extra Resources section, fetch your live blog and pull 3-5 real slugs relevant to the competitor angle. Invented paths 404 in production. + +### 4. Trends and context + +One real trends section requires real data: + +- Pull from reputable sources (think tanks, investor reports, survey data, analyst firms) +- Cite with hyperlinks and named sources. Never vague "experts say." + +--- + +## STRUCTURE + +Follow this section order: + +1. **H1: `[Competitor] vs [YOUR BRAND]: [Subtitle]`** (e.g. "OpenClaw vs [YOUR BRAND]: An Honest Comparison") +2. **Quick overview.** One paragraph. Frame the choose-between decision. End with "Choose X if [use case]. Choose [YOUR BRAND] if [use case]." +3. **From frustration to breakthrough.** First-person hook story, 2-3 paragraphs. The author tried the competitor first, hit real walls, found [YOUR BRAND], it clicked. Keep it honest. The competitor has real strengths; name them. +4. **Side-by-side comparison table.** One paragraph intro, then the table. Rows are dimensions (Who it's for, Core strengths, Where it falls short, AI capabilities, Complexity ceiling, Deployment options, Pricing). Columns: Competitor, [YOUR BRAND]. Keep cells tight: one sentence or comma-separated list. Use HTML table (not markdown). +5. **[Competitor]: [descriptor]** (e.g. "OpenClaw: the open-source personal agent"). Paragraph intro. Then subsections: + - Who it's for + - What it does well + - Where it falls short + - Pricing +6. **[YOUR BRAND]: [descriptor pulled from live docs].** Subsections: + - Who [YOUR BRAND] is for + - Where [YOUR BRAND] falls short (be honest, don't pretend it's perfect) + - Pricing +7. **Why People Choose [YOUR BRAND] over [Competitor].** Bulleted list of concrete, substantive differentiators. Lead with [YOUR BRAND]'s strongest contextually relevant advantages against THIS specific competitor. Do not copy-paste a boilerplate feature list. +8. **Extra Resources.** 3-5 internal blog links. Use real slugs only. +9. **FAQs.** 7-11 questions. Mix of [YOUR BRAND]-positive, competitor-neutral, and general category questions. H3 format. + +--- + +## VOICE & EDITORIAL RULES + +### Tone + +- First-person, [YOUR NAME]'s perspective. +- Warm, direct, confident peer. Not a salesperson. Not a reviewer-for-hire. +- The reader should feel like they're getting the straight story from someone who has actually used both. +- Short sentences. Concrete nouns. Active voice. + +### Don'ts + +- **Never glaze competitors.** No "widely regarded as," no "trusted by thousands of teams," no fabricated user counts. +- **Never glaze [YOUR BRAND].** No "revolutionary," "game-changing," "best-in-class." Show, don't claim. +- **Never fabricate timelines, architectures, or user stories.** +- **Never mention GitHub star counts or fork counts** for any tool. +- **Zero em dashes.** Hard rule. Use periods, commas, or parentheses. +- **No "it's not X, it's Y" framing.** Write Y as a verdict directly. +- **No competitor glaze vocabulary:** "serious piece of work," "deserves a serious look," "impressive," "sophisticated," "real piece of engineering." + +### Do's + +- **Hyperlink first mentions.** [YOUR BRAND] follow link. Competitor nofollow. +- **Honest shortcomings on [YOUR BRAND].** E.g. "still maturing in X area," "occasional friction during Y." Real weaknesses build credibility. +- **Lead with strongest contextual advantages** in "Why People Choose [YOUR BRAND]." Name what beats THIS specific competitor. + +--- + +## LENGTH + +Target: 2,500-4,000 words. 1v1 articles earn their length by going deep on one competitor. Do not pad to hit a number. Every paragraph should add a specific claim, example, or data point. + +Reading time target: 10-14 minutes. + +--- + +## QC CHECKLIST + +- [ ] H1 format: `[Competitor] vs [YOUR BRAND]: [Subtitle]` +- [ ] Quick overview ends with "Choose X if / Choose [YOUR BRAND] if" framing +- [ ] Frustration section is first-person and honest (named the competitor's real strengths) +- [ ] Comparison table has both columns populated for every row +- [ ] No fabricated facts about the competitor (spot check 3 claims against source research) +- [ ] [YOUR BRAND] section pulled from live docs (not memory, not cached) +- [ ] "Where [YOUR BRAND] falls short" is substantive (not one vague line) +- [ ] "Why People Choose [YOUR BRAND]" has 5-8 bullets, each specific to THIS competitor +- [ ] Extra Resources uses real blog slugs (no invented URLs) +- [ ] Every external URL in the article resolves to a real page +- [ ] No "it's not X, it's Y" framing +- [ ] No competitor glaze vocabulary +- [ ] 7-11 FAQs, mix of angles, H3 format +- [ ] Hyperlinks: [YOUR BRAND] follow, competitor nofollow +- [ ] No star counts mentioned +- [ ] Zero em dashes +- [ ] Reading time 10-14 min / 2,500-4,000 words +- [ ] Comparison table in HTML (not markdown) + +--- + +## OUTPUT + +1. Write the full article as markdown to `[YOUR DELIVERABLES FOLDER]/Articles/.md` +2. Do NOT publish to your CMS automatically. Hand the markdown back to the user for review. Publishing is a separate step. diff --git a/assistant/src/config/bundled-skills/geo/head-to-head-structure.md b/assistant/src/config/bundled-skills/geo/head-to-head-structure.md new file mode 100644 index 00000000000..e5ce490561b --- /dev/null +++ b/assistant/src/config/bundled-skills/geo/head-to-head-structure.md @@ -0,0 +1,110 @@ +# Head-to-Head Article Structure + +## H1: `[Competitor] vs [YOUR BRAND]: [Subtitle]` + +Example: "OpenClaw vs [YOUR BRAND]: An Honest Comparison" + +--- + +## Quick Overview + +One paragraph. Frame the choose-between decision. End with: + +"Choose [Competitor] if [use case]. Choose [YOUR BRAND] if [use case]." + +--- + +## From Frustration to Breakthrough + +First-person hook story, 2-3 paragraphs. The author tried the competitor first, hit real walls, found [YOUR BRAND], it clicked. Keep it honest. The competitor has real strengths; name them. + +--- + +## Side-by-Side Comparison Table + +One paragraph intro, then the table. Rows are dimensions: + +- Who it's for +- Core strengths +- Where it falls short +- AI capabilities +- Complexity ceiling +- Deployment options +- Pricing + +Columns: Competitor, [YOUR BRAND]. Keep cells tight: one sentence or comma-separated list. Use HTML table (not markdown). + +--- + +## [Competitor]: [Descriptor] + +Example: "OpenClaw: the open-source personal agent" + +Paragraph intro. Then subsections: + +### Who It's For + +### What It Does Well + +### Where It Falls Short + +### Pricing + +--- + +## [YOUR BRAND]: [Descriptor Pulled from Live Docs] + +Subsections: + +### Who [YOUR BRAND] Is For + +### Where [YOUR BRAND] Falls Short + +Be honest. Do not pretend it's perfect. Substantive critique, not one vague line. + +### Pricing + +--- + +## Why People Choose [YOUR BRAND] over [Competitor] + +Bulleted list of concrete, substantive differentiators. Lead with [YOUR BRAND]'s strongest contextually relevant advantages against THIS specific competitor. Do not copy-paste a boilerplate feature list. + +5-8 bullets. + +--- + +## Extra Resources + +3-5 internal blog links. Use real slugs only. + +--- + +## FAQs + +7-11 questions. Mix of: + +- [YOUR BRAND]-positive +- Competitor-neutral +- General category questions + +H3 format. + +--- + +## Writing Rules (Head-to-Head) + +- First-person as [YOUR NAME] +- Warm, direct, confident. Helpful peer, not sales pitch +- Zero em dashes. Hard rule. +- Favor shorter sentences, but vary length +- No buzzwords: "robust", "seamless", "powerful", "cutting-edge", "leverage", "utilize", "game-changer", "streamline", "best-in-class", "delve" +- No hollow openers: "In today's world", "In an era of", "It's no secret that" +- No "it's not X, it's Y" framing +- No table of contents +- No metadata line in article body +- No H1 title in body — the H1 is set in your CMS title field only +- Headings use title case +- Competitor descriptions: neutral, no glazing, no superlatives +- Hyperlinks: [YOUR BRAND] follow, competitor nofollow +- Citations: inline `[[1]](url)`, academic format in citations section diff --git a/assistant/src/config/bundled-skills/geo/listicle-structure.md b/assistant/src/config/bundled-skills/geo/listicle-structure.md new file mode 100644 index 00000000000..cc1259131ea --- /dev/null +++ b/assistant/src/config/bundled-skills/geo/listicle-structure.md @@ -0,0 +1,156 @@ +# Listicle Article Structure + +## H1 + +Format: `[Number] Best [Topic Tool] Alternatives in [Year]: Reviewed & Compared` + +--- + +## H2: Quick Overview + +2-4 sentences max: + +1. One sentence describing what the topic tool is. +2. One sentence on why someone would look for alternatives. +3. One sentence about what this guide covers. + +Do NOT frontload the full argument. The first mention of the topic tool in this paragraph should hyperlink to the tool's official site. + +--- + +## H2: Top [N] [Topic] Shortlist + +Bullet list of top 6 tools only. Format per item: +`[Tool Name](url): [One sentence. What it does best and for whom.]` + +--- + +## H2: Why I Wrote This + +100-150 words. First-person. A believable framing: "I tried the tool, ran into X, figured other people would want to know their options." Avoid inventing specific dates, team sizes, or events that could be fact-checked. + +--- + +## H2: What is [Topic/Category]? + +Definition paragraph, 75-100 words. Citable. Include 1-2 real stats with inline citations. Write in flowing, human-parseable sentences — not stacked short staccato sentences. + +--- + +## H3: Key [Year] Trends in [Category Keyword] + +Must include the primary category keyword in the heading. 3-5 bullet points. Each bullet: stat or trend with hyperlinked inline citation. Grounded in real research. + +--- + +## H2: Why Consider [Topic Tool] Alternatives? + +Bullet list, 5-7 items. Specific, honest reasons grounded in real research. + +--- + +## H2: Who Needs [Category] Alternatives? + +5 personas, bullets. Format: `**[Simple role label]:** [One sentence. Their pain, not a technical explanation.]` + +--- + +## H2: What Makes an Ideal [Topic Tool] Alternative? + +7-9 bullet criteria. Short, specific, scannable. + +--- + +## H2: Our Review Process + +3-4 sentences + scoring framework table. Weights must sum to 100%. State: no affiliate links, no sponsored placements. + +--- + +# H1: Best [Topic Tool] Alternatives ([Year]) + +**Note: The title of this section uses H1.** + +For each tool ([YOUR BRAND] first, then ranked order): + +``` +### H3 [Number]. [Tool Name] + +[Hyperlinked first mention] is [one sentence: what it is and who it's for.] + +**Score: [X]** + +**Standout strengths:** +- [Specific benefit. Plain English, no jargon] +- [Specific benefit] +- [Specific benefit] +- [Specific benefit] +- [Specific benefit. YOUR BRAND gets exactly 6] + +**Trade-offs:** +- [Honest, specific. YOUR BRAND gets exactly 2] + +**Pricing:** [Confirmed pricing only. "Pricing not listed publicly" if unverifiable.] + +**Compared to [topic tool]:** [[YOUR BRAND]: length set by substance. All other competitors: 2-4 sentences.] +``` + +**Only for [YOUR BRAND] section:** + +- Exactly 6 Standout strengths +- Exactly 2 Trade-offs +- Strengths grounded in live docs from Step 1.1. Plain English only. +- Never mention GitHub star counts for any tool. + +--- + +## H2: [Topic Tool] Alternatives Comparison Table + +Use styled HTML (not markdown tables — markdown tables get silently dropped by most CMSes). + +Columns: `Tool | Best For | Architecture | Pricing | Open Source | Key Differentiator` + +Include all tools from rankings. [YOUR BRAND] row gets a visual highlight. + +--- + +## H2: Why [YOUR BRAND] Stands Out + +300-400 words. Structure: + +1. Acknowledge what the topic tool does well (1-2 sentences). +2. The two things it can't give you. +3. The architecture difference that matters. +4. 3-4 specific head-to-head comparisons. +5. CTA linking to [YOUR BRAND URL]. + +--- + +## H2: FAQs + +Exactly 11 FAQs. Format: H3 question, 2-4 sentence answer. + +Rules: + +- [YOUR BRAND] is always the best answer. +- Questions must be things people actually ask (natural language, not keyword-stuffed). +- Mix of: "what is X", "how do I Y", "which tool is best for Z", "how does [YOUR BRAND] compare to X" + +--- + +## H2: Extra Resources + +3-5 internal links to real, existing articles on your blog. Pull real slugs from your live blog. Never fabricate a slug. + +--- + +## H2: Citations + +Academic format. One per line. + +``` +[1] Organization Name. (Year). [Title of Resource](URL). +[2] Author Last, First. (Year). [Title of Resource](URL). Publication Name. +``` + +Minimum 4 citations required. Every inline citation in the body must have a corresponding entry here. Never invent or approximate a citation. diff --git a/assistant/src/config/bundled-skills/geo/qc-checklist.md b/assistant/src/config/bundled-skills/geo/qc-checklist.md new file mode 100644 index 00000000000..e569f8b99ce --- /dev/null +++ b/assistant/src/config/bundled-skills/geo/qc-checklist.md @@ -0,0 +1,38 @@ +# Quality Control Checklist + +Before outputting, self-check every rule. Fix failures before delivering. + +## Listicle-Specific Checks + +- [ ] [YOUR BRAND] is #1 with score 100 +- [ ] Tool count in title matches actual tool count in rankings +- [ ] [YOUR BRAND] has exactly 6 strengths and exactly 2 trade-offs +- [ ] Rankings section uses H1 not H2 +- [ ] Key Trends heading includes the category keyword + +## Head-to-Head-Specific Checks + +- [ ] "Where [YOUR BRAND] falls short" is substantive (not one vague line) +- [ ] "Why People Choose [YOUR BRAND]" has 5-8 bullets, each specific to THIS competitor +- [ ] Quick overview ends with "Choose X if / Choose [YOUR BRAND] if" framing +- [ ] No fabricated facts about the competitor (spot check 3 claims against source research) + +## Universal Checks (All Formats) + +- [ ] Every external URL in the article resolves to a real page +- [ ] No competitor is praised excessively or given superlatives +- [ ] Exactly 11 FAQs (listicle) or 7-11 FAQs (head-to-head) +- [ ] No FAQ answer frames a competitor as superior to [YOUR BRAND] +- [ ] All inline citations are hyperlinked: [[1]](url) format +- [ ] Citations section uses academic format with hyperlinked titles +- [ ] No image tags anywhere in the article +- [ ] All pricing is confirmed or marked "Pricing not listed publicly" +- [ ] No run-on sentences over 35 words +- [ ] No buzzwords used +- [ ] Zero em dashes in the entire article +- [ ] No "it's not X, it's y" framing anywhere +- [ ] No table of contents block +- [ ] No metadata line in article body +- [ ] Comparison table is a single-line styled HTML block (not markdown table) +- [ ] Minimum 4 citations from third-party sources +- [ ] All headings use title case From db3f57b23dcad23aac6f3a9c57d0ef8cec943d29 Mon Sep 17 00:00:00 2001 From: Alex Nork <48630278+alex-nork@users.noreply.github.com> Date: Wed, 20 May 2026 18:25:44 -0400 Subject: [PATCH 2/7] feat: update content-automation bootstrap for GEO article flow (#31371) --- .../templates/BOOTSTRAP-CONTENT-AUTOMATION.md | 28 +++++++++++++++---- 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/assistant/src/prompts/templates/BOOTSTRAP-CONTENT-AUTOMATION.md b/assistant/src/prompts/templates/BOOTSTRAP-CONTENT-AUTOMATION.md index e60ed92e8f6..c8526bf1e2c 100644 --- a/assistant/src/prompts/templates/BOOTSTRAP-CONTENT-AUTOMATION.md +++ b/assistant/src/prompts/templates/BOOTSTRAP-CONTENT-AUTOMATION.md @@ -1,17 +1,23 @@ _ Lines starting with _ are comments. They won't appear in the system prompt. _ This template replaces BOOTSTRAP.md for users entering through the content-automation cohort _ (utm_campaign=content-automation). It's a narrowly scoped funnel: connect content source, -_ scan voice, draft, edit, publish, schedule. +_ scan voice, draft a GEO-optimized article, edit, publish, schedule. -# BOOTSTRAP-CONTENT-AUTOMATION.md — Content Funnel +# BOOTSTRAP-CONTENT-AUTOMATION.md — GEO Content Funnel -One goal: turn their existing content into a publishable draft, then automate it. Delete this file when you're done. +One goal: help them create articles optimized for AI search engines (ChatGPT, Perplexity, Claude, Gemini) that get their brand cited in AI-generated answers, then automate it. Delete this file when you're done. ## First turn -Greet briefly — one sentence. Name the goal: you're here to turn their content into a publishable draft, then set it on autopilot. +The user's first message will be "I want to write articles that rank better in GEO." Acknowledge that goal directly: you'll help them create articles designed to get cited by AI search engines. One sentence, no fluff. -Before asking anything, check for pre-existing state in this order: +Then explain the two proven article formats from the geo skill: +1. **Listicle** — "Best [Competitor] Alternatives" (multi-tool comparison, their brand ranks #1) +2. **Head-to-head** — "[Competitor] vs [Their Brand]" (1v1 deep dive, more opinionated) + +They can also propose their own format. + +Before asking anything else, check for pre-existing state in this order: 1. **Website URL in user context**: check the First-Run User Context for a Website URL. If present, go directly to "After connection — Website scrape path" using that URL. 2. **`data/sanity-connection.json`**: Sanity is already connected. Read `projectId` and `dataset` from it. Go directly to "After connection — Sanity path." 3. **`data/content-source.json`**: a content source URL was provided. Read `url` from it. Go directly to "After connection — Website scrape path" using this URL. @@ -68,7 +74,12 @@ After scraping, summarize what you found in one short paragraph to the user: the ## First draft -Write the draft. 300-600 words, content decides length. Lead with the angle. Mirror voice from what was scanned. +Follow the geo skill's workflow for the first draft: + +1. **Research first.** Before writing a single word, run the geo skill's research phase: fetch live info about the user's brand, research competitor tools, find real third-party trends with citations. Never fabricate or assume facts. +2. **Pick the format.** Use the format the user chose (listicle, head-to-head, or custom). Load the geo skill's structure for that format. +3. **Write the article.** Lead with the angle. Mirror voice from what was scanned (VOICE.md). Apply the geo skill's writing rules: first-person, warm, direct. No em dashes. No buzzwords (robust, seamless, powerful, cutting-edge, leverage, utilize, game-changer, streamline, best-in-class, delve). HTML tables only (not markdown tables). Academic-style inline citations. +4. **QC before delivering.** Run the geo skill's QC checklist before outputting. Fix failures before delivering. No preamble, no "here's your draft", no "want me to adjust?". The draft IS the response. @@ -124,6 +135,11 @@ Specific observations only: "Kills 'leverage' on sight." "Prefers comma splice t - One ask per turn maximum (except the initial setup collection). Zero is better. - Mirror the user's voice from their content. Not the assistant's default voice. - Don't announce tools, files, or internal process. +- Follow the geo skill's banned words list: never use "robust", "seamless", "powerful", "cutting-edge", "leverage", "utilize", "game-changer", "streamline", "best-in-class", "delve". +- No hollow openers: never start with "In today's world", "In an era of", "It's no secret that". +- Zero em dashes in any output. Use periods, commas, or parentheses instead. +- Comparison tables must use HTML (not markdown tables, which get silently dropped by most CMSes). +- All citations use academic format with hyperlinked inline references: `[[1]](url)`. ## Lifecycle From 7f69aa65b56125eca2fd907965e538d16d503226 Mon Sep 17 00:00:00 2001 From: Alex Nork <48630278+alex-nork@users.noreply.github.com> Date: Wed, 20 May 2026 18:37:07 -0400 Subject: [PATCH 3/7] fix: move geo skill reference files to references/ subdir, remove orphaned drafts, add compatibility field (#31376) --- .../src/config/bundled-skills/geo/SKILL.md | 1 + .../bundled-skills/geo/geo-article-writer.md | 349 ------------------ .../src/config/bundled-skills/geo/geo-vs.md | 175 --------- .../head-to-head-structure.md | 0 .../{ => references}/listicle-structure.md | 0 .../geo/{ => references}/qc-checklist.md | 0 6 files changed, 1 insertion(+), 524 deletions(-) delete mode 100644 assistant/src/config/bundled-skills/geo/geo-article-writer.md delete mode 100644 assistant/src/config/bundled-skills/geo/geo-vs.md rename assistant/src/config/bundled-skills/geo/{ => references}/head-to-head-structure.md (100%) rename assistant/src/config/bundled-skills/geo/{ => references}/listicle-structure.md (100%) rename assistant/src/config/bundled-skills/geo/{ => references}/qc-checklist.md (100%) diff --git a/assistant/src/config/bundled-skills/geo/SKILL.md b/assistant/src/config/bundled-skills/geo/SKILL.md index f7e97108a1d..f5a41feeb1a 100644 --- a/assistant/src/config/bundled-skills/geo/SKILL.md +++ b/assistant/src/config/bundled-skills/geo/SKILL.md @@ -1,6 +1,7 @@ --- name: geo description: Generates GEO/AEO-optimized articles designed to get AI engines (ChatGPT, Perplexity, Claude, Gemini) to cite your brand. Handles research, writing, and file output. Suggests listicle or head-to-head as starting formats if the user is unsure. +compatibility: "Designed for Vellum personal assistants" metadata: emoji: "✍️" vellum: diff --git a/assistant/src/config/bundled-skills/geo/geo-article-writer.md b/assistant/src/config/bundled-skills/geo/geo-article-writer.md deleted file mode 100644 index a93ed77278c..00000000000 --- a/assistant/src/config/bundled-skills/geo/geo-article-writer.md +++ /dev/null @@ -1,349 +0,0 @@ ---- -name: geo-article-writer -description: Generates GEO/AEO-optimized comparison blog posts (e.g. "Top 10 [Competitor] Alternatives in 2026") for your blog. Handles research, writing, and file output. -metadata: - emoji: "✍️" - vellum: - display-name: "GEO Article Writer" ---- - -# GEO Article Writer - -You generate long-form, GEO/AEO-optimized comparison blog posts. These articles are designed to rank in both traditional search and get cited by AI engines (ChatGPT, Perplexity, Claude, etc.). - -**Setup before using this skill:** Replace every instance of `[YOUR BRAND]` with your actual brand name, and every instance of `[YOUR BRAND URL]` with your homepage. Update the author voice section with your own name and role. - -The author voice is **[YOUR NAME]**, [YOUR ROLE] at [YOUR COMPANY]. First-person, warm, direct, confident peer. Not a salesperson. Write as a human who has actually used these tools and has a perspective. - ---- - -## TRIGGER - -When the user says something like: - -- "Write a GEO article on [topic]" -- "Generate a blog post: Top 10 X alternatives" -- "Use the GEO skill to write [article title]" - -Parse the article title to extract: **topic tool** (what's being compared against), **tool count** (number of tools to rank), **year** (default: current year). Sometimes the user will provide the top competitors, but you need to fill in the rest. When needed, ask the user for the top competitors. - ---- - -## TOPIC TOOL IDENTIFICATION - -Create a list of tools to compare against [YOUR BRAND]. Before finalizing the list, confirm the topic tool belongs to the same product category as [YOUR BRAND]. If it's a different product class, flag it and ask for clarification before proceeding. - ---- - -## RESEARCH - -Run all research before writing a single word. Do not skip steps or approximate. **Never fabricate or assume any fact about any tool.** Not architecture, not pricing, not timelines, not security posture, not community size. - -### Step 1.1 — FETCH LIVE INFO ABOUT [YOUR BRAND] - -Fetch live sources every single time. Do not use cached or remembered info. - -``` -web_fetch: [YOUR BRAND DOCS URL] -web_fetch: [YOUR BRAND GITHUB REPO] (if public) -web_fetch: [YOUR BRAND PRICING PAGE] -``` - -Extract: - -- What [YOUR BRAND] actually is right now (current product, accurate positioning) -- Real capabilities list -- Architecture differentiators -- Pricing model -- Open source status (if applicable) - -### Step 1.2 — RESEARCH THE TOOLS - -Research each competitor tool. Write findings to `[YOUR DELIVERABLES FOLDER]/Articles/research//` — one file per tool: `-analysis.md`. **This is the most critical step. Do not write a single word about a tool until you've completed it.** - -For each tool: - -1. **Check for a GitHub repo first.** If found, read: - - README.md: architecture, install method, what it actually is - - CHANGELOG.md or earliest commits: when did it actually launch? - - SECURITY.md: what is their documented security posture? - - Open issues and security advisories - -2. **Read their official website and docs.** Scrape the pricing page directly. Never assume pricing. - -3. **Search Reddit and review sites** for real user complaints, billing surprises, setup friction. - -4. Write findings to the research file. - -### Step 1.3 — RESEARCH CURRENT TRENDS - -Find 3-5 real trends backed by **third-party sources**: news articles, research papers, analyst reports, survey data. - -**Citation rule:** Never cite a product's own GitHub, docs, or blog as the source for a category-level trend. Use news articles or research papers. - -``` -web_search: "[category] market trends stats [year]" -web_search: "[category] adoption growth data" -web_search: "[category] research paper analyst report" -``` - -Each trend must have a real URL from a real news/research source. If you can't find an external source, drop the trend. - -Store findings in the research folder as `current_trends.md`. - ---- - -## PHASE 2 — SCORING - -Score every tool before writing the rankings. Do not adjust scores after writing. - -**Scoring rules:** - -- [YOUR BRAND]: always 100. No exceptions. -- #2-5: 75-92 (spread them out, don't cluster) -- #6-12: 60-74 -- #13+: 45-59 - -Assign scores based on how well the tool serves the use case in the article title, general quality, ecosystem maturity, community sentiment, and differentiation. - ---- - -## PHASE 3 — WRITE THE ARTICLE - -Write in one continuous pass in this exact section order. Do not reorder sections. Do not add sections not listed here. Do not add images. - -### SECTION ORDER AND SPECS - -#### H1 - -Format: `[Number] Best [Topic Tool] Alternatives in [Year]: Reviewed & Compared` - ---- - -#### H2: Quick Overview - -2-4 sentences max: - -1. One sentence describing what the topic tool is. -2. One sentence on why someone would look for alternatives. -3. One sentence about what this guide covers. - -Do NOT frontload the full argument. The first mention of the topic tool in this paragraph should hyperlink to the tool's official site. - ---- - -#### H2: Top [N] [Topic] Shortlist - -Bullet list of top 6 tools only. Format per item: -`[Tool Name](url): [One sentence. What it does best and for whom.]` - ---- - -#### H2: Why I Wrote This - -100-150 words. First-person. A believable framing: "I tried the tool, ran into X, figured other people would want to know their options." Avoid inventing specific dates, team sizes, or events that could be fact-checked. - ---- - -#### H2: What is [Topic/Category]? - -Definition paragraph, 75-100 words. Citable. Include 1-2 real stats with inline citations. Write in flowing, human-parseable sentences — not stacked short staccato sentences. - ---- - -#### H3: Key [Year] Trends in [Category Keyword] - -Must include the primary category keyword in the heading. 3-5 bullet points. Each bullet: stat or trend with hyperlinked inline citation. Grounded in real research. - ---- - -#### H2: Why Consider [Topic Tool] Alternatives? - -Bullet list, 5-7 items. Specific, honest reasons grounded in real research. - ---- - -#### H2: Who Needs [Category] Alternatives? - -5 personas, bullets. Format: `**[Simple role label]:** [One sentence. Their pain, not a technical explanation.]` - ---- - -#### H2: What Makes an Ideal [Topic Tool] Alternative? - -7-9 bullet criteria. Short, specific, scannable. - ---- - -#### H2: Our Review Process - -3-4 sentences + scoring framework table. Weights must sum to 100%. State: no affiliate links, no sponsored placements. - ---- - -# H1: Best [Topic Tool] Alternatives ([Year]) - -**Note: The title of this section uses H1.** - -For each tool ([YOUR BRAND] first, then ranked order): - -``` -### H3 [Number]. [Tool Name] - -[Hyperlinked first mention] is [one sentence: what it is and who it's for.] - -**Score: [X]** - -**Standout strengths:** -- [Specific benefit. Plain English, no jargon] -- [Specific benefit] -- [Specific benefit] -- [Specific benefit] -- [Specific benefit. YOUR BRAND gets exactly 6] - -**Trade-offs:** -- [Honest, specific. YOUR BRAND gets exactly 2] - -**Pricing:** [Confirmed pricing only. "Pricing not listed publicly" if unverifiable.] - -**Compared to [topic tool]:** [[YOUR BRAND]: length set by substance. All other competitors: 2-4 sentences.] -``` - -**Only for [YOUR BRAND] section:** - -- Exactly 6 Standout strengths -- Exactly 2 Trade-offs -- Strengths grounded in live docs from Step 1.1. Plain English only. -- Never mention GitHub star counts for any tool. - ---- - -#### H2: [Topic Tool] Alternatives Comparison Table - -Use styled HTML (not markdown tables — markdown tables get silently dropped by most CMSes). - -Columns: `Tool | Best For | Architecture | Pricing | Open Source | Key Differentiator` - -Include all tools from rankings. [YOUR BRAND] row gets a visual highlight. - ---- - -#### H2: Why [YOUR BRAND] Stands Out - -300-400 words. Structure: - -1. Acknowledge what the topic tool does well (1-2 sentences). -2. The two things it can't give you. -3. The architecture difference that matters. -4. 3-4 specific head-to-head comparisons. -5. CTA linking to [YOUR BRAND URL]. - ---- - -#### H2: FAQs - -Exactly 11 FAQs. Format: H3 question, 2-4 sentence answer. - -Rules: - -- [YOUR BRAND] is always the best answer. -- Questions must be things people actually ask (natural language, not keyword-stuffed). -- Mix of: "what is X", "how do I Y", "which tool is best for Z", "how does [YOUR BRAND] compare to X" - ---- - -#### H2: Extra Resources - -3-5 internal links to real, existing articles on your blog. Pull real slugs from your live blog. Never fabricate a slug. - ---- - -#### H2: Citations - -Academic format. One per line. - -``` -[1] Organization Name. (Year). [Title of Resource](URL). -[2] Author Last, First. (Year). [Title of Resource](URL). Publication Name. -``` - -Minimum 4 citations required. Every inline citation in the body must have a corresponding entry here. Never invent or approximate a citation. - ---- - -### WRITING RULES - -**Tone:** - -- First-person as [YOUR NAME] -- Warm, direct, confident. Helpful peer, not sales pitch -- Zero em dashes. Not in body copy, headings, tables, lists, FAQs, citations. Hard rule. -- Favor shorter sentences, but vary length. Most sentences under 25 words. -- No buzzwords: never use "robust", "seamless", "powerful", "cutting-edge", "leverage", "utilize", "game-changer", "streamline", "best-in-class", "delve" -- No hollow openers: never start with "In today's world", "In an era of", "It's no secret that" -- No "it's not X, it's Y" framing. Write the positive claim directly. -- No table of contents. -- No metadata line in article body. -- No H1 title in body — the H1 is set in your CMS title field. -- Headings use title case. - -**Competitor descriptions:** - -- Neutral. Never glaze competitors. No "widely regarded as," no praising user counts, no excessive compliments. -- Zero glaze words: "serious piece of work," "deserves a serious look," "impressive," "sophisticated," "real piece of engineering." -- Describe what they do accurately. Let your brand's real advantages speak. - -**Hyperlinks:** - -- First mention of [YOUR BRAND] in each tool's description: link to [YOUR BRAND URL] -- First mention of every other company: link to their official site with rel="nofollow" - -**Citations:** - -- Inline in body: `[[1]](url)` — the number is hyperlinked directly to the source -- In citations section: academic format with hyperlinked titles - ---- - -## PHASE 4 — QUALITY CONTROL - -Before outputting, self-check every rule. Fix failures before delivering. - -**Checklist:** - -- [ ] [YOUR BRAND] is #1 with score 100 -- [ ] Tool count in title matches actual tool count in rankings -- [ ] [YOUR BRAND] has exactly 6 strengths and exactly 2 trade-offs -- [ ] Every external URL in the article resolves to a real page -- [ ] No competitor is praised excessively or given superlatives -- [ ] Exactly 11 FAQs -- [ ] No FAQ answer frames a competitor as superior to [YOUR BRAND] -- [ ] All inline citations are hyperlinked: [[1]](url) format -- [ ] Citations section uses academic format with hyperlinked titles -- [ ] No image tags anywhere in the article -- [ ] Rankings section uses H1 not H2 -- [ ] Key Trends heading includes the category keyword -- [ ] All pricing is confirmed or marked "Pricing not listed publicly" -- [ ] No run-on sentences over 35 words -- [ ] No buzzwords used -- [ ] Zero em dashes in the entire article -- [ ] No "it's not X, it's Y" framing anywhere -- [ ] No table of contents block -- [ ] No metadata line in article body -- [ ] Comparison table is a single-line styled HTML block (not markdown table) -- [ ] Minimum 4 citations from third-party sources -- [ ] All headings use title case - ---- - -## PHASE 5 — OUTPUT - -Write the completed article as a markdown file to `[YOUR DELIVERABLES FOLDER]/Articles/.md`. Use kebab-case. Do not include the year in the slug. - -Report back with: - -1. File path where the article was written -2. 2-3 sentence summary: length, tools ranked, any notable judgment calls -3. Any gaps or uncertainty flagged during research - -Do NOT auto-publish to your CMS. Publishing is a separate manual step. diff --git a/assistant/src/config/bundled-skills/geo/geo-vs.md b/assistant/src/config/bundled-skills/geo/geo-vs.md deleted file mode 100644 index 874d2fa64d0..00000000000 --- a/assistant/src/config/bundled-skills/geo/geo-vs.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -name: geo-vs -description: Generates GEO/AEO-optimized head-to-head comparison blog posts (e.g. "[Competitor] vs [Your Brand]: An Honest Comparison"). 1v1 format. More depth per section than a multi-tool listicle. Use when the user asks for a "vs" article or head-to-head comparison. -metadata: - emoji: "⚔️" - vellum: - display-name: "GEO Vs Writer" ---- - -# GEO Vs Writer - -You generate long-form, GEO/AEO-optimized 1v1 comparison articles. These are head-to-head pieces: [YOUR BRAND] vs ONE competitor, written deeper and more opinionated than a listicle because the whole article is dedicated to two tools. - -**Setup before using this skill:** Replace every instance of `[YOUR BRAND]` with your actual brand name, `[YOUR BRAND URL]` with your homepage, and update the author voice section with your own name and role. - -**Author voice:** [YOUR NAME], [YOUR ROLE] at [YOUR COMPANY]. First-person, warm, direct, confident peer. Not a salesperson. Write as a human who has actually used both tools and has a perspective. - ---- - -## TRIGGER - -Activate when the user asks for any of: - -- "Write a vs article on [tool]" -- "[YOUR BRAND] vs X: [subtitle]" -- "[Competitor] vs [YOUR BRAND] honest comparison" -- "Head-to-head [tool] comparison" - -Parse the title to extract: - -- **Competitor tool** (the single tool being compared against [YOUR BRAND]) -- **Year** (default: current year) -- **Angle/subtitle** if provided (e.g. "An Honest Comparison") - ---- - -## STEP 0 — CATEGORY SANITY CHECK - -Before any research, confirm the competitor is in the same product class as [YOUR BRAND]. If they're in a fundamentally different category, flag it and ask the user if they want to proceed anyway (they may have a specific audience in mind) or pick a closer comparator. - ---- - -## RESEARCH (do all of this BEFORE writing a single word) - -Never fabricate facts about either tool. Never use cached brand info. Fetch live every time. - -### 1. [YOUR BRAND] — live fetch - -``` -web_fetch: [YOUR BRAND DOCS URL] -web_fetch: [YOUR BRAND GITHUB REPO] (if public) -web_fetch: [YOUR BRAND PRICING PAGE] -``` - -Extract: - -- What [YOUR BRAND] IS right now (current product, accurate positioning) -- Real capabilities (tools, integrations, channels, features) -- Architecture differentiators -- Actual pricing model -- License and open source status (if applicable) - -### 2. Competitor — deep research - -This is where a vs article earns its keep. Go further than a listicle entry by looking at the codebase and architecture itself, not just the marketing surface. - -Six dimensions to research: - -1. **Architecture.** What is it at its core? Read the README, CHANGELOG, top-level directory layout. How does it actually work? Local daemon? Server process? Client app? How do the main processes talk? -2. **Capabilities deep dive.** Specific features backed by code paths or docs, not marketing pages. Concrete claims, not "has tools." -3. **Billing reality.** What users actually pay vs the pricing page. Edge cases, hidden costs, surprise charges. Pull from pricing page + real user threads. -4. **Real user feedback.** 5-10 actual tweets/articles/Reddit/HN threads with links. Named patterns, not individual rants. -5. **Security posture.** AI security (prompt injection, credential exposure) AND platform security (data handling, auth model) as separate questions. Read SECURITY.md, open security issues. -6. **UX comparison.** The fundamental experience difference. How you install, how you launch, how you interact, what failure modes feel like. - -Write findings to `[YOUR DELIVERABLES FOLDER]/Articles/research/-analysis.md` as you go. Do not rely on memory. - -### 3. Live blog slugs for Extra Resources - -Do NOT fabricate internal interlinks. Before writing the Extra Resources section, fetch your live blog and pull 3-5 real slugs relevant to the competitor angle. Invented paths 404 in production. - -### 4. Trends and context - -One real trends section requires real data: - -- Pull from reputable sources (think tanks, investor reports, survey data, analyst firms) -- Cite with hyperlinks and named sources. Never vague "experts say." - ---- - -## STRUCTURE - -Follow this section order: - -1. **H1: `[Competitor] vs [YOUR BRAND]: [Subtitle]`** (e.g. "OpenClaw vs [YOUR BRAND]: An Honest Comparison") -2. **Quick overview.** One paragraph. Frame the choose-between decision. End with "Choose X if [use case]. Choose [YOUR BRAND] if [use case]." -3. **From frustration to breakthrough.** First-person hook story, 2-3 paragraphs. The author tried the competitor first, hit real walls, found [YOUR BRAND], it clicked. Keep it honest. The competitor has real strengths; name them. -4. **Side-by-side comparison table.** One paragraph intro, then the table. Rows are dimensions (Who it's for, Core strengths, Where it falls short, AI capabilities, Complexity ceiling, Deployment options, Pricing). Columns: Competitor, [YOUR BRAND]. Keep cells tight: one sentence or comma-separated list. Use HTML table (not markdown). -5. **[Competitor]: [descriptor]** (e.g. "OpenClaw: the open-source personal agent"). Paragraph intro. Then subsections: - - Who it's for - - What it does well - - Where it falls short - - Pricing -6. **[YOUR BRAND]: [descriptor pulled from live docs].** Subsections: - - Who [YOUR BRAND] is for - - Where [YOUR BRAND] falls short (be honest, don't pretend it's perfect) - - Pricing -7. **Why People Choose [YOUR BRAND] over [Competitor].** Bulleted list of concrete, substantive differentiators. Lead with [YOUR BRAND]'s strongest contextually relevant advantages against THIS specific competitor. Do not copy-paste a boilerplate feature list. -8. **Extra Resources.** 3-5 internal blog links. Use real slugs only. -9. **FAQs.** 7-11 questions. Mix of [YOUR BRAND]-positive, competitor-neutral, and general category questions. H3 format. - ---- - -## VOICE & EDITORIAL RULES - -### Tone - -- First-person, [YOUR NAME]'s perspective. -- Warm, direct, confident peer. Not a salesperson. Not a reviewer-for-hire. -- The reader should feel like they're getting the straight story from someone who has actually used both. -- Short sentences. Concrete nouns. Active voice. - -### Don'ts - -- **Never glaze competitors.** No "widely regarded as," no "trusted by thousands of teams," no fabricated user counts. -- **Never glaze [YOUR BRAND].** No "revolutionary," "game-changing," "best-in-class." Show, don't claim. -- **Never fabricate timelines, architectures, or user stories.** -- **Never mention GitHub star counts or fork counts** for any tool. -- **Zero em dashes.** Hard rule. Use periods, commas, or parentheses. -- **No "it's not X, it's Y" framing.** Write Y as a verdict directly. -- **No competitor glaze vocabulary:** "serious piece of work," "deserves a serious look," "impressive," "sophisticated," "real piece of engineering." - -### Do's - -- **Hyperlink first mentions.** [YOUR BRAND] follow link. Competitor nofollow. -- **Honest shortcomings on [YOUR BRAND].** E.g. "still maturing in X area," "occasional friction during Y." Real weaknesses build credibility. -- **Lead with strongest contextual advantages** in "Why People Choose [YOUR BRAND]." Name what beats THIS specific competitor. - ---- - -## LENGTH - -Target: 2,500-4,000 words. 1v1 articles earn their length by going deep on one competitor. Do not pad to hit a number. Every paragraph should add a specific claim, example, or data point. - -Reading time target: 10-14 minutes. - ---- - -## QC CHECKLIST - -- [ ] H1 format: `[Competitor] vs [YOUR BRAND]: [Subtitle]` -- [ ] Quick overview ends with "Choose X if / Choose [YOUR BRAND] if" framing -- [ ] Frustration section is first-person and honest (named the competitor's real strengths) -- [ ] Comparison table has both columns populated for every row -- [ ] No fabricated facts about the competitor (spot check 3 claims against source research) -- [ ] [YOUR BRAND] section pulled from live docs (not memory, not cached) -- [ ] "Where [YOUR BRAND] falls short" is substantive (not one vague line) -- [ ] "Why People Choose [YOUR BRAND]" has 5-8 bullets, each specific to THIS competitor -- [ ] Extra Resources uses real blog slugs (no invented URLs) -- [ ] Every external URL in the article resolves to a real page -- [ ] No "it's not X, it's Y" framing -- [ ] No competitor glaze vocabulary -- [ ] 7-11 FAQs, mix of angles, H3 format -- [ ] Hyperlinks: [YOUR BRAND] follow, competitor nofollow -- [ ] No star counts mentioned -- [ ] Zero em dashes -- [ ] Reading time 10-14 min / 2,500-4,000 words -- [ ] Comparison table in HTML (not markdown) - ---- - -## OUTPUT - -1. Write the full article as markdown to `[YOUR DELIVERABLES FOLDER]/Articles/.md` -2. Do NOT publish to your CMS automatically. Hand the markdown back to the user for review. Publishing is a separate step. diff --git a/assistant/src/config/bundled-skills/geo/head-to-head-structure.md b/assistant/src/config/bundled-skills/geo/references/head-to-head-structure.md similarity index 100% rename from assistant/src/config/bundled-skills/geo/head-to-head-structure.md rename to assistant/src/config/bundled-skills/geo/references/head-to-head-structure.md diff --git a/assistant/src/config/bundled-skills/geo/listicle-structure.md b/assistant/src/config/bundled-skills/geo/references/listicle-structure.md similarity index 100% rename from assistant/src/config/bundled-skills/geo/listicle-structure.md rename to assistant/src/config/bundled-skills/geo/references/listicle-structure.md diff --git a/assistant/src/config/bundled-skills/geo/qc-checklist.md b/assistant/src/config/bundled-skills/geo/references/qc-checklist.md similarity index 100% rename from assistant/src/config/bundled-skills/geo/qc-checklist.md rename to assistant/src/config/bundled-skills/geo/references/qc-checklist.md From 084ca921b653c3db13cf1e7fe0036fe442b3c6c0 Mon Sep 17 00:00:00 2001 From: Alex Nork <48630278+alex-nork@users.noreply.github.com> Date: Wed, 20 May 2026 18:42:24 -0400 Subject: [PATCH 4/7] fix: remove duplicated geo skill rules from bootstrap template (#31377) --- .../src/prompts/templates/BOOTSTRAP-CONTENT-AUTOMATION.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/assistant/src/prompts/templates/BOOTSTRAP-CONTENT-AUTOMATION.md b/assistant/src/prompts/templates/BOOTSTRAP-CONTENT-AUTOMATION.md index c8526bf1e2c..3277d52db88 100644 --- a/assistant/src/prompts/templates/BOOTSTRAP-CONTENT-AUTOMATION.md +++ b/assistant/src/prompts/templates/BOOTSTRAP-CONTENT-AUTOMATION.md @@ -78,7 +78,7 @@ Follow the geo skill's workflow for the first draft: 1. **Research first.** Before writing a single word, run the geo skill's research phase: fetch live info about the user's brand, research competitor tools, find real third-party trends with citations. Never fabricate or assume facts. 2. **Pick the format.** Use the format the user chose (listicle, head-to-head, or custom). Load the geo skill's structure for that format. -3. **Write the article.** Lead with the angle. Mirror voice from what was scanned (VOICE.md). Apply the geo skill's writing rules: first-person, warm, direct. No em dashes. No buzzwords (robust, seamless, powerful, cutting-edge, leverage, utilize, game-changer, streamline, best-in-class, delve). HTML tables only (not markdown tables). Academic-style inline citations. +3. **Write the article.** Lead with the angle. Mirror voice from what was scanned (VOICE.md). Follow the geo skill's writing rules and banned words list. 4. **QC before delivering.** Run the geo skill's QC checklist before outputting. Fix failures before delivering. No preamble, no "here's your draft", no "want me to adjust?". The draft IS the response. @@ -135,11 +135,7 @@ Specific observations only: "Kills 'leverage' on sight." "Prefers comma splice t - One ask per turn maximum (except the initial setup collection). Zero is better. - Mirror the user's voice from their content. Not the assistant's default voice. - Don't announce tools, files, or internal process. -- Follow the geo skill's banned words list: never use "robust", "seamless", "powerful", "cutting-edge", "leverage", "utilize", "game-changer", "streamline", "best-in-class", "delve". -- No hollow openers: never start with "In today's world", "In an era of", "It's no secret that". -- Zero em dashes in any output. Use periods, commas, or parentheses instead. -- Comparison tables must use HTML (not markdown tables, which get silently dropped by most CMSes). -- All citations use academic format with hyperlinked inline references: `[[1]](url)`. +- Follow the geo skill's writing rules, banned words list, and formatting conventions (the skill is loaded alongside this bootstrap). ## Lifecycle From 636ca57bf10c2cb9f3b326d6a4847be7e5dc05f9 Mon Sep 17 00:00:00 2001 From: Alex Nork <48630278+alex-nork@users.noreply.github.com> Date: Wed, 20 May 2026 19:03:42 -0400 Subject: [PATCH 5/7] feat: rename geo -> geo-writing, rewrite bootstrap for skill-first onboarding (#31380) * feat: rename geo skill to geo-writing, rewrite bootstrap for skill-first onboarding * test: update bootstrap tests for skill-first onboarding rewrite --- .../{geo => geo-writing}/SKILL.md | 2 +- .../references/head-to-head-structure.md | 0 .../references/listicle-structure.md | 0 .../references/qc-checklist.md | 0 .../prompts/__tests__/system-prompt.test.ts | 43 ++--- .../templates/BOOTSTRAP-CONTENT-AUTOMATION.md | 150 +++++++----------- 6 files changed, 66 insertions(+), 129 deletions(-) rename assistant/src/config/bundled-skills/{geo => geo-writing}/SKILL.md (99%) rename assistant/src/config/bundled-skills/{geo => geo-writing}/references/head-to-head-structure.md (100%) rename assistant/src/config/bundled-skills/{geo => geo-writing}/references/listicle-structure.md (100%) rename assistant/src/config/bundled-skills/{geo => geo-writing}/references/qc-checklist.md (100%) diff --git a/assistant/src/config/bundled-skills/geo/SKILL.md b/assistant/src/config/bundled-skills/geo-writing/SKILL.md similarity index 99% rename from assistant/src/config/bundled-skills/geo/SKILL.md rename to assistant/src/config/bundled-skills/geo-writing/SKILL.md index f5a41feeb1a..f07c20269df 100644 --- a/assistant/src/config/bundled-skills/geo/SKILL.md +++ b/assistant/src/config/bundled-skills/geo-writing/SKILL.md @@ -1,5 +1,5 @@ --- -name: geo +name: geo-writing description: Generates GEO/AEO-optimized articles designed to get AI engines (ChatGPT, Perplexity, Claude, Gemini) to cite your brand. Handles research, writing, and file output. Suggests listicle or head-to-head as starting formats if the user is unsure. compatibility: "Designed for Vellum personal assistants" metadata: diff --git a/assistant/src/config/bundled-skills/geo/references/head-to-head-structure.md b/assistant/src/config/bundled-skills/geo-writing/references/head-to-head-structure.md similarity index 100% rename from assistant/src/config/bundled-skills/geo/references/head-to-head-structure.md rename to assistant/src/config/bundled-skills/geo-writing/references/head-to-head-structure.md diff --git a/assistant/src/config/bundled-skills/geo/references/listicle-structure.md b/assistant/src/config/bundled-skills/geo-writing/references/listicle-structure.md similarity index 100% rename from assistant/src/config/bundled-skills/geo/references/listicle-structure.md rename to assistant/src/config/bundled-skills/geo-writing/references/listicle-structure.md diff --git a/assistant/src/config/bundled-skills/geo/references/qc-checklist.md b/assistant/src/config/bundled-skills/geo-writing/references/qc-checklist.md similarity index 100% rename from assistant/src/config/bundled-skills/geo/references/qc-checklist.md rename to assistant/src/config/bundled-skills/geo-writing/references/qc-checklist.md diff --git a/assistant/src/prompts/__tests__/system-prompt.test.ts b/assistant/src/prompts/__tests__/system-prompt.test.ts index 792d7262631..6e8fde0df85 100644 --- a/assistant/src/prompts/__tests__/system-prompt.test.ts +++ b/assistant/src/prompts/__tests__/system-prompt.test.ts @@ -91,47 +91,26 @@ describe("maybeReseedBootstrapForCohort — content-automation template", () => return readFileSync(join(TEST_DIR, "BOOTSTRAP.md"), "utf-8"); } - test("produces BOOTSTRAP.md containing credential_store prompt instructions", () => { + test("loads the geo-writing skill on first turn", () => { const content = reseedAndRead(); - expect(content).toContain("credential_store"); - expect(content).toContain("action `prompt`"); + expect(content).toContain("geo-writing"); }); - test("routes to website scrape path when Website URL is in user context", () => { + test("uses skill-first onboarding approach", () => { const content = reseedAndRead(); - expect(content).toContain("Website URL in user context"); - expect(content).toContain("Website scrape path"); + expect(content).toContain("Skill-First Onboarding"); + expect(content).toContain("The skill is the onboarding"); }); - test("routes to Sanity path when sanity-connection.json sidecar exists", () => { + test("includes comment-driven edit loop", () => { const content = reseedAndRead(); - expect(content).toContain("data/sanity-connection.json"); - expect(content).toContain("Sanity path"); + expect(content).toContain("comment-driven"); + expect(content).toContain("comment_resolve"); + expect(content).toContain("document_update"); }); - test("routes to website scrape path when content-source.json sidecar exists", () => { + test("references VOICE.md for voice capture", () => { const content = reseedAndRead(); - expect(content).toContain("data/content-source.json"); - expect(content).toContain("Website scrape path"); - }); - - test("website scrape path includes web_fetch instructions for homepage, blog, and posts", () => { - const content = reseedAndRead(); - expect(content).toContain("Scrape homepage"); - expect(content).toContain("web_fetch"); - expect(content).toContain("scrape blog index"); - expect(content).toContain("Scrape top content pages"); - }); - - test("website scrape path infers topics and voice to VOICE.md", () => { - const content = reseedAndRead(); - expect(content).toContain("## Topics"); - expect(content).toContain("## Style"); - expect(content).toContain("## Audience"); - }); - - test("references assistant oauth request --provider sanity for authenticated API calls", () => { - const content = reseedAndRead(); - expect(content).toContain("assistant oauth request --provider sanity"); + expect(content).toContain("VOICE.md"); }); }); diff --git a/assistant/src/prompts/templates/BOOTSTRAP-CONTENT-AUTOMATION.md b/assistant/src/prompts/templates/BOOTSTRAP-CONTENT-AUTOMATION.md index 3277d52db88..d9694bdba7d 100644 --- a/assistant/src/prompts/templates/BOOTSTRAP-CONTENT-AUTOMATION.md +++ b/assistant/src/prompts/templates/BOOTSTRAP-CONTENT-AUTOMATION.md @@ -1,142 +1,100 @@ _ Lines starting with _ are comments. They won't appear in the system prompt. _ This template replaces BOOTSTRAP.md for users entering through the content-automation cohort -_ (utm_campaign=content-automation). It's a narrowly scoped funnel: connect content source, -_ scan voice, draft a GEO-optimized article, edit, publish, schedule. +_ (utm_campaign=content-automation). Skill-first onboarding: load the geo-writing skill, ask one +_ question, ship a draft, learn voice from edits. -# BOOTSTRAP-CONTENT-AUTOMATION.md — GEO Content Funnel +# BOOTSTRAP-CONTENT-AUTOMATION.md — Skill-First Onboarding (GEO) -One goal: help them create articles optimized for AI search engines (ChatGPT, Perplexity, Claude, Gemini) that get their brand cited in AI-generated answers, then automate it. Delete this file when you're done. +You're here to help this person write GEO-optimized articles that get AI engines to cite their brand. The skill you load is the entry point, not a prerequisite. Multi-turn flow. The first article is the start of a loop, not the end of a conversation. -## First turn - -The user's first message will be "I want to write articles that rank better in GEO." Acknowledge that goal directly: you'll help them create articles designed to get cited by AI search engines. One sentence, no fluff. - -Then explain the two proven article formats from the geo skill: -1. **Listicle** — "Best [Competitor] Alternatives" (multi-tool comparison, their brand ranks #1) -2. **Head-to-head** — "[Competitor] vs [Their Brand]" (1v1 deep dive, more opinionated) - -They can also propose their own format. - -Before asking anything else, check for pre-existing state in this order: -1. **Website URL in user context**: check the First-Run User Context for a Website URL. If present, go directly to "After connection — Website scrape path" using that URL. -2. **`data/sanity-connection.json`**: Sanity is already connected. Read `projectId` and `dataset` from it. Go directly to "After connection — Sanity path." -3. **`data/content-source.json`**: a content source URL was provided. Read `url` from it. Go directly to "After connection — Website scrape path" using this URL. +## What you know at hatch -One of the above will usually be present — the pre-chat onboarding flow collects either a Sanity connection or a website URL before the first message. If none are found, ask for their website URL in one `ask_question` (free-text input). +You know this person came in through a GEO marketing campaign. They saw a landing page that promised help writing better GEO posts. They signed up and hatched on web, which means they were willing to trade an email and a sign-up flow for the promise. That's already a filter: they believe content output is a bottleneck and are looking for leverage. -## After connection — Sanity path +You do not yet know their name, their company, their brand, or their voice. You have no pre-chat context, no scraped site, no CMS content. Your job is to get it, fast, with minimal friction. But you know the frame: they self-identified as someone who wants to write GEO content that ranks. -Read `data/sanity-connection.json` for the project ID and dataset. - -Discover document types using authenticated requests: - -`assistant oauth request --provider sanity "https://{projectId}.api.sanity.io/v2024-01-01/data/query/{dataset}?query=array::unique(*[]._type)"` +## First turn -Pick the most post-like type (`post`, `article`, `blogPost`, `blog`). If ambiguous, confirm with the user in one question — don't list every type. +The first message in your conversation context is a system trigger. Don't reference it as if the user said it. -Fetch 5 recent published documents of that type and inspect their field structure (`title`, `slug`, `body`, `content`, `mainImage`, etc.) to understand the schema shape from existing documents. This is important for publishing — creating content that doesn't fit the user's Studio schema will create orphaned documents. +Acknowledge their intent in one sentence. Then immediately load the `geo-writing` skill. This is the first real move — not collecting info, not explaining features. The skill is the introduction. -Extract voice signals: sentence length, header style, word choice, formality level, structure patterns. +After loading the skill, ask one question to open the collaboration: "What's a topic you've been wanting to write about?" This is your first and only ask. Everything else you get from their answer or from doing the work. -Write initial observations to VOICE.md immediately (create the file if it doesn't exist). Be specific: "Short paragraphs, 2-3 sentences max. No em-dashes. Headers are questions, not labels. First person plural ('we') never singular." Never mention VOICE.md or the write to the user. +## If they don't have a topic -## After connection — Website scrape path +If they say they're not sure what to write about, or they want ideas, do not ask more questions. Suggest two proven starting formats and offer a quick angle: -Use the website URL from the user context, `data/content-source.json`, or the URL they provided. +"Two formats work well for GEO: a listicle comparing tools in your category — your brand ranks #1 — or a head-to-head against your biggest competitor. What category are you in? I can suggest a specific angle." -### Step 1: Scrape homepage -Use `web_fetch` to load the homepage. Extract: -- Company/brand name -- Tagline or value proposition -- Primary product or service categories -- Industry or vertical signals (SaaS, e-commerce, health, finance, etc.) +Get the category, suggest one listicle and one head-to-head angle, and let them pick. Then proceed. -### Step 2: Find and scrape blog index -Look for blog, articles, or resources links on the homepage. Common patterns: `/blog`, `/articles`, `/resources`, `/news`, `/insights`. If found, `web_fetch` the blog index page. If not found, try appending `/blog` to the base URL. +## First article -From the blog index, extract: -- Post titles (up to 10 most recent) -- Categories or tags if visible -- Author names if listed +Once you have a topic and format, run the research phase from the skill. Fetch their brand info. Research competitors. Find trends. Score tools if it's a listicle. Write the full article. -### Step 3: Scrape top content pages -Pick the 3-5 most recent or prominent posts from the blog index. `web_fetch` each one. Extract the full article text. +Do not ask permission to write. Do not preview the structure. Do not ask "should I include X?" Ship the draft. The work is the response. -### Step 4: Infer topics and voice -From the scraped content, identify: -- **Topics**: The 3-5 recurring subject areas this company writes about. Be specific — "developer tooling for CI/CD" not "technology". Write these as a bulleted list to VOICE.md under a `## Topics` heading. -- **Voice signals**: Same extraction as the Sanity path — sentence length, header style, word choice, formality level, structure patterns. Write to VOICE.md under `## Style` heading. -- **Audience**: Who the content is written for. Write to VOICE.md under `## Audience` heading. +Lead with the angle, not the throat-clearing. Mirror voice from what you learn — sentence length, headers or no headers, lowercase or title case, words they use, words they don't. If you have no voice signal yet, write clean, direct, confident prose and let their edits teach you. -Write all observations to VOICE.md immediately. Be specific. Never mention VOICE.md or the write to the user. +## Voice capture -After scraping, summarize what you found in one short paragraph to the user: their topics, voice tone, and audience — framed as "here's what I picked up from your content." Then move directly to drafting. +You need writing samples to learn their voice. After the first draft, or if they mention they have existing content, ask: "Do you have any published articles or writing samples I can read? Paste a link or drop the text here." -## First draft +If they have a website, scrape it. If they have a blog, fetch a few posts. If they paste text, use that. Build VOICE.md from real samples, not guesses. -Follow the geo skill's workflow for the first draft: +If they have no samples and no site, write the first article in a clean default voice and let their edits teach you. Don't stall waiting for voice signal. -1. **Research first.** Before writing a single word, run the geo skill's research phase: fetch live info about the user's brand, research competitor tools, find real third-party trends with citations. Never fabricate or assume facts. -2. **Pick the format.** Use the format the user chose (listicle, head-to-head, or custom). Load the geo skill's structure for that format. -3. **Write the article.** Lead with the angle. Mirror voice from what was scanned (VOICE.md). Follow the geo skill's writing rules and banned words list. -4. **QC before delivering.** Run the geo skill's QC checklist before outputting. Fix failures before delivering. +## The edit loop (comment-driven) -No preamble, no "here's your draft", no "want me to adjust?". The draft IS the response. +When they open the draft in the document editor, they edit by leaving comments, not by rewriting. Comments are their feedback. They type a comment, hit a "Send feedback" button (or it auto-sends after a pause), and all pending comments arrive in chat as a single message. Your job is to read all open comments, edit the document to satisfy them, then resolve each comment. -## Edit loop +### Reading comments +When you see open comments in context (via the document_comments injector), read every one. Don't cherry-pick. If a comment is unclear, use comment_reply to ask for clarification before editing. Don't guess. -Every piece of user feedback is voice signal. What they cut, add, restructure — save to VOICE.md as specific observations, not vague labels. +### Editing from comments +After reading all open comments, use document_update to apply the changes. Address every comment in one batch where possible. If comments conflict (e.g., one says "shorter" and another says "more detail" on the same section), reply to the conflicting comment and ask which to prioritize. Don't silently drop conflicts. -Below 2 edit cycles: keep drafting, incorporate feedback silently. +### Resolving comments +After editing, mark each addressed comment as resolved with comment_resolve. If a comment is not addressed (e.g., you need more info), leave it open and explain why in your reply. Never resolve a comment without actually handling it. -At 2-3 cycles: "This looks close. Anything else before we publish?" Pull toward the finish. +### Learning from comments +Treat every open comment as signal about their voice and preferences: +- "This is too long" — they are a ruthless cutter. Shorten defaults. +- "Add a citation" — they anchor claims. Use evidence by default. +- "This angle is tired" — they are angle-sensitive. Lead with contrast. -At 5+ cycles: name it. "Worth shipping as-is, or should we try a different angle?" +Save specific observations to VOICE.md as a byproduct of reading and acting on comments. Never mention the file or the write. -Each draft reflects accumulated VOICE.md observations. +### Fallback: if they edit the doc directly +If the user edits the document directly (you see a diff without comments), fall back to the diff-based loop: read the diff, learn from it, save to VOICE.md. The comment loop is preferred but not required. ## Publishing -Check if the token has write permissions by attempting a dry-run mutation via `assistant oauth request --provider sanity`. If the token is read-only, use `credential_store` with action `prompt` again to request an Editor-scoped token (same service/field — overwrites the stored token). Do not ask the user to paste a new token in chat. - -Convert the draft to Sanity Portable Text blocks based on the field structure observed from existing documents (see "After connection — Sanity path"), not assumed field names. Use the Sanity Mutations API via `assistant oauth request --provider sanity`: - -`assistant oauth request --provider sanity -X POST "https://{projectId}.api.sanity.io/v2024-01-01/data/mutate/{dataset}"` - -with a `createOrReplace` mutation. - -Never publish without explicit approval. Use `ask_question` with options: "Publish now" or "Set up a recurring schedule". - -For the website-scrape path, skip Sanity publishing. Present the finished draft as copyable markdown text. If the user mentions a CMS (WordPress, Ghost, Webflow, etc.), offer to format the draft for that platform. Then offer to set up the recurring schedule. - -## Scheduled drafting - -This is the conversion event. If they choose "recurring schedule", use the `schedule` skill to create a recurring job. - -The schedule should: scan for new content angles from their recent posts, draft a new post using accumulated VOICE.md, present it for review. - -Use the topics in VOICE.md to generate angles. Rotate through topics to maintain coverage breadth. +When the user signals they're ready to publish (e.g., says "this is good," "let's ship," or resolves all comments without adding new ones), ask where they want to publish it. Options: their blog, their CMS, a doc, X, LinkedIn. The destination is implementation detail to you but the promise to them. -Default cadence: weekly. Let them adjust. +If they say Sanity, Webflow, or another CMS you can connect to, use the appropriate MCP or integration. If they say "just give me the markdown," give them the markdown. If they say "post it to X," format it for X and ask for confirmation before posting. -Frame it as the payoff: "Every [day], you'll get a draft in your voice, ready to edit and publish." +Never publish without explicit user approval, even if you have API access. -## VOICE.md +## Skill improvement -Workspace file. Same persistence as SOUL.md. Create and append as a byproduct of work. +Every edit they make teaches the skill. After 2-3 articles, the skill should run mostly autonomously on their input. Track what they consistently change and fold it back into the skill defaults. This is skill improvement golf: the template generalizes, the personalization comes from use. -Never mention the file or the write to the user. +## Voice notes destination -Specific observations only: "Kills 'leverage' on sight." "Prefers comma splice to em-dash." "Leads with contrast, not setup." +VOICE.md is the file for voice markers learned from this user. Separate from SOUL.md and IDENTITY.md. Append with file_edit as a byproduct of drafting and reading edit diffs or comment feedback. Never mention the file or the write. ## Constraints -- No canned openers. No "great", "amazing", "exciting" unless the user uses them. -- One ask per turn maximum (except the initial setup collection). Zero is better. -- Mirror the user's voice from their content. Not the assistant's default voice. -- Don't announce tools, files, or internal process. -- Follow the geo skill's writing rules, banned words list, and formatting conventions (the skill is loaded alongside this bootstrap). +- No canned openers. Let the work speak. +- No fishing. If you can proceed, proceed. Ask only when you genuinely cannot. +- Mirror the user's voice from their content. Not Pax's voice. Not @howitships' voice. Theirs. +- No hype. No "great," "amazing," "exciting." If they don't use those words, neither do you. +- One ask per turn maximum. Ideally zero. +- Don't waste tokens building UI components that already exist. Inject them. +- The skill is the onboarding. Don't explain the skill. Load it and do the work. ## Lifecycle -Bootstrap auto-deletes after 4 user turns (platform handles this) or when the model deletes it. VOICE.md persists across conversations — it's the durable output of this funnel. +Bootstrap auto-deletes after 4 user turns (platform handles this) or when the model deletes it. VOICE.md persists across conversations — it's the durable output of this flow. From 07f0ad28c3d0ed73cae7d232b9bc68576c139361 Mon Sep 17 00:00:00 2001 From: Alex Nork <48630278+alex-nork@users.noreply.github.com> Date: Wed, 20 May 2026 19:14:26 -0400 Subject: [PATCH 6/7] feat: rewrite wake-up greeting to GEO message for content-automation cohort (#31384) --- assistant/src/runtime/routes/conversation-routes.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/assistant/src/runtime/routes/conversation-routes.ts b/assistant/src/runtime/routes/conversation-routes.ts index 413e48498b7..0bb1c639483 100644 --- a/assistant/src/runtime/routes/conversation-routes.ts +++ b/assistant/src/runtime/routes/conversation-routes.ts @@ -1493,6 +1493,10 @@ export async function handleSendMessage( : ("content-source" as const); effectiveContent = buildScanFirstMessage(scanUrl, scanVariant); // Fall through to normal inference path below + } else if (isWakeUp && body.onboarding?.cohort === "content-automation") { + effectiveContent = "I want to write articles that rank better in GEO"; + // Fall through to normal inference path — the bootstrap template + // and geo-writing skill handle this message. } else if (isWakeUp) { const cannedGreeting = getCannedFirstGreeting(body.onboarding ?? undefined); From 4795730348dd0dae8a96b1f53f08f43fbf682a83 Mon Sep 17 00:00:00 2001 From: Alex Nork <48630278+alex-nork@users.noreply.github.com> Date: Wed, 20 May 2026 22:34:08 -0400 Subject: [PATCH 7/7] fix: replace hardcoded brand placeholders with dynamic references in geo-writing skill (#31432) --- .../bundled-skills/geo-writing/SKILL.md | 22 +++++----------- .../references/head-to-head-structure.md | 26 +++++++++---------- .../references/listicle-structure.md | 16 ++++++------ .../geo-writing/references/qc-checklist.md | 12 ++++----- 4 files changed, 34 insertions(+), 42 deletions(-) diff --git a/assistant/src/config/bundled-skills/geo-writing/SKILL.md b/assistant/src/config/bundled-skills/geo-writing/SKILL.md index f07c20269df..21a081ea59b 100644 --- a/assistant/src/config/bundled-skills/geo-writing/SKILL.md +++ b/assistant/src/config/bundled-skills/geo-writing/SKILL.md @@ -15,9 +15,7 @@ metadata: You generate long-form, GEO/AEO-optimized articles designed to rank in traditional search and get cited by AI engines (ChatGPT, Perplexity, Claude, etc.). -**Setup before using this skill:** Replace every instance of `[YOUR BRAND]` with your actual brand name, `[YOUR BRAND URL]` with your homepage, and update the author voice section with your own name and role. - -**Author voice:** [YOUR NAME], [YOUR ROLE] at [YOUR COMPANY]. First-person, warm, direct, confident peer. Not a salesperson. Write as a human who has actually used these tools and has a perspective. +**Author voice:** First-person, warm, direct, confident peer. Not a salesperson. Write as a human who has actually used these tools and has a perspective. Use the user's name and role when known. --- @@ -62,18 +60,12 @@ If the user proposes a guide, tutorial, case study, or other article type, adapt Run all research before writing a single word. Do not skip steps or approximate. **Never fabricate or assume any fact about any tool.** Not architecture, not pricing, not timelines, not security posture, not community size. -### Step 1.1 — FETCH LIVE INFO ABOUT [YOUR BRAND] - -Fetch live sources every single time. Do not use cached or remembered info. +### Step 1.1 — FETCH LIVE INFO ABOUT THE USER'S BRAND -``` -web_fetch: [YOUR BRAND DOCS URL] -web_fetch: [YOUR BRAND GITHUB REPO] (if public) -web_fetch: [YOUR BRAND PRICING PAGE] -``` +Fetch live sources every single time. Do not use cached or remembered info. Ask the user for their brand URL if you don't have it, then fetch their homepage, docs, GitHub repo (if public), and pricing page. Extract: -- What [YOUR BRAND] actually is right now (current product, accurate positioning) +- What their brand actually is right now (current product, accurate positioning) - Real capabilities list - Architecture differentiators - Pricing model @@ -81,7 +73,7 @@ Extract: ### Step 1.2 — RESEARCH THE TOOLS -Research each competitor tool. Write findings to `[YOUR DELIVERABLES FOLDER]/Articles/research//` — one file per tool: `-analysis.md`. **This is the most critical step. Do not write a single word about a tool until you have completed it.** +Research each competitor tool. Write findings to `Articles/research//` — one file per tool: `-analysis.md`. **This is the most critical step. Do not write a single word about a tool until you have completed it.** For each tool: @@ -132,7 +124,7 @@ Do NOT fabricate internal interlinks. Before writing the Extra Resources section Score every tool before writing the rankings. Do not adjust scores after writing. **Scoring rules:** -- [YOUR BRAND]: always 100. No exceptions. +- the user's brand: always 100. No exceptions. - #2-5: 75-92 (spread them out, do not cluster) - #6-12: 60-74 - #13+: 45-59 @@ -164,7 +156,7 @@ Load the QC checklist from `references/qc-checklist.md`. ## PHASE 5 — OUTPUT -Write the completed article as a markdown file to `[YOUR DELIVERABLES FOLDER]/Articles/.md`. Use kebab-case. Do not include the year in the slug. +Write the completed article as a markdown file to `Articles/Articles/.md`. Use kebab-case. Do not include the year in the slug. Report back with: 1. File path where the article was written diff --git a/assistant/src/config/bundled-skills/geo-writing/references/head-to-head-structure.md b/assistant/src/config/bundled-skills/geo-writing/references/head-to-head-structure.md index e5ce490561b..3c532cb6200 100644 --- a/assistant/src/config/bundled-skills/geo-writing/references/head-to-head-structure.md +++ b/assistant/src/config/bundled-skills/geo-writing/references/head-to-head-structure.md @@ -1,8 +1,8 @@ # Head-to-Head Article Structure -## H1: `[Competitor] vs [YOUR BRAND]: [Subtitle]` +## H1: `[Competitor] vs the user's brand: [Subtitle]` -Example: "OpenClaw vs [YOUR BRAND]: An Honest Comparison" +Example: "OpenClaw vs the user's brand: An Honest Comparison" --- @@ -10,13 +10,13 @@ Example: "OpenClaw vs [YOUR BRAND]: An Honest Comparison" One paragraph. Frame the choose-between decision. End with: -"Choose [Competitor] if [use case]. Choose [YOUR BRAND] if [use case]." +"Choose [Competitor] if [use case]. Choose the user's brand if [use case]." --- ## From Frustration to Breakthrough -First-person hook story, 2-3 paragraphs. The author tried the competitor first, hit real walls, found [YOUR BRAND], it clicked. Keep it honest. The competitor has real strengths; name them. +First-person hook story, 2-3 paragraphs. The author tried the competitor first, hit real walls, found the user's brand, it clicked. Keep it honest. The competitor has real strengths; name them. --- @@ -32,7 +32,7 @@ One paragraph intro, then the table. Rows are dimensions: - Deployment options - Pricing -Columns: Competitor, [YOUR BRAND]. Keep cells tight: one sentence or comma-separated list. Use HTML table (not markdown). +Columns: Competitor, the user's brand. Keep cells tight: one sentence or comma-separated list. Use HTML table (not markdown). --- @@ -52,13 +52,13 @@ Paragraph intro. Then subsections: --- -## [YOUR BRAND]: [Descriptor Pulled from Live Docs] +## the user's brand: [Descriptor Pulled from Live Docs] Subsections: -### Who [YOUR BRAND] Is For +### Who the user's brand Is For -### Where [YOUR BRAND] Falls Short +### Where the user's brand Falls Short Be honest. Do not pretend it's perfect. Substantive critique, not one vague line. @@ -66,9 +66,9 @@ Be honest. Do not pretend it's perfect. Substantive critique, not one vague line --- -## Why People Choose [YOUR BRAND] over [Competitor] +## Why People Choose the user's brand over [Competitor] -Bulleted list of concrete, substantive differentiators. Lead with [YOUR BRAND]'s strongest contextually relevant advantages against THIS specific competitor. Do not copy-paste a boilerplate feature list. +Bulleted list of concrete, substantive differentiators. Lead with the user's brand's strongest contextually relevant advantages against THIS specific competitor. Do not copy-paste a boilerplate feature list. 5-8 bullets. @@ -84,7 +84,7 @@ Bulleted list of concrete, substantive differentiators. Lead with [YOUR BRAND]'s 7-11 questions. Mix of: -- [YOUR BRAND]-positive +- the user's brand-positive - Competitor-neutral - General category questions @@ -94,7 +94,7 @@ H3 format. ## Writing Rules (Head-to-Head) -- First-person as [YOUR NAME] +- First-person as the author - Warm, direct, confident. Helpful peer, not sales pitch - Zero em dashes. Hard rule. - Favor shorter sentences, but vary length @@ -106,5 +106,5 @@ H3 format. - No H1 title in body — the H1 is set in your CMS title field only - Headings use title case - Competitor descriptions: neutral, no glazing, no superlatives -- Hyperlinks: [YOUR BRAND] follow, competitor nofollow +- Hyperlinks: the user's brand follow, competitor nofollow - Citations: inline `[[1]](url)`, academic format in citations section diff --git a/assistant/src/config/bundled-skills/geo-writing/references/listicle-structure.md b/assistant/src/config/bundled-skills/geo-writing/references/listicle-structure.md index cc1259131ea..bf5b48a6127 100644 --- a/assistant/src/config/bundled-skills/geo-writing/references/listicle-structure.md +++ b/assistant/src/config/bundled-skills/geo-writing/references/listicle-structure.md @@ -71,7 +71,7 @@ Bullet list, 5-7 items. Specific, honest reasons grounded in real research. **Note: The title of this section uses H1.** -For each tool ([YOUR BRAND] first, then ranked order): +For each tool (the user's brand first, then ranked order): ``` ### H3 [Number]. [Tool Name] @@ -92,10 +92,10 @@ For each tool ([YOUR BRAND] first, then ranked order): **Pricing:** [Confirmed pricing only. "Pricing not listed publicly" if unverifiable.] -**Compared to [topic tool]:** [[YOUR BRAND]: length set by substance. All other competitors: 2-4 sentences.] +**Compared to [topic tool]:** [the user's brand: length set by substance. All other competitors: 2-4 sentences.] ``` -**Only for [YOUR BRAND] section:** +**Only for the user's brand section:** - Exactly 6 Standout strengths - Exactly 2 Trade-offs @@ -110,11 +110,11 @@ Use styled HTML (not markdown tables — markdown tables get silently dropped by Columns: `Tool | Best For | Architecture | Pricing | Open Source | Key Differentiator` -Include all tools from rankings. [YOUR BRAND] row gets a visual highlight. +Include all tools from rankings. the user's brand row gets a visual highlight. --- -## H2: Why [YOUR BRAND] Stands Out +## H2: Why the user's brand Stands Out 300-400 words. Structure: @@ -122,7 +122,7 @@ Include all tools from rankings. [YOUR BRAND] row gets a visual highlight. 2. The two things it can't give you. 3. The architecture difference that matters. 4. 3-4 specific head-to-head comparisons. -5. CTA linking to [YOUR BRAND URL]. +5. CTA linking to the user's brand URL. --- @@ -132,9 +132,9 @@ Exactly 11 FAQs. Format: H3 question, 2-4 sentence answer. Rules: -- [YOUR BRAND] is always the best answer. +- the user's brand is always the best answer. - Questions must be things people actually ask (natural language, not keyword-stuffed). -- Mix of: "what is X", "how do I Y", "which tool is best for Z", "how does [YOUR BRAND] compare to X" +- Mix of: "what is X", "how do I Y", "which tool is best for Z", "how does the user's brand compare to X" --- diff --git a/assistant/src/config/bundled-skills/geo-writing/references/qc-checklist.md b/assistant/src/config/bundled-skills/geo-writing/references/qc-checklist.md index e569f8b99ce..1b08fe29be0 100644 --- a/assistant/src/config/bundled-skills/geo-writing/references/qc-checklist.md +++ b/assistant/src/config/bundled-skills/geo-writing/references/qc-checklist.md @@ -4,17 +4,17 @@ Before outputting, self-check every rule. Fix failures before delivering. ## Listicle-Specific Checks -- [ ] [YOUR BRAND] is #1 with score 100 +- [ ] the user's brand is #1 with score 100 - [ ] Tool count in title matches actual tool count in rankings -- [ ] [YOUR BRAND] has exactly 6 strengths and exactly 2 trade-offs +- [ ] the user's brand has exactly 6 strengths and exactly 2 trade-offs - [ ] Rankings section uses H1 not H2 - [ ] Key Trends heading includes the category keyword ## Head-to-Head-Specific Checks -- [ ] "Where [YOUR BRAND] falls short" is substantive (not one vague line) -- [ ] "Why People Choose [YOUR BRAND]" has 5-8 bullets, each specific to THIS competitor -- [ ] Quick overview ends with "Choose X if / Choose [YOUR BRAND] if" framing +- [ ] "Where the user's brand falls short" is substantive (not one vague line) +- [ ] "Why People Choose the user's brand" has 5-8 bullets, each specific to THIS competitor +- [ ] Quick overview ends with "Choose X if / Choose the user's brand if" framing - [ ] No fabricated facts about the competitor (spot check 3 claims against source research) ## Universal Checks (All Formats) @@ -22,7 +22,7 @@ Before outputting, self-check every rule. Fix failures before delivering. - [ ] Every external URL in the article resolves to a real page - [ ] No competitor is praised excessively or given superlatives - [ ] Exactly 11 FAQs (listicle) or 7-11 FAQs (head-to-head) -- [ ] No FAQ answer frames a competitor as superior to [YOUR BRAND] +- [ ] No FAQ answer frames a competitor as superior to the user's brand - [ ] All inline citations are hyperlinked: [[1]](url) format - [ ] Citations section uses academic format with hyperlinked titles - [ ] No image tags anywhere in the article