agricidaniel__claude-blog/docs/TEMPLATES.md

Content Templates

Reference guide for the 12 content type templates included with claude-blog. Templates provide structural blueprints for different article types, ensuring consistent quality and optimization across all content.

---

Template Overview

Template	Content Type	Word Count Target	Best For
how-to-guide.md	How-To Guide	2,000-2,500	Step-by-step tutorials, process guides
listicle.md	Listicle	1,500-2,000	Ranked lists, curated collections
case-study.md	Case Study	2,000-3,000	Client results, project retrospectives
comparison.md	Comparison	1,500-2,000	X vs Y, tool evaluations
pillar-page.md	Pillar Page	3,000-4,000	Comprehensive topic guides
product-review.md	Product Review	1,500-2,500	Tool reviews, software evaluations
thought-leadership.md	Thought Leadership	2,000-3,000	Industry analysis, opinion pieces
roundup.md	Expert Roundup	2,000-2,500	Multi-source collections, trend reports
tutorial.md	Tutorial	2,500-3,500	Code walkthroughs, technical demos
news-analysis.md	News Analysis	800-1,500	Industry updates, algorithm changes
data-research.md	Data/Research	2,500-3,500	Original research, survey results
faq-knowledge.md	FAQ / Knowledge Base	1,500-2,000	Reference content, Q&A collections

---

How Templates Work

Templates are structural blueprints, not fill-in-the-blank forms. Each template defines:

1. Section structure: The H2/H3 skeleton for the content type
2. Answer-first prompts: Guidance for opening each section with data
3. Coverage prompts: Intent-dependent completeness without padding
4. Info gain markers: Where original data or unique perspective is needed
5. Visual element placement: Where charts and images should appear
6. Optional Q&A zone: Where genuine unanswered reader questions fit
7. Linking zones: Where internal and external links are most natural

---

Template Structure Anatomy

Every template follows a consistent internal structure:

# [Template Name]

## Metadata
- Content type: [type]
- Word count: [range]
- H2 sections: [count]
- Charts: [count]
- Images: [count]
- Optional Q&A items: [count by reader need]

## Section Structure

### Frontmatter
[Required fields for this content type]

### Introduction (100-150 words)
- Hook: [Type of hook that works best]
- Problem/opportunity: [Framing guidance]
- Promise: [What reader learns]

### H2: [Section Pattern] (word count)
ANSWER-FIRST: [Guidance for the opening stat paragraph]
CONTENT: [What to cover in the body]
INFO-GAIN: [Where unique perspective is needed]
VISUAL: [Chart type or image suggestion]

[... additional H2 sections ...]

### Optional Q&A Zone (count by reader need)
[Visible Q&A guidance specific to this content type; omit when it would repeat
the article. Q&A presence earns no score.]

### Conclusion (100-150 words)
[Closing pattern for this content type]

## Optimization Notes
[Content-type-specific SEO and GEO tips]

Section Markers

Marker	Purpose
ANSWER-FIRST:	Guidance to state the section point early and support material claims; no fixed length or statistic quota
CONTENT:	What topics and subtopics to cover in the section body
INFO-GAIN:	Where original data, first-hand experience, or unique perspective is needed
VISUAL:	Recommended chart type or image placement
FAQ-ZONE:	Where an optional visible Q&A section may appear when reader need warrants it
LINK-ZONE:	Natural places for internal or external links

---

How /blog write Selects Templates

When /blog write is invoked, the orchestrator selects a template based on:

1. Explicit User Request

If the user specifies a content type, that template is used directly:

/blog write "10 Best CI/CD Tools for 2026"      --> listicle.md
/blog write "How to Set Up Kubernetes Monitoring" --> how-to-guide.md
/blog write case study: Acme Corp migration       --> case-study.md

2. Topic Analysis

If no type is specified, the orchestrator analyzes the topic:

Topic Signal	Template Selected
"How to...", "Guide to..."	how-to-guide.md
Numbers in title ("10 Best...", "7 Ways...")	listicle.md
"X vs Y", "compared", "alternative"	comparison.md
"Review", "tested", "hands-on"	product-review.md
Company/project name + "results"	case-study.md
Broad topic, "complete guide", "everything"	pillar-page.md
"Tutorial", "walkthrough", "step by step"	tutorial.md
News event, update, announcement	news-analysis.md
Survey, study, data, research	data-research.md
"FAQ", "questions about"	faq-knowledge.md
Industry trend, prediction, opinion	thought-leadership.md
Expert quotes, collection, roundup	roundup.md

