# agricidaniel/claude-blog architecture

> Architecture diagram of the GitHub repository agricidaniel/claude-blog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agricidaniel/claude-blog
- Repository: https://github.com/agricidaniel/claude-blog

## Overview

1. **What this repository is**
   - `claude-blog` is not a traditional application server; it is a **Claude Code skill package** made of Markdown skill definitions, agent prompts, Python helper scripts, templates, and tests.
   - The architecture is centered on **command routing** inside Claude Code, with the repo acting as a content-production toolkit for blog writing, SEO, review, and publishing support.

2. **Primary entry points**
   - The user-facing entry points are the `/blog ...` commands defined in `skills/blog/SKILL.md` and the many sub-skill directories under `skills/`.
   - Installation and packaging are handled by `install.sh`, `install.ps1`, `uninstall.*`, and the plugin metadata in `.claude-plugin/` plus `plugin.json`.
   - This means the repo’s runtime boundary is mostly **Claude Code + local filesystem + Python**, not a long-running service.

3. **Orchestration layer**
   - `skills/blog/SKILL.md` is the top-level orchestrator that dispatches work to sub-skills like `blog-write`, `blog-rewrite`, `blog-analyze`, `blog-brief`, `blog-flow`, `blog-google`, and others.
   - The orchestrator drives a **pipeline-style workflow**: research, drafting, template selection, media generation, validation, and final review.
   - The user does not interact with lower-level helpers directly in normal use; those helpers are invoked by the orchestrator or by individual sub-skills.

4. **Delivery contract as the main quality boundary**
   - The key architectural boundary is the **5-gate Blog Delivery Contract** described in the README and codified by `scripts/blog_preflight.py`, `scripts/blog_render.py`, `scripts/generate_hero.py`, and `agents/blog-reviewer.md`.
   - Content must pass capability checks, format checks, visual checks, a blocking review gate, and asset/link integrity checks before it is returned.
   - This is the repo’s core control loop: **iterate up to 3 times on failure, then escalate to the user**.

5. **Agent layer**
   - The repo includes five specialized agents in `agents/`, such as `blog-researcher.md`, `blog-writer.md`, `blog-reviewer.md`, `blog-seo.md`, and `blog-translator.md`.
   - These agents represent distinct editorial roles and are used as **delegated reasoning boundaries**: research, write, review, optimize, translate.
   - `blog-reviewer` is especially important because it is a **blocking gate**, not just advisory text.

6. **Skill modularity and domain separation**
   - The large `skills/` tree is the main subsystem decomposition. Each directory is a capability module, typically with its own `SKILL.md`, sometimes references, scripts, or assets.
   - Major clusters include:
     - **Core writing workflow**: `blog-write`, `blog-rewrite`, `blog-outline`, `blog-brief`, `blog-strategy`, `blog-analyze`
     - **SEO and audit**: `blog-seo-check`, `blog-cannibalization`, `blog-factcheck`, `blog-geo`, `blog-audit`
     - **Localization/multilingual**: `blog-translate`, `blog-localize`, `blog-multilingual`, `blog-locale-audit`
     - **Research and planning**: `blog-discourse`, `blog-cluster`, `blog-calendar`, `blog-persona`
     - **Media and distribution**: `blog-image`, `blog-audio`, `blog-repurpose`, `blog-chart`
   - `blog-chart` is explicitly internal-only, while most others are user-invokable commands.

7. **Shared references and editorial rules**
   - The shared knowledge base lives under `skills/blog/references/`.
   - These documents define the editorial rules and scoring models used across multiple sub-skills: AI slop detection, cognitive load, research quality, synthesis constraints, internal linking, schema guidance, and content templates.
   - Architecturally, this is a **policy layer**: the skills consume these references on demand instead of duplicating logic across every command.

8. **Templates and output shaping**
   - `skills/blog/templates/` contains the content archetypes the system emits, such as how-to, listicle, comparison, case study, tutorial, pillar page, and FAQ.
   - Template selection is part of the content pipeline and affects the final structure of generated articles.
   - The repository also ships generated visual assets and diagrams in `assets/` and `branding/`, which support documentation and brand consistency rather than runtime logic.

