--- name: agricidaniel/blog-write source: https://app.decimal.ai/s/agricidaniel-blog-write@2/SKILL.md source_sha256: 5671618acdfa --- # Blog Writer: New Article Generation Writes complete blog articles from a topic, brief, or outline. Every article follows the 6 pillars of dual optimization (Google rankings + AI citations). **Key references** (paths relative to repo root; references live in the main `blog` skill's references directory, not in `blog-write/`): - `skills/blog/references/synthesis-contract.md`: 6 LAWs for synthesis output (v1.8.0; applies whenever the article embeds research-synthesis prose) - `skills/blog/references/content-templates.md`: Template selection guide and usage - `skills/blog/references/quality-scoring.md`: 5-category scoring (Content 30, SEO 25, E-E-A-T 15, Technical 15, AI Citation 15) - `skills/blog/references/eeat-signals.md`: Experience, expertise, authority, trust markers - `skills/blog/references/internal-linking.md`: Linking strategy and anchor text rules - `skills/blog/references/visual-media.md`: Image sourcing and chart styling - `skills/blog-write/references/delivery.md`: delivery contract steps and summary template for this sub-skill ## Workflow ### Phase 0: Surface Targeting (do this BEFORE research) Decide which of the FLOW 5 surfaces this post is meant to win. The choice shapes structure, length, citation density, and call-to-action. The 5 surfaces in 2026: 1. Owned site (organic Google ranking) 2. SERP including AI Overviews 3. AI assistant citations (ChatGPT, Perplexity, Claude, Gemini, Copilot, You.com) 4. Local pack (out of scope for blog content; use claude-seo for local) 5. Communities and video (Reddit, YouTube, LinkedIn, Quora, niche forums) Most posts target surfaces 1, 2, and 3 by default. If the same query also surfaces in a community (Reddit thread, YouTube comment), apply dual-surface thinking: optimize the post for extraction AND plan a community echo (covered in `/blog repurpose`). For a deeper surface-by-surface workflow, see `skills/blog/references/flow-alignment.md` and `/blog flow find`. ### Phase 1: Topic Understanding 1. **Clarify the topic** - If the user provides just a topic, ask: - Target audience (who is this for?) - Primary keyword / search intent - Desired word count (default: 2,000-2,500 words) - Platform/format (MDX, markdown, HTML - auto-detect if in a project) 2. **If a brief exists** - Load it and skip to Phase 1.5 ### Phase 1.5: Template Selection Select the appropriate content template from the 12 templates in `skills/blog/templates/` (the main `blog` skill owns the templates directory). 1. **Auto-detect content type** from the topic and search intent: | Signal | Template | |--------|----------| | "How to...", process, steps | `how-to-guide` | | "Best X", "Top N", list format | `listicle` | | Client result, before/after, metrics | `case-study` | | "X vs Y", comparison, alternatives | `comparison` | | Broad topic, comprehensive guide | `pillar-page` | | "Is X worth it", product evaluation | `product-review` | | Opinion, prediction, industry take | `thought-leadership` | | Expert quotes, multi-source collection | `roundup` | | Code walkthrough, tool demo, technical | `tutorial` | | Breaking news, algorithm update, event | `news-analysis` | | Survey results, experiment, original data | `data-research` | | Q&A, knowledge base, "What is X" | `faq-knowledge` | 2. **Load the matching template**: Read from `skills/blog/templates/.md` 3. **Adapt the outline** - Use the template's section structure, heading patterns, and word count guidance to shape Phase 3's outline 4. **Fallback** - If no template clearly fits, use the generic outline structure in Phase 3 below. Inform the user which template was selected (or that none matched). See `skills/blog/references/content-templates.md` for detailed selection criteria and intent mapping. ### Phase 2: Research Spawn a `blog-researcher` agent (or do inline research with WebSearch): 1. **Find 8-12 current statistics** (2025-2026 data preferred) - Search: `[topic] study 2025 2026 data statistics` - Prioritize tier 1-3 sources (see `skills/blog/references/quality-scoring.md`) - Record: statistic, source name, URL, date, methodology 2. **Find a cover image** (wide, high-quality, topic-relevant): - Prefer original screenshots, product visuals, diagrams, or data graphics when available - For stock, use official APIs such as Openverse, Unsplash, Pexels, or Pixabay so license, creator, source URL, and download URL are captured - Download approved assets into the draft folder, store attribution, and never hotlink arbitrary CDN URLs - Reject `javascript:`, `data:`, and `file:` image URLs - Target dimensions: 1200x630 (OG-compatible) or 1920x1080 - Or generate a custom SVG cover via `blog-chart` (text-on-gradient with key stat) - Or generate a custom AI image via `blog-image`; prefer `gemini-3.1-flash-image`, then `gemini-3.1-flash-lite-image` or `gemini-3-pro-image` when available, and record the model ID - See `skills/blog/references/visual-media.md` for cover image sizing details 3. **Find 3-5 inline images** from open-source platforms: - Use official APIs or Openverse search; keep license, creator, source URL, and retrieval date with each asset - Download images locally and reference local paths in the draft - Validate final URLs with the delivery contract SSRF rules before download 4. **Plan 2-4 data visualizations** from researched statistics - Select diverse chart types (see `skills/blog/references/visual-media.md`) - Map data points to chart formats 5. **AI image generation** (optional, if `blog-image` is available): - If stock photo results are insufficient (< 3 good matches) or topic is too niche - Generate custom hero image and/or inline illustrations via `blog-image` sub-skill - Record prompt, provider, and model ID; stock photos remain available, but original and data visuals are preferred when they better serve the topic 6. **NotebookLM research** (optional, if user has relevant notebooks): - If the user mentions a NotebookLM notebook or the topic aligns with a configured notebook - Query via `blog-notebooklm` for source-grounded data from user-uploaded documents - Inherit the source tier from the underlying document provenance; user's own primary documents can be Tier 1, while copied secondary sources keep their original tier - Falls back silently if not configured or not authenticated 7. **Find relevant YouTube videos** (2-3 per post): - Use `blog-google` youtube command or WebSearch `site:youtube.com [topic] [year]` - Apply quality criteria from `skills/blog/references/video-embeds.md` (min score 50/100) - Select 2-3 best videos. Falls back silently if none found. ### Phase 3: Outline Generation Create a structured outline before writing. If a template was loaded in Phase 1.5, adapt this skeleton to match the template's section structure: ``` # [Title as Question - Include Primary Keyword] ## Introduction (100-150 words) - Hook with surprising statistic - Problem/opportunity statement - What the reader will learn > **Key Takeaways** > - [Core finding with statistic and source] > - [Second key insight or recommendation] > - [Third actionable takeaway] > (3-5 bullets, 40-60 words combined) ## H2: [Question Format] (300-400 words) - Answer-first paragraph (40-60 words with stat + source) - Supporting evidence - [Image placement] - Practical advice - [CITATION CAPSULE placeholder] - [INTERNAL-LINK: anchor text → target description] ## H2: [Question Format] (300-400 words) - Answer-first paragraph - [Chart: type + data description] - Analysis and implications - [CITATION CAPSULE placeholder] - [INTERNAL-LINK: anchor text → target description] ## H2: [Statement for Variety] (300-400 words) - Answer-first paragraph - Real-world example or case study - [Image placement] - [CITATION CAPSULE placeholder] ## H2: [Question Format] (300-400 words) - Answer-first paragraph - [Chart: type + data description] - Step-by-step guidance - [CITATION CAPSULE placeholder] - [INTERNAL-LINK: anchor text → target description] ## H2: [Question Format] (200-300 words) - Answer-first paragraph - Forward-looking analysis ## [CTA Section or Inline Placement] - See `skills/blog/references/cta-placement.md` for placement rules by content type - Place CTA after value delivery, not at arbitrary positions - Single focused CTA per post (266% more conversions) - [CTA: contextual call-to-action matching article topic] ## FAQ Section (3-5 questions, 40-60 words each answer) - [INTERNAL-LINK: anchor text → detailed content] ## Conclusion (100-150 words) - Key takeaways (bulleted) - Call to action - [INTERNAL-LINK: anchor text → next logical content] ``` Present the outline to the user for approval before writing. **Visual element pacing**: Insert `[IMAGE]`, `[CHART]`, `[VIDEO]`, or `[CALLOUT]` markers every 300-500 words. Alternate types (no consecutive same-type). See `skills/blog/references/content-rules.md` Visual Rhythm section and `skills/blog/references/cta-placement.md` for CTA positioning. ### Phase 4: Chart Generation (Built-In) When the researcher identifies chart-worthy data (3+ comparable metrics, trend data, before/after comparisons): 1. Select chart type using the diversity rule (no repeated types per post) 2. Invoke `blog-chart` sub-skill with: chart type, title, data values, source, platform format 3. Embed the returned SVG directly in the post within a `
` wrapper 4. Target 2-4 charts per 2,000-word post 5. Distribute charts evenly - never cluster them See `skills/blog/references/visual-media.md` for chart type selection and styling rules. ### Phase 5: Content Writing Write the full article following these rules: #### 5a. Frontmatter ```yaml --- title: "[Question-format title with primary keyword]" description: "[Fact-dense, 150-160 chars, includes 1 statistic]" coverImage: "[URL from Pixabay/Unsplash/Pexels or generated SVG path]" coverImageAlt: "[Descriptive sentence about the cover image]" ogImage: "[Same as coverImage, or custom OG image URL]" date: "YYYY-MM-DD" lastUpdated: "YYYY-MM-DD" author: "[Author name]" tags: ["keyword1", "keyword2", "keyword3"] --- ``` If the platform uses a different field name (e.g., `image`, `hero`, `thumbnail`), adapt to match the project's existing frontmatter convention. #### 5b. Summary Box (Key Takeaways) Immediately after the introduction (before the first H2 body section), add a summary box: ```markdown > **Key Takeaways** > - [Core finding with statistic] ([Source], year) > - [Second key insight or recommendation] > - [Third actionable takeaway] ``` Requirements: - 3-5 bullet points, 40-60 words combined - Must be self-contained - understandable without reading the article - Include 1 specific statistic with source name - State the key finding, recommendation, or answer - Default label: "Key Takeaways". If a persona is active, use the persona's summary_label - Backward compatible: accept existing TL;DR boxes during rewrites #### 5c. Answer-First Formatting (Critical) Every H2 section MUST open with a 40-60 word paragraph containing: - At least one specific statistic with source attribution - A direct answer to the heading's implicit question Pattern: ```markdown ## How Does X Impact Y in 2026? [Stat from source] ([Source Name](url), year). [Direct answer to the heading question in 1-2 more sentences, explaining the implication and what this means for the reader.] ``` **FLOW evidence triple (drafting requirement, not just audit):** Every public statistic must carry three components AT DRAFTING TIME: 1. **Year anchor in prose.** Write "In 2026," or "As of Q1 2026," BEFORE the statistic, in the sentence body. Year buried inside parentheses does not count. Example: - GOOD: "In 2026, Ahrefs found a 58% lower CTR for position one when an AI Overview was present." - WEAK: "Position-one CTR dropped 58% (Ahrefs, 2026)." 2. **Inline citation with publisher and title.** Name both the publisher and the document title (or report name), not just a brand. Example: - GOOD: "Ahrefs, [document or report title], 2026" - WEAK: "Ahrefs reported..." 3. **URL plus retrieval date in the source block at the bottom of the post.** Provenance discipline lets future readers and AI crawlers verify the source still says what was claimed. Format: - "[Publisher], [Title], retrieved YYYY-MM-DD, [full URL]" **FLOW quality bar (drop or replace):** Public claims must use verified sources OR stay qualitative. If a statistic cannot be verified, drop it. If it is contradicted by a more recent source, replace it with the verified alternative. Do not soften vague language to keep an unsourceable number. For evidence-led optimization prompts (CTR audit, AI detector test, schema, PAA rewording, ChatGPT visibility), see `/blog flow optimize`. #### 5d. Information Gain Markers Distribute at least 2-3 information gain markers throughout the article. These signal to search engines and AI systems that the content contains original value not available elsewhere. Tag each with a comment or visible marker: - `[ORIGINAL DATA]` - Proprietary surveys, experiments, A/B test results, case study metrics the author collected first-hand - `[PERSONAL EXPERIENCE]` - First-hand observations, lessons learned from direct involvement, "when we tried X, Y happened" narratives - `[UNIQUE INSIGHT]` - Analysis others haven't made, contrarian perspectives backed by data, novel connections between existing research Placement: - Weave into the body text naturally - Use as inline comments: `` before the relevant paragraph - Or as visible callouts if the format supports it: ```markdown > **Our finding:** [original observation backed by specific data] ``` - Minimum 2 per post, target 3 for comprehensive articles These markers map directly to the "Originality/unique value markers" criterion in the Content Quality scoring category (see `skills/blog/references/quality-scoring.md`). #### 5e. Citation Capsules For each major H2 section, generate a citation capsule - a 40-60 word self-contained passage designed so AI systems can extract and quote it directly. Requirements per capsule: - 40-60 words, self-contained (makes sense in isolation) - Contains: one specific claim + one data point + source attribution - Written in a declarative, quotable style - Placed within the H2 section body (not as a separate block) Example: ```markdown According to a 2026 Gartner study, 58% of enterprise buyers now consult AI assistants before contacting a vendor ([Gartner](https://www.gartner.com), 2026). This shift means B2B content must answer specific questions concisely enough for AI systems to extract and cite in their responses. ``` Capsules map to the "AI Citation Readiness" scoring category (15 points) in `skills/blog/references/quality-scoring.md`. #### 5f. Internal Linking Zones Mark internal linking opportunities throughout the article using placeholder notation. The user (or a follow-up pass) will resolve these to actual URLs. Zone placement: - **Introduction** - Link to related pillar content or topic hub - **Each H2 section** - Link to supporting articles, deeper dives, related tools - **FAQ section** - Link answers to detailed content that expands on the answer - **Conclusion** - Link to the next logical piece of content the reader should consume Format: ```markdown [INTERNAL-LINK: anchor text → target description] ``` Example: ```markdown For a deeper dive into keyword clustering, see our [INTERNAL-LINK: complete guide to keyword clustering → pillar page on keyword research methodology]. ``` Target 5-10 internal link zones per 2,000-word post. Use descriptive anchor text (never "click here" or "read more"). See `skills/blog/references/internal-linking.md` for anchor text rules and linking strategy. #### 5g. Paragraph Rules - Every paragraph: 40-80 words (never exceed 150) - Every sentence: max 15-20 words - Start each paragraph with the most important information - Target Flesch Reading Ease: 60-70 #### 5h. Heading Rules - One H1 (title only) - H2s for main sections (60-70% as questions) - H3s for subsections only - never skip levels - Include primary keyword naturally in 2-3 headings #### 5i. Image Embedding Standard markdown: ```markdown ![Descriptive alt text - topic keywords naturally](https://cdn.pixabay.com/photo/...) ``` MDX with Next.js Image (if detected): ```mdx ![Descriptive alt text - topic keywords naturally](https://cdn.pixabay.com/photo/...) ``` - Place images after H2 headings, before body text - Space evenly throughout the post (not clustered) - Alt text should be a full descriptive sentence #### 5j. Chart Embedding Standard markdown/HTML: ```html
...
Source: [Source Name], [Year]
``` MDX format: ```mdx
...
``` #### 5k. Video Embedding Embed YouTube videos using srcdoc lazy-loading pattern from `skills/blog/references/video-embeds.md`. Include aria-label, noscript fallback for AI crawlers. Place after relevant H2, 500+ words apart. #### 5l. Citation Format Inline attribution (always): ```markdown In February 2026, Seer Interactive's AI Overview CTR tracker reported a 2.4% organic CTR on AI Overview SERPs ([Seer Interactive](https://www.seerinteractive.com/), retrieved YYYY-MM-DD). ``` #### 5m. FAQ Section Add 3-5 FAQ items with 40-60 word answers when user questions warrant it. Each answer must contain a verified statistic when a relevant source-backed number exists. FAQPage is optional entity markup only. Google FAQ rich results have been limited primarily to well-known, authoritative government and health sites since the 2023 guidance, so do not make FAQ schema a core Google rich-result output or citation lever. Prioritize Article/BlogPosting + Person + Organization + BreadcrumbList; emit FAQPage only when the platform already supports it and the questions genuinely help users. For MDX with an optional FAQSchema component: ```mdx ``` For standard markdown: ```markdown ## Frequently Asked Questions ### Question text here? Answer with statistic and source attribution (40-60 words). ``` #### 5n. Internal Linking - 5-10 internal links per 2,000-word post - Link to relevant existing content naturally - Use descriptive anchor text (not "click here") ### Phase 6: Quality Check Before delivering, verify: #### Structure and Content 1. Every H2 opens with a statistic + source 2. No paragraph exceeds 150 words 3. All statistics have named tier 1-3 sources 4. 2-4 charts with type diversity 5. 3-5 inline images with descriptive alt text 6. Cover image present in frontmatter (coverImage + ogImage) 7. FAQ section present with 3-5 items when warranted by user questions 8. Heading hierarchy is clean (H1 -> H2 -> H3) 9. Meta description is 150-160 chars with a stat #### New Element Verification 10. TL;DR box present after introduction (40-60 words, contains statistic + source) 11. At least 2-3 information gain markers (`[ORIGINAL DATA]`, `[PERSONAL EXPERIENCE]`, or `[UNIQUE INSIGHT]`) 12. Citation capsules present in major H2 sections (40-60 words, self-contained, quotable) 13. Internal linking zones marked in introduction, H2 sections, FAQ, and conclusion 14. No AI-detectable phrases from banned list (see `agents/blog-writer.md`) #### Burstiness and Naturalness Check 15. **Sentence length variance** - Verify a mix of short (8-word) and long (25-word) sentences. Uniform sentence length signals AI authorship. 16. **Banned AI phrase scan** - Check for and remove: - "in today's digital landscape", "it's important to note", "dive into" - "game-changer", "navigate the landscape", "revolutionize", "seamlessly" - "cutting-edge", "harness the power of", "leverage" (as verb) - "delve", "crucial", "elevate", "foster", "landscape" (overused) - "multifaceted", "robust", "tapestry", "embark" - Full list in `agents/blog-writer.md` 17. **Contractions** - Verify natural use of contractions ("it's", "we've", "don't", "isn't"). Formal AI prose avoids contractions; natural writing uses them. 18. **Rhetorical questions** - Verify at least one rhetorical question every 200-300 words to break up declarative patterns. 19. **YouTube videos** - 2-3 embeds with lazy loading, aria-labels, and noscript fallback (see `skills/blog/references/video-embeds.md`) ### Phase 6.5: Delivery Contract Enforcement (v1.9.0) Before Phase 7, run the 5-gate delivery contract (via `python3 scripts/blog_preflight.py` plus a BLOCKING `blog-reviewer` agent) per `skills/blog/references/blog-delivery-contract.md` and the writer-specific checklist in `skills/blog-write/references/delivery.md`. Use `python3` for local scripts. The user is never the first reviewer; the gates are. On any block, capture `/preflight-report.json`, re-dispatch the blog-writer agent with the diagnostic as input, and re-run the gated steps. Maximum 3 iterations. On the 3rd failure, stop and present the failure diagnostic instead of the draft. ### Phase 7: Delivery Present the completed article only after Phase 6.5 returns all gates passing. Include `/preview/*.png` screenshots and the compact completion summary described in `skills/blog-write/references/delivery.md`.