3. Default

If the topic is ambiguous, the orchestrator defaults to how-to-guide.md as the most versatile template and confirms with the user.

---

Template Details

how-to-guide.md

Best for step-by-step guides where the reader wants to accomplish something.

Structure:
  Introduction (hook with difficulty/time stat)
  H2: Why This Matters (context + data)
  H2: Prerequisites / What You Need
  H2: Step 1 - [Action] (answer-first with success rate)
  H2: Step 2 - [Action]
  H2: Step 3 - [Action]
  H2: Common Mistakes to Avoid
  H2: Optional Q&A (count by reader need)
  Conclusion (key takeaways + next step)

Visuals: Process flow chart, before/after comparison chart
Images: Screenshots or relevant stock for each major step

listicle.md

Best for ranked lists, tool collections, and curated recommendations.

Structure:
  Introduction (hook with total count stat)
  H2: [Item 1] - [Key Differentiator]
  H2: [Item 2] - [Key Differentiator]
  ... (5-15 items depending on depth)
  H2: How We Evaluated [Category]
  H2: Optional Q&A (count by reader need)
  Conclusion (top pick + comparison table)

Visuals: Comparison bar chart, market share donut chart
Images: Logo/screenshot per item, or grouped comparison image

case-study.md

Best for showcasing real results with specific metrics.

Structure:
  Introduction (headline result stat)
  H2: The Challenge
  H2: The Approach / Solution
  H2: Implementation Details
  H2: Results (metrics + timeline)
  H2: Key Takeaways
  H2: Optional Q&A (count by reader need)
  Conclusion (CTA to learn more)

Visuals: Before/after bar chart, timeline or results line chart
Images: Screenshots, dashboards, team/process photos
Info-Gain: Real metrics from the actual project (critical)

comparison.md

Best for X vs Y evaluations and tool comparisons.

Structure:
  Introduction (market context stat)
  H2: Quick Comparison Table
  H2: [Product A] Overview
  H2: [Product B] Overview
  H2: Feature-by-Feature Comparison
  H2: Pricing Comparison
  H2: Which Should You Choose?
  H2: Optional Q&A (count by reader need)
  Conclusion (recommendation matrix)

Visuals: Feature comparison radar chart, pricing bar chart
Images: Product screenshots, UI comparisons

pillar-page.md

Best for comprehensive guides that serve as hub pages for topic clusters.

Structure:
  Introduction (scope + authority stat)
  H2: What Is [Topic]? (definition + context)
  H2: Why [Topic] Matters in 2026
  H2: [Core Subtopic 1] (detailed coverage)
  H2: [Core Subtopic 2]
  H2: [Core Subtopic 3]
  H2: [Core Subtopic 4]
  H2: [Advanced Topic]
  H2: Tools and Resources
  H2: Optional Q&A (count by reader need)
  Conclusion (learning path + next steps)

Visuals: 3-4 charts (diverse types), topic overview diagram
Images: 5+ images distributed throughout
Linking: Heavy internal linking to supporting cluster pages

product-review.md

Best for hands-on tool reviews with real testing results.

Structure:
  Introduction (verdict stat, e.g., performance score)
  H2: Quick Verdict
  H2: What Is [Product]?
  H2: Setup and First Impressions
  H2: Key Features Tested
  H2: Performance Results
  H2: Pricing and Value
  H2: Pros and Cons
  H2: Who Is This For?
  H2: Optional Q&A (count by reader need)
  Conclusion (final rating + recommendation)

Visuals: Performance benchmark chart, pricing comparison
Images: Screenshots from actual testing (critical for E-E-A-T)
Info-Gain: First-hand testing data (must demonstrate Experience)

thought-leadership.md

Best for industry analysis and forward-looking opinion pieces.

Structure:
  Introduction (trend stat that sets the stage)
  H2: The Current Landscape
  H2: What's Changing (analysis + data)
  H2: Why This Matters
  H2: Evidence and Interpretation (supported first-hand perspective when
      supplied, otherwise differentiated sourced analysis)
  H2: What to Do About It (actionable advice)
  H2: Looking Ahead (predictions)
  H2: Optional Q&A (count by reader need)
  Conclusion (key thesis + call to action)