9. **Python helper scripts as execution backends**
   - The root `scripts/` directory contains the operational backend for the skills: preflight checks, rendering, hero generation, discourse research, cognitive-load analysis, prose linting, and sync/load helpers.
   - These scripts are the bridge between Markdown-driven skill instructions and concrete file generation or validation.
   - Sub-skill-specific script folders, especially under `skills/blog-google/scripts/`, `skills/blog-audio/scripts/`, and `skills/blog-notebooklm/scripts/`, show that some capabilities are fully packaged mini-subsystems with their own dependencies and runners.

10. **External integrations that materially shape the architecture**
   - `blog-google` integrates with Google services such as PageSpeed Insights, Search Console, GA4, CrUX, Indexing API, Keyword Planner, NLP, and YouTube.
   - `blog-notebooklm` is a separate research path that relies on NotebookLM sessions and browser automation helpers.
   - `blog-image` ties into image-generation/MCP tooling, and `blog-audio` uses Gemini TTS for narration.
   - These integrations are optional capability modules, not hard dependencies of the whole repo, but they expand the pipeline’s output types.

11. **File-based artifact flow**
   - The system is artifact-driven: blog generation yields markdown, HTML, PDF, hero images, screenshots, review reports, and preflight audit data in the filesystem.
   - The README implies a deterministic handoff from content generation to rendering and validation, with files acting as the integration contract between stages.
   - There is no central database or message queue; the main state boundary is the **workspace directory and generated files**.

12. **Testing, policy, and release guardrails**
   - `tests/` enforces command coherence, version coherence, security rules, installer behavior, and regression coverage around the delivery contract.
   - CI in `.github/workflows/ci.yml` validates the package, prose hygiene, plugin structure, and the repo’s internal consistency.
   - This repo is therefore architected as a **self-validating skill distribution**: content generation is paired with repository-level checks to keep the Markdown, scripts, docs, and release metadata aligned.

