Skip to content

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.

25.7 KB
Raw Blame

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.py using real YAML with duplicate-key rejection. Native user-invocable defaults to true; explicit booleans, name/directory agreement and size caps are project policy. allowed-tools is valid host permission preapproval metadata, but this bundle deliberately ships no preapprovals. Agent tools is 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

  1. Create skills/blog-<name>/SKILL.md with YAML frontmatter
  2. Add routing logic to skills/blog/SKILL.md orchestrator
  3. Update install.sh and install.ps1 to copy the new sub-skill
  4. Update uninstall.sh to remove it

Adding a New Agent

  1. Create agents/blog-<role>.md with YAML frontmatter
  2. Define the tool set (keep it minimal for the role)
  3. Reference the agent from sub-skills that need it

Adding a New Reference

  1. Create skills/blog/references/<topic>.md
  2. Document when to load it in the orchestrator
  3. Update install.sh to copy the new reference file

Adding a New Template

  1. Create skills/blog/templates/<type>.md
  2. Define section structure, markers, and word count targets
  3. 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.