Visuals: Trend line chart, market shift chart
Info-Gain: Supported personal perspective when available, or differentiated
sourced synthesis and clearly framed analysis

roundup.md

Best for collecting insights from multiple sources or experts.

Structure:
  Introduction (theme + number of sources stat)
  H2: Key Finding 1 (synthesis from multiple sources)
  H2: Key Finding 2
  H2: Key Finding 3
  H2: Expert Perspectives
  H2: What This Means for [Audience]
  H2: Optional Q&A (count by reader need)
  Conclusion (synthesis + action items)

Visuals: Multi-source comparison chart, trend aggregation

tutorial.md

Best for technical walkthroughs with code examples.

Structure:
  Introduction (what you'll build + tech stack)
  H2: Prerequisites and Setup
  H2: Step 1 - [Foundation]
  H2: Step 2 - [Core Feature]
  H2: Step 3 - [Integration]
  H2: Step 4 - [Testing/Deployment]
  H2: Troubleshooting Common Issues
  H2: Optional Q&A (count by reader need)
  Conclusion (complete code repo link + extensions)

Visuals: Architecture diagram (SVG), performance chart
Images: Terminal screenshots, UI results
Special: Code blocks with syntax highlighting throughout

news-analysis.md

Best for timely commentary on industry events and updates.

Structure:
  Introduction (the news + impact stat)
  H2: What Happened
  H2: Why It Matters
  H2: Who's Affected
  H2: What to Do Now (immediate actions)
  H2: Optional Q&A (count by reader need)
  Conclusion (outlook)

Visuals: 1-2 charts (impact visualization)
Note: Shorter format (800-1,500 words), speed matters

data-research.md

Best for original research, surveys, and data analysis.

Structure:
  Introduction (headline finding)
  H2: Methodology
  H2: Key Finding 1 (data + analysis)
  H2: Key Finding 2
  H2: Key Finding 3
  H2: Implications
  H2: Limitations
  H2: Optional Q&A (count by reader need)
  Conclusion (summary of findings + data access)

Visuals: 3-4 charts (data visualizations are central)
Info-Gain: Original data is the entire value proposition

faq-knowledge.md

Best for comprehensive Q&A reference content.

Structure:
  Introduction (topic scope + common questions stat)
  H2: [Category 1] Questions
    H3: Question 1? (concise, complete answer with support where needed)
    H3: Question 2?
  H2: [Category 2] Questions
    H3: Question 3?
    H3: Question 4?
  H2: [Category 3] Questions
  Conclusion (additional resources)

Visuals: 1-2 summary charts
Special: Use statistics only when relevant, verified, and useful
Schema: FAQPage is optional visible-content markup with no readiness-score benefit

---

How to Customize Templates

Modifying an Existing Template

1. Navigate to ~/.claude/skills/blog/templates/
2. Open the template file you want to modify
3. Adjust section structure, word counts, or guidance
4. Changes take effect immediately (no restart needed)

Creating a New Template

1. Copy an existing template as a starting point:

   cp ~/.claude/skills/blog/templates/how-to-guide.md \
      ~/.claude/skills/blog/templates/my-custom-type.md
   

2. Define the section structure for your content type
3. Add ANSWER-FIRST:, VISUAL:, and INFO-GAIN: markers
4. Set appropriate word count targets
5. Add a topic signal entry in the template selection logic

Template Best Practices

• Keep sections focused on one topic each
• Place VISUAL: markers where data naturally supports a chart
• Use INFO-GAIN: markers liberally: these are the sections that differentiate your content from AI-generated consensus
• Set realistic word counts that match the content type's natural depth
• Include an FAQ zone only when genuine reader questions warrant it; keep a conclusion when the content type benefits from one

---

Template and Scoring Integration

Templates guide content creation; the scoring system validates the result. The mapping between template features and scoring categories:

Template Feature	Scoring Category	Points At Stake
Section structure	Schema & Structure	10
Purpose-first markers	Purpose Fit and Reader Utility	20
Visual placement	Visual Elements	15
Optional FAQ zone	Reader utility only; no Google/AI score effect	0
Info-gain markers	Content Quality	25
Citation guidance	Statistics & Citations	20

A well-followed template naturally produces content scoring 75+ without additional optimization passes.