Free, open source blog writer for Claude Code. Researches current sources, writes answer-first posts for Google and AI answers, has an independent reviewer score each one out of 100 and ships only after five delivery gates. 32 skills, 30 /blog commands, 5 agents. Active development at AI-Marketing-Hub/claude-blog; public releases ship here.
Architecture
System design documentation for claude-blog, covering component types,
data flow, scoring methodology, file conventions, and extension points.
The Claude Blog Brain is vendored at ./brain as a self-contained, evidence-gated Obsidian brain. It is not part of the plugin payload; all skill tooling remains scoped to skills/.
System Overview
+-----------------------------+
| User Input |
| /blog <command> [args] |
+-------------+---------------+
|
v
+-----------------------------+
| Main Orchestrator |
| skills/blog/SKILL.md |
| |
| - Command parsing |
| - Platform detection |
| - Sub-skill routing |
| - Quality gate enforcement |
+------+----------+-----------+
| |
+----------------+ +----------------+
| |
v v
+----------------------------+ +---------------------------+
| 32 Skill Directories | | On-Demand References |
| 1 orchestrator + 31 | | skills/blog/references/*.md |
| sub-skills | | skills/blog/templates/*.md |
| write rewrite | | |
| analyze brief | | 22 references loaded |
| calendar strategy | | on demand (RAG pattern) |
| outline seo-check | | 12 content templates |
| schema repurpose | +---------------------------+
| geo audit |
| image cannibalization |
| factcheck persona |
| taxonomy notebooklm |
| audio google |
| cluster flow |
| multilingual translate |
| localize locale-audit |
| brand discourse |
| style decay |
| chart (internal) |
+------+----------+----------+
| |
v v
+------------------+ +------------------------+
| 5 Subagents | | 23 root-level Scripts |
| agents/*.md | | scripts/*.py |
| | | |
| blog-researcher | | analyze_blog |
| blog-writer | | blog_preflight (1.9) |
| blog-seo | | blog_render (1.9) |
| blog-reviewer | | blog_hygiene (1.11) |
| blog-translator | | ai_citation_score |
| | | content_decay |
| | | quality_gate |
| | | style_learn |
| | | |
| | | generate_hero (1.9) |
| | | cognitive_load |
+------------------+ | discourse_research |
| load_untrusted_root |
| lint_prose |
| sync_flow |
+------------------------+
Component Types
1. Main Orchestrator
File: skills/blog/SKILL.md
The entry point for all /blog commands. Responsibilities:
- Parse user input to identify the sub-command and arguments
- Detect the blog platform from project structure (MDX, Hugo, Jekyll, etc.)
- Route to the appropriate sub-skill
- Enforce quality gates (hard rules that never ship content violating them)
- Load reference files on demand
The orchestrator is a Claude Code skill with YAML frontmatter defining its name, description, trigger phrases, and allowed tools.
2. Skill Directories (32 total: 1 orchestrator + 31 sub-skills; 30 user-facing commands)
Location: skills/blog-*/SKILL.md (and skills/blog/SKILL.md for the orchestrator)
Each sub-skill is a standalone Claude Code skill with its own:
- YAML frontmatter validated by
scripts/validate_skills.pyusing real YAML with duplicate-key rejection. Nativeuser-invocabledefaults to true; explicit booleans, name/directory agreement and size caps are project policy.allowed-toolsis valid host permission preapproval metadata, but this bundle deliberately ships no preapprovals. Agenttoolsis the allowlist. - Detailed workflow (step-by-step instructions)
- Input/output specifications
- Quality checks
| Sub-Skill | Responsibility | Introduced |
|---|---|---|
| blog-write | New article generation with full optimization (v1.9.0: iterates through 5-gate delivery contract until score >= 90 and zero P0, at most 3 failed gate runs per draft) | v1.0.0 |
| blog-rewrite | Existing post optimization preserving author voice (v1.9.0: same delivery contract) | v1.0.0 |
| blog-analyze | Quality audit with 5-category 100-point scoring | v1.0.0 |
| blog-brief | Content brief generation with research | v1.0.0 |
| blog-calendar | Editorial calendar planning | v1.0.0 |
| blog-strategy | Blog positioning and content architecture | v1.0.0 |
| blog-outline | SERP-informed outline generation | v1.0.0 |
| blog-seo-check | Post-writing SEO validation | v1.0.0 |
| blog-schema | JSON-LD schema markup generation | v1.0.0 |
| blog-repurpose | Cross-platform content repurposing | v1.0.0 |
| blog-geo | AI citation optimization audit | v1.0.0 |
| blog-audit | Full-site blog health assessment | v1.0.0 |
| blog-chart | Inline SVG charts (internal-only, invoked by write/rewrite) | v1.0.0 |
| blog-image | AI image generation via Gemini (nanobanana-mcp) | v1.4.0 |
| blog-cannibalization | Keyword overlap detection across posts | v1.4.x |
| blog-factcheck | Statistics verification against cited sources | v1.4.x |
| blog-persona | Writing persona / voice profile management | v1.4.x |
| blog-taxonomy | CMS tag / category management (WordPress, Shopify, Ghost, Strapi, Sanity) | v1.4.x |
| blog-notebooklm | Source-grounded research via NotebookLM | v1.5.0 |
| blog-audio | Audio narration via Gemini TTS (30 voices, 80+ languages) | v1.6.0 |
| blog-google | Google API integration (PSI, CrUX, GSC, GA4, NLP, YouTube, Ads) | v1.6.5 |
| blog-cluster | Semantic topic-cluster planning + execution (hub-and-spoke) | v1.7.0 |
| blog-flow | FLOW framework prompts (find / optimize / win / prompts / sync) | v1.7.0 |
| blog-multilingual | One-command multilingual write + translate + localize + hreflang | v1.7.0 |
| blog-translate | SEO-optimized translation with format preservation | v1.7.0 |
| blog-localize | Cultural deep-adaptation per locale | v1.7.0 |
| blog-locale-audit | Multilingual content QA (completeness, hreflang, parity, freshness) | v1.7.0 |
| blog-brand | Generate BRAND.md + VOICE.md context auto-loaded by all sub-skills | v1.8.0 |
| blog-discourse | API-free last-30-days discourse research (Reddit, X, YouTube, etc.) | v1.8.0 |
| blog-style | Learn author voice profiles from existing posts | v1.10.0 |
| blog-decay | Detect GSC content decay and prioritize refresh candidates | v1.10.0 |
3. Subagents (5)
Location: agents/blog-*.md
Specialized agents spawned by sub-skills via Claude Code's Task tool.
Each agent has a focused role with a restricted tool set. None of the
agents have Bash access; the v1.7.0 hardening removed Bash from the
agent frontmatter to bound blast radius (see agents/blog-reviewer.md
and agents/blog-translator.md).
| Agent | Tools | Role |
|---|---|---|
| blog-researcher | WebSearch, WebFetch, Read, Grep, Glob | Find statistics, images, competitive data |
| blog-writer | Read, Write, Edit, Grep, Glob | Write and rewrite optimized content |
| blog-seo | Read, Grep, Glob | Technical SEO analysis and validation |
| blog-reviewer | Read, Grep, Glob | Quality review and scoring; BLOCKING in v1.9.0 (emits BLOCKING: true|false (reason) line parsed by scripts/blog_preflight.py Gate 4) |
| blog-translator | Read, Write, Edit, Grep, Glob | Multilingual translation (v1.7.0; no Bash for blast-radius safety) |
Agents are defined as markdown files with YAML frontmatter specifying their name, description, and available tools.
4. Reference Files (22)
Location: skills/blog/references/*.md
Knowledge documents loaded on demand (RAG-style; not preloaded into context).
22 references in skills/blog/references/ cover SEO landscape, GEO/AEO,
content rules, visual media, schema, E-E-A-T, platform guides, distribution,
internal linking, FLOW prompts, video embeds, AI-slop detection, editorial
heuristics, cognitive load, research quality, synthesis contract, and the
v1.9.0 blog-delivery-contract spec.
To list the current set:
ls skills/blog/references/*.md
The exact list is intentionally not enumerated here so this doc doesn't drift
behind file-system reality. The test_reference_count_coherence pytest
asserts the count claimed in skills/blog/SKILL.md matches the actual file
count, so every documented count auto-syncs.
5. Content Templates (12)
Location: skills/blog/templates/*.md
Structural templates for different content types. Each template defines section structure, word count targets, and format-specific guidance. See TEMPLATES.md for the full reference.
6. Root-Level Python Scripts (23)
Location: scripts/*.py
Twenty-three Python helpers live at the repository root (count them with
ls scripts/*.py | wc -l; scripts/windows_installer_ownership.ps1 is the
PowerShell twin of the ownership engine and is not counted). They support the
orchestrator, the delivery contract, the installers and the CI checks.
Interfaces and output formats are documented by each helper (--help);
dependencies are stdlib-only or narrowly pinned.
| Script | Purpose | Introduced |
|---|---|---|
analyze_blog.py |
5-category 100-point quality scoring; batch mode; JSON/markdown/table output | v1.0.0 |
ai_citation_score.py |
Non-calibrated AI citation readiness heuristic, 0-100 per post | v1.10.0 |
blog_hygiene.py |
Optional deterministic hygiene: lazy-load images and auto-TOC | v1.11.0 |
blog_preflight.py |
Runs the 5-gate Blog Delivery Contract (Gates 1, 2, 3, 5 plus the Gate 4 nonce and digest checks); --init-review-nonce issues the review nonce |
v1.9.0 |
blog_render.py |
md -> html -> pdf renderer; XSS-safe JSON-LD via </-><\/; O_NOFOLLOW symlink refusal; frontmatter validation; embeds blog-source-sha256; refuses .html input |
v1.9.0 |
blog_studio_status.py |
Read-only inspector for the saved preflight report's evidence object; prints the status JSON the optional Blog Studio plugin displays (--draft, --project-root, --expected-run) |
v2.3.2 |
check_google_currentness.py |
Checks the reviewed Google update ledger against official machine-readable feeds | Maintenance |
check_secrets.py |
Fails on unadjudicated detect-secrets findings without printing raw values | Maintenance |
cognitive_load.py |
Per-section concept-density analyzer (entities, numerics, jargon, forward refs, clause depth) | v1.8.0 |
consistency_check.py |
Validates repository-local references and FLOW prompt locks | Maintenance |
content_decay.py |
GSC content-decay detector: 20%+ QoQ decline | v1.10.0 |
dependency_smoke.py |
Offline initialization smoke checks for the optional runtimes | Maintenance |
discourse_research.py |
Discourse-brief synthesis from SERP JSON; depth-bounded parsing; path-traversal guards | v1.8.0 |
generate_hero.py |
Hero image ladder: Banana MCP -> Gemini API (only with --allow-paid) -> Unsplash/Pexels/Pixabay -> Openverse; keeps a valid existing hero |
v1.9.0 |
installer_ownership.py |
Shared Unix legacy/v2 ownership verification, migration and rollback | v2.3.0 |
lint_prose.py |
Fence-aware prose-hygiene linter (no em-dash, en-dash, --); CI-enforced |
v1.8.4 |
load_untrusted_root.py |
Code-enforced BRAND/VOICE/DISCOURSE fencing with CSPRNG nonces; O_NOFOLLOW + size cap | v1.8.3 |
quality_gate.py |
Pre-commit gate: block posts scoring < 70; fail-closed on bad paths and missing frontmatter; --select is the pre-commit hook mode that skips Markdown files that are not blog posts |
v1.10.0 |
style_learn.py |
Author voice-profile learner from sample posts | v1.10.0 |
sync_flow.py |
Pulls FLOW reference prompts from upstream; sandboxed; stdlib-only | v1.7.0 |
sync_google_updates.py |
Synchronizes the canonical Google update ledger into the Blog Brain | Maintenance |
validate_public_release.py |
Read-only validation of a prepared public worktree | Maintenance |
validate_skills.py |
Real-YAML validation of skill and agent frontmatter plus the maintained bundle contract | Maintenance |
Data Flow
Write Flow
/blog write "topic"
|
v
Orchestrator (skills/blog/SKILL.md)
|
+-- Loads: references/content-rules.md
| references/visual-media.md
| templates/[auto-selected].md
|
+-- Spawns: blog-researcher agent
| |
| +-- WebSearch: finds evidence for material claims
| +-- WebSearch: finds useful licensed visual evidence
| +-- WebFetch: verifies sources and URLs
| +-- Returns: structured research data
|
+-- Presents outline for user approval
|
+-- Invokes: blog-chart when a chart explains the data
|
+-- Spawns: blog-writer agent
| |
| +-- Writes full article with:
| | - Answer-first formatting
| | - Sourced statistics
| | - Image embeds
| | - Chart embeds
| | - Q&A only when it answers reader questions
| +-- Returns: complete article (draft-only markers allowed)
|
+-- Quality verification (5 categories, 100 points)
|
+-- 5-gate Blog Delivery Contract, canonical sequence
| 1 Draft D/S.md (markers allowed)
| 2 Visuals orchestrator resolves every marker, hero, charts
| 3 Render blog_render.py -> S.html + S.pdf (blog-source-sha256)
| 4 Nonce blog_preflight.py --init-review-nonce (stores digests)
| 5 Review blog-reviewer; orchestrator saves review.md verbatim
| 6 Gates blog_preflight.py --draft D --strict
| 7 Loop any edit => re-render, re-nonce, re-review; max 3x
| If any gate BLOCKS: iterate up to 3x then escalate to user
|
+-- Writes file to user's project
|
v
Delivery summary: md, html, pdf, hero, 3 viewport screenshots plus a dark-mode
screenshot (preview/), review.md, preflight-report.json
The authoritative sequence and the full list of what each gate enforces live
once, in skills/blog/references/blog-delivery-contract.md. This file does not
repeat them: when the two disagree, the contract wins.
Analyze Flow
/blog analyze "file.md"
|
v
Orchestrator --> blog-analyze sub-skill
|
+-- Reads target file
|
+-- Loads: references/quality-scoring.md
|
+-- Runs: analyze_blog.py (if Python available)
| |
| +-- Returns: JSON metrics
|
+-- Manual scoring (5 categories, 100 points)
|
+-- Generates prioritized recommendations
|
v
Quality report with score and action items
On-Demand Reference Loading (RAG Pattern)
Reference files are NOT preloaded into context. The orchestrator and sub-skills load them selectively based on the current task:
Task References Loaded
---- -----------------
/blog write content-rules, visual-media, quality-scoring
/blog rewrite content-rules, quality-scoring
/blog analyze quality-scoring
/blog brief content-rules, geo-optimization
/blog strategy geo-optimization, google-landscape-2026
/blog geo geo-optimization, ai-crawler-guide
/blog schema schema-stack
/blog seo-check google-landscape-2026, schema-stack
This pattern keeps context usage efficient. Only the knowledge relevant to the current operation is loaded.
Scoring Methodology
Blog quality is measured across 5 categories totaling 100 points. The
analyze_blog.py script and the blog-analyze sub-skill both use this
framework.
Category Weights
Content Quality (30 pts) ############################--
SEO Signals (25 pts) #########################-----
E-E-A-T (15 pts) ###############---------------
Technical (15 pts) ###############---------------
AI Citation (15 pts) ###############---------------
| | | | | |
0 20 40 60 80 100
Scoring Bands
| Score | Rating | Action |
|---|---|---|
| 90-100 | Exceptional | Eligible for delivery review; all gates must still pass |
| 80-89 | Strong | Minor tweaks; orchestrator iterates if Gate 4 wants 90+ |
| 70-79 | Acceptable | Notable gaps; iterate |
| 60-69 | Below Standard | Significant improvements required |
| < 60 | Rewrite | Full rewrite recommended |
The standalone quality gate uses a configurable default threshold of 70.
Delivery separately requires reviewer score >=90, explicit zero uncleared P0
issues, a matching nonce on files unchanged since the nonce was issued, a valid
final nonblocking decision, and all five preflight gates (full list in
blog-delivery-contract.md). An analyzer score alone cannot authorize delivery.
Advisory style and length observations do not block delivery or infer
authorship. Integrity and safety failures remain blocking.
Quality Gates (Hard Rules)
These are non-negotiable. Content violating any of these must not be published:
| Gate | Threshold |
|---|---|
| Fabricated statistics | Zero tolerance |
| Paragraph clarity | Review in context; no fixed length gate |
| Heading hierarchy | Never skip levels (H1 > H2 > H3); one H1; checked by Gate 2 |
| Source tier | Tier 1-3 only |
| Image alt text | Required on all images; a missing alt is a Gate 2 violation |
| Self-promotion | Keep mentions useful to the reader and disclose commercial context |
| Chart selection | Use the clearest chart for the evidence, without a fixed quota |
Platform Detection
The orchestrator auto-detects the blog platform from project signals:
| Signal | Platform | Output Format |
|---|---|---|
.mdx files + next.config |
Next.js/MDX | JSX-compatible markdown |
.md files + hugo.toml |
Hugo | Standard markdown |
.md files + _config.yml |
Jekyll | Markdown with YAML front matter |
.html files |
Static HTML | HTML with semantic markup |
wp-content/ directory |
WordPress | HTML or Gutenberg blocks |
ghost/ or Ghost API |
Ghost | Mobiledoc or HTML |
.astro files |
Astro | MDX or markdown |
| No signals detected | Default | Standard markdown |
Platform detection affects:
- Frontmatter format and field names
- Image embedding syntax (markdown vs
<Image>component) - Chart embedding format (HTML SVG vs JSX SVG with camelCase)
- Schema injection method
File Naming Conventions
| Component | Location | Naming |
|---|---|---|
| Main skill | skills/blog/SKILL.md |
Fixed name |
| Sub-skills | skills/blog-<command>/SKILL.md |
Prefix blog- + command name |
| Agents | agents/blog-<role>.md |
Prefix blog- + role name |
| References | skills/blog/references/<topic>.md |
Kebab-case topic name |
| Templates | skills/blog/templates/<type>.md |
Kebab-case content type |
| Scripts | scripts/<name>.py |
Snake-case script name |
Extension Points
Adding a New Command
- Create
skills/blog-<name>/SKILL.mdwith YAML frontmatter - Add routing logic to
skills/blog/SKILL.mdorchestrator - Update
install.shandinstall.ps1to copy the new sub-skill - Update
uninstall.shto remove it
Adding a New Agent
- Create
agents/blog-<role>.mdwith YAML frontmatter - Define the tool set (keep it minimal for the role)
- Reference the agent from sub-skills that need it
Adding a New Reference
- Create
skills/blog/references/<topic>.md - Document when to load it in the orchestrator
- Update
install.shto copy the new reference file
Adding a New Template
- Create
skills/blog/templates/<type>.md - Define section structure, markers, and word count targets
- Add template selection logic to
blog-write
Installed Directory Tree
After installation, claude-blog occupies this structure inside ~/.claude/:
~/.claude/
├── skills/
│ ├── blog/
│ │ ├── SKILL.md # Main orchestrator
│ │ ├── references/
│ │ │ ├── ai-crawler-guide.md
│ │ │ ├── content-rules.md
│ │ │ ├── content-templates.md
│ │ │ ├── distribution-playbook.md
│ │ │ ├── eeat-signals.md
│ │ │ ├── geo-optimization.md
│ │ │ ├── google-landscape-2026.md
│ │ │ ├── internal-linking.md
│ │ │ ├── platform-guides.md
│ │ │ ├── quality-scoring.md
│ │ │ ├── schema-stack.md
│ │ │ └── visual-media.md
│ │ ├── templates/
│ │ │ ├── how-to-guide.md
│ │ │ ├── listicle.md
│ │ │ ├── case-study.md
│ │ │ ├── comparison.md
│ │ │ ├── pillar-page.md
│ │ │ ├── product-review.md
│ │ │ ├── thought-leadership.md
│ │ │ ├── roundup.md
│ │ │ ├── tutorial.md
│ │ │ ├── news-analysis.md
│ │ │ ├── data-research.md
│ │ │ └── faq-knowledge.md
│ │ └── scripts/
│ │ └── analyze_blog.py
│ ├── blog-write/SKILL.md
│ ├── blog-rewrite/SKILL.md
│ ├── blog-analyze/SKILL.md
│ ├── blog-brief/SKILL.md
│ ├── blog-calendar/SKILL.md
│ ├── blog-strategy/SKILL.md
│ ├── blog-outline/SKILL.md
│ ├── blog-seo-check/SKILL.md
│ ├── blog-schema/SKILL.md
│ ├── blog-repurpose/SKILL.md
│ ├── blog-geo/SKILL.md
│ ├── blog-audit/SKILL.md
│ ├── blog-chart/SKILL.md # internal-only (SVG generation)
│ ├── blog-image/SKILL.md # v1.4.0
│ ├── blog-cannibalization/SKILL.md
│ ├── blog-factcheck/SKILL.md
│ ├── blog-persona/SKILL.md
│ ├── blog-taxonomy/SKILL.md
│ ├── blog-notebooklm/SKILL.md # v1.5.0
│ ├── blog-audio/SKILL.md # v1.6.0
│ ├── blog-google/SKILL.md # v1.6.5
│ ├── blog-cluster/SKILL.md # v1.7.0
│ ├── blog-flow/SKILL.md # v1.7.0
│ ├── blog-multilingual/SKILL.md # v1.7.0
│ ├── blog-translate/SKILL.md # v1.7.0
│ ├── blog-localize/SKILL.md # v1.7.0
│ ├── blog-locale-audit/SKILL.md # v1.7.0
│ ├── blog-brand/SKILL.md # v1.8.0
│ ├── blog-discourse/SKILL.md # v1.8.0
│ ├── blog-style/SKILL.md # v1.10.0
│ └── blog-decay/SKILL.md # v1.10.0
└── agents/
├── blog-researcher.md
├── blog-writer.md
├── blog-seo.md
├── blog-reviewer.md
└── blog-translator.md # v1.7.0
Component counts: 32 skill directories (1 orchestrator + 31 sub-skills);
30 user-facing commands (blog-chart is internal); 5 agents (blog-researcher,
blog-writer, blog-seo, blog-reviewer, blog-translator); 22 references in
skills/blog/references/ (plus per-sub-skill references and the synced FLOW
prompts under skills/blog-flow/references/); 12 content templates; 22
root-level Python scripts (the table in section 6; ls scripts/*.py | wc -l)
plus per-sub-skill scripts under blog-google/, blog-notebooklm/,
blog-audio/, blog-image/ and blog-flow/. Only the reference
count is asserted by a test (test_reference_count_coherence); the other
numbers are maintained by hand, so verify them with ls before relying on
them. The test count is deliberately not quoted here (run
python3 -m pytest --collect-only -q | tail -1).
v1.8.0+ adds three project-root context files (BRAND.md / VOICE.md /
DISCOURSE.md, auto-loaded via scripts/load_untrusted_root.py with
CSPRNG nonce fencing). v1.8.4+ enforces prose hygiene and version
coherence via CI (see scripts/lint_prose.py, tests/test_version_coherence.py).
v1.9.0 adds the 5-gate Blog Delivery Contract (see
skills/blog/references/blog-delivery-contract.md) and a pytest suite that
includes mutation-test-verified XSS, symlink, and frontmatter regression
coverage.
Installed resource paths
Consumer skills resolve bundled resources from host Markdown substitution
${CLAUDE_SKILL_DIR}, which is not an ordinary exported shell variable.
Shared helpers live at ../../scripts, siblings at .., main references at
../blog/references, and own helpers at scripts beneath that anchor. These
relationships hold in repository/plugin and standalone layouts. Explicit
absolute CLAUDE_BLOG_* overrides take precedence; relative overrides fail.
No executable helper or reviewed reference falls back to the consumer CWD or
a default global profile. The orchestrator passes resolved absolute roots and
fenced context into agents; root CLAUDE.md is developer-only plugin context.
Writable optional integration state remains a separate migration concern.