Main entry points: [`skills/blog/SKILL.md`](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog/SKILL.md) (Blog router), [`skills/blog/references/blog-delivery-contract.md`](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog/references/blog-delivery-contract.md) (Delivery contract), [`skills/blog-flow/SKILL.md`](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-flow/SKILL.md) (Flow), [`.claude-plugin/plugin.json`](https://github.com/agricidaniel/claude-blog/blob/main/.claude-plugin/plugin.json) (Plugin config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_package["Packaging"]
  node_plugin_json["Plugin config<br/>plugin metadata<br/>[plugin.json]"]
  node_install_sh["Install<br/>[install.sh]"]
  node_install_ps1["Install PS<br/>installer<br/>[install.ps1]"]
end

subgraph group_orchestration["Orchestration"]
  node_blog_skill["Blog router<br/>skill orchestrator<br/>[SKILL.md]"]
  node_delivery_contract["Delivery contract<br/>policy gate"]
  node_content_rules["Content rules<br/>editorial policy<br/>[content-rules.md]"]
  node_reviewer_agent["Reviewer<br/>agent gate<br/>[blog-reviewer.md]"]
  node_researcher_agent["Researcher<br/>agent role<br/>[blog-researcher.md]"]
end

subgraph group_capabilities["Capabilities"]
  node_blog_write["Write<br/>writing skill<br/>[SKILL.md]"]
  node_blog_rewrite["Rewrite<br/>revision skill<br/>[SKILL.md]"]
  node_blog_analyze["Analyze<br/>analysis skill<br/>[SKILL.md]"]
  node_blog_flow["Flow<br/>planning skill<br/>[SKILL.md]"]
  node_blog_seo_check["SEO check<br/>seo skill<br/>[SKILL.md]"]
  node_blog_translate["Translate<br/>localization skill<br/>[SKILL.md]"]
end

subgraph group_backend["Backends"]
  node_preflight["Preflight<br/>validator<br/>[blog_preflight.py]"]
  node_render["Render<br/>[blog_render.py]"]
  node_hero["Hero gen<br/>asset generator<br/>[generate_hero.py]"]
  node_discourse["Research"]
end

subgraph group_quality["Quality"]
  node_tests_contract["Contract test<br/>test suite"]
  node_ci["CI<br/>workflow<br/>[ci.yml]"]
end

subgraph group_integrations["Integrations"]
  node_blog_google["Google<br/>integration skill<br/>[SKILL.md]"]
  node_blog_audio["Audio<br/>media skill<br/>[SKILL.md]"]
  node_blog_image["Image<br/>media skill<br/>[SKILL.md]"]
  node_blog_notebooklm["NotebookLM<br/>research skill<br/>[SKILL.md]"]
end

node_plugin_json -->|"registers"| node_blog_skill
node_install_sh -->|"installs"| node_plugin_json
node_install_ps1 -->|"installs"| node_plugin_json
node_blog_skill -->|"dispatches"| node_blog_write
node_blog_skill -->|"dispatches"| node_blog_rewrite
node_blog_skill -->|"dispatches"| node_blog_analyze
node_blog_skill -->|"dispatches"| node_blog_flow
node_blog_skill -->|"dispatches"| node_blog_seo_check
node_blog_skill -->|"dispatches"| node_blog_translate
node_blog_skill -->|"dispatches"| node_blog_google
node_blog_skill -->|"dispatches"| node_blog_audio
node_blog_skill -->|"dispatches"| node_blog_image
node_blog_skill -->|"dispatches"| node_blog_notebooklm
node_blog_skill -->|"depends on"| node_delivery_contract
node_blog_skill -->|"uses"| node_content_rules
node_blog_skill -->|"gates through"| node_reviewer_agent
node_blog_skill -->|"delegates"| node_researcher_agent
node_reviewer_agent -->|"enforces"| node_delivery_contract
node_preflight -->|"checks"| node_delivery_contract
node_render -->|"feeds"| node_delivery_contract
node_hero -->|"supports"| node_render
node_discourse -->|"supports"| node_researcher_agent
node_blog_flow -->|"orchestrates"| node_preflight
node_blog_flow -->|"orchestrates"| node_render
node_blog_flow -->|"orchestrates"| node_discourse
node_blog_google -->|"uses"| node_preflight
node_blog_google -->|"produces"| node_render
node_blog_audio -->|"produces"| node_hero
node_blog_image -->|"produces"| node_hero
node_blog_notebooklm -.->|"resembles"| node_discourse
node_tests_contract -->|"verifies"| node_delivery_contract
node_ci -->|"runs"| node_tests_contract
node_ci -->|"validates"| node_plugin_json
node_ci -->|"validates"| node_install_sh

click node_plugin_json "https://github.com/agricidaniel/claude-blog/blob/main/.claude-plugin/plugin.json"
click node_install_sh "https://github.com/agricidaniel/claude-blog/blob/main/install.sh"
click node_install_ps1 "https://github.com/agricidaniel/claude-blog/blob/main/install.ps1"
click node_blog_skill "https://github.com/agricidaniel/claude-blog/blob/main/skills/blog/SKILL.md"
click node_delivery_contract "https://github.com/agricidaniel/claude-blog/blob/main/skills/blog/references/blog-delivery-contract.md"
click node_content_rules "https://github.com/agricidaniel/claude-blog/blob/main/skills/blog/references/content-rules.md"
click node_blog_write "https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-write/SKILL.md"
click node_blog_rewrite "https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-rewrite/SKILL.md"
click node_blog_analyze "https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-analyze/SKILL.md"
click node_blog_flow "https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-flow/SKILL.md"
click node_blog_seo_check "https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-seo-check/SKILL.md"
click node_blog_translate "https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-translate/SKILL.md"
click node_blog_google "https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-google/SKILL.md"
click node_blog_audio "https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-audio/SKILL.md"
click node_blog_image "https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-image/SKILL.md"
click node_blog_notebooklm "https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-notebooklm/SKILL.md"
click node_reviewer_agent "https://github.com/agricidaniel/claude-blog/blob/main/agents/blog-reviewer.md"
click node_researcher_agent "https://github.com/agricidaniel/claude-blog/blob/main/agents/blog-researcher.md"
click node_preflight "https://github.com/agricidaniel/claude-blog/blob/main/scripts/blog_preflight.py"
click node_render "https://github.com/agricidaniel/claude-blog/blob/main/scripts/blog_render.py"
click node_hero "https://github.com/agricidaniel/claude-blog/blob/main/scripts/generate_hero.py"
click node_discourse "https://github.com/agricidaniel/claude-blog/blob/main/scripts/discourse_research.py"
click node_tests_contract "https://github.com/agricidaniel/claude-blog/blob/main/tests/test_blog_delivery_contract.py"
click node_ci "https://github.com/agricidaniel/claude-blog/blob/main/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin_json,node_install_sh,node_install_ps1 toneBlue
class node_blog_skill,node_delivery_contract,node_content_rules,node_reviewer_agent,node_researcher_agent toneAmber
class node_blog_write,node_blog_rewrite,node_blog_analyze,node_blog_flow,node_blog_seo_check,node_blog_translate toneMint
class node_preflight,node_render,node_hero,node_discourse toneRose
class node_tests_contract,node_ci toneIndigo
class node_blog_google,node_blog_audio,node_blog_image,node_blog_notebooklm toneTeal
```

## Components

### Packaging

Plugin metadata and install scripts that register the skill package.

- [Plugin config](https://github.com/agricidaniel/claude-blog/blob/main/.claude-plugin/plugin.json): plugin metadata · Claude plugin entry metadata for packaging and discovery. · `.claude-plugin/plugin.json`
- [Install](https://github.com/agricidaniel/claude-blog/blob/main/install.sh): installer · Shell installer for setting up the skill package. · `install.sh`
- [Install PS](https://github.com/agricidaniel/claude-blog/blob/main/install.ps1): installer · PowerShell installer for Windows environments. · `install.ps1`

### Orchestration

Top-level command router and shared editorial policy.

- [Blog router](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog/SKILL.md): skill orchestrator · Top-level /blog command dispatcher and workflow entry point. · `skills/blog/SKILL.md`
- [Delivery contract](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog/references/blog-delivery-contract.md): policy gate · Core 5-gate quality contract for blog output. · `skills/blog/references/blog-delivery-contract.md`
- [Content rules](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog/references/content-rules.md): editorial policy · Shared writing and formatting rules consumed across skills. · `skills/blog/references/content-rules.md`
- [Reviewer](https://github.com/agricidaniel/claude-blog/blob/main/agents/blog-reviewer.md): agent gate · Blocking editorial reviewer used to enforce the delivery contract. · `agents/blog-reviewer.md`
- [Researcher](https://github.com/agricidaniel/claude-blog/blob/main/agents/blog-researcher.md): agent role · Specialized research agent for sourcing and synthesis. · `agents/blog-researcher.md`

### Capabilities

Primary skill modules exposed as blog commands.

- [Write](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-write/SKILL.md): writing skill · Primary drafting workflow for long-form blog content. · `skills/blog-write/SKILL.md`
- [Rewrite](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-rewrite/SKILL.md): revision skill · Transforms and refines existing drafts. · `skills/blog-rewrite/SKILL.md`
- [Analyze](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-analyze/SKILL.md): analysis skill · Content analysis and diagnostic command. · `skills/blog-analyze/SKILL.md`
- [Flow](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-flow/SKILL.md): planning skill · Research-to-publish workflow and prompt framework. · `skills/blog-flow/SKILL.md`
- [SEO check](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-seo-check/SKILL.md): seo skill · Search optimization and audit capability. · `skills/blog-seo-check/SKILL.md`
- [Translate](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-translate/SKILL.md): localization skill · Translation and adaptation workflow. · `skills/blog-translate/SKILL.md`

### Backends

Python helpers that execute rendering, validation, and research work.

- [Preflight](https://github.com/agricidaniel/claude-blog/blob/main/scripts/blog_preflight.py): validator · Checks content readiness before delivery. · `scripts/blog_preflight.py`
- [Render](https://github.com/agricidaniel/claude-blog/blob/main/scripts/blog_render.py): renderer · Produces final deliverable formats and artifacts. · `scripts/blog_render.py`
- [Hero gen](https://github.com/agricidaniel/claude-blog/blob/main/scripts/generate_hero.py): asset generator · Creates hero imagery and visual assets. · `scripts/generate_hero.py`
- [Research](https://github.com/agricidaniel/claude-blog/blob/main/scripts/discourse_research.py): research backend · Discourse and research helper backend. · `scripts/discourse_research.py`

### Quality

Review gates, tests, and CI guardrails.

- [Contract test](https://github.com/agricidaniel/claude-blog/blob/main/tests/test_blog_delivery_contract.py): test suite · Regression coverage for delivery contract behavior. · `tests/test_blog_delivery_contract.py`
- [CI](https://github.com/agricidaniel/claude-blog/blob/main/.github/workflows/ci.yml): workflow · Repository-wide continuous integration checks. · `.github/workflows/ci.yml`

### Integrations

Capability modules that connect to external services or tools.

- [Google](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-google/SKILL.md): integration skill · Google search, indexing, analytics, and performance workflows. · `skills/blog-google/SKILL.md`
- [Audio](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-audio/SKILL.md): media skill · Narration and TTS generation workflow. · `skills/blog-audio/SKILL.md`
- [Image](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-image/SKILL.md): media skill · Image-generation and MCP setup workflow. · `skills/blog-image/SKILL.md`
- [NotebookLM](https://github.com/agricidaniel/claude-blog/blob/main/skills/blog-notebooklm/SKILL.md): research skill · Browser-assisted research and question answering workflow. · `skills/blog-notebooklm/SKILL.md`

## Connections

- Plugin config → Blog router: registers · Plugin metadata exposes the skill package to Claude Code.
- Install → Plugin config: installs · Shell installer sets up plugin and skill wiring.
- Install PS → Plugin config: installs · Windows installer sets up plugin and skill wiring.
- Blog router → Write: dispatches · Top-level command routes into the core writing skill.
- Blog router → Rewrite: dispatches · Top-level command routes into rewrite workflows.
- Blog router → Analyze: dispatches · Top-level command routes into analysis workflows.
- Blog router → Flow: dispatches · Top-level command routes into planning and research flow.
- Blog router → SEO check: dispatches · Top-level command routes into SEO review workflows.
- Blog router → Translate: dispatches · Top-level command routes into localization workflows.
- Blog router → Google: dispatches · Top-level command routes into Google-backed capabilities.
- Blog router → Audio: dispatches · Top-level command routes into audio output workflows.
- Blog router → Image: dispatches · Top-level command routes into visual asset workflows.
- Blog router → NotebookLM: dispatches · Top-level command routes into NotebookLM-backed research.
- Blog router → Delivery contract: depends on · The orchestrator enforces the delivery contract before release.
- Blog router → Content rules: uses · The orchestrator relies on shared editorial rules and heuristics.
- Blog router → Reviewer: gates through · Final output must pass the blocking reviewer.
- Blog router → Researcher: delegates · Research tasks are delegated to a specialized agent.
- Reviewer → Delivery contract: enforces · Reviewer implements the blocking quality boundary.
- Preflight → Delivery contract: checks · Preflight validates capability, format, visual, review, and asset gates.
- Render → Delivery contract: feeds · Rendering produces artifacts consumed by the contract gates.
- Hero gen → Render: supports · Hero assets are part of the rendering pipeline.
- Research → Researcher: supports · Research backend supplies source gathering and synthesis.
- Flow → Preflight: orchestrates · Flow uses preflight checks as part of the pipeline.
- Flow → Render: orchestrates · Flow stages content into final renderable artifacts.
- Flow → Research: orchestrates · Flow incorporates research backends for discovery.
- Google → Preflight: uses · Google workflows depend on validation before reporting.
- Google → Render: produces · Google workflows generate report-style artifacts.
- Audio → Hero gen: produces · Audio workflow can accompany final content assets.
- Image → Hero gen: produces · Image workflow feeds visual asset generation.
- NotebookLM → Research: resembles · NotebookLM workflow acts as a research path adjacent to discourse research.
- Contract test → Delivery contract: verifies · Test suite guards the core delivery contract behavior.
- CI → Contract test: runs · CI executes contract and regression tests.
- CI → Plugin config: validates · CI checks plugin structure and package coherence.
- CI → Install: validates · CI covers installer and release wiring.