How agricidaniel/claude-blog works
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: blog/SKILL.md Blog router · blog-delivery-contract.md Delivery contract · blog-flow/SKILL.md Flow · plugin.json Plugin config
Components 24
Packaging
Plugin metadata and install scripts that register the skill package.
- Plugin config · Claude plugin entry metadata for packaging and discovery.
.claude-plugin/plugin.json - Install · Shell installer for setting up the skill package.
install.sh - Install PS · PowerShell installer for Windows environments.
install.ps1
Orchestration
Top-level command router and shared editorial policy.
- Blog router · Top-level /blog command dispatcher and workflow entry point.
skills/blog/SKILL.md - Delivery contract · Core 5-gate quality contract for blog output.
skills/blog/references/blog-delivery-contract.md - Content rules · Shared writing and formatting rules consumed across skills.
skills/blog/references/content-rules.md - Reviewer · Blocking editorial reviewer used to enforce the delivery contract.
agents/blog-reviewer.md - Researcher · Specialized research agent for sourcing and synthesis.
agents/blog-researcher.md
Capabilities
Primary skill modules exposed as blog commands.
- Write · Primary drafting workflow for long-form blog content.
skills/blog-write/SKILL.md - Rewrite · Transforms and refines existing drafts.
skills/blog-rewrite/SKILL.md - Analyze · Content analysis and diagnostic command.
skills/blog-analyze/SKILL.md - Flow · Research-to-publish workflow and prompt framework.
skills/blog-flow/SKILL.md - SEO check · Search optimization and audit capability.
skills/blog-seo-check/SKILL.md - Translate · Translation and adaptation workflow.
skills/blog-translate/SKILL.md
Backends
Python helpers that execute rendering, validation, and research work.
- Preflight · Checks content readiness before delivery.
scripts/blog_preflight.py - Render · Produces final deliverable formats and artifacts.
scripts/blog_render.py - Hero gen · Creates hero imagery and visual assets.
scripts/generate_hero.py - Research · Discourse and research helper backend.
scripts/discourse_research.py
Quality
Review gates, tests, and CI guardrails.
- Contract test · Regression coverage for delivery contract behavior.
tests/test_blog_delivery_contract.py - CI · Repository-wide continuous integration checks.
.github/workflows/ci.yml
Integrations
Capability modules that connect to external services or tools.
- Google · Google search, indexing, analytics, and performance workflows.
skills/blog-google/SKILL.md - Audio · Narration and TTS generation workflow.
skills/blog-audio/SKILL.md - Image · Image-generation and MCP setup workflow.
skills/blog-image/SKILL.md - NotebookLM · Browser-assisted research and question answering workflow.
skills/blog-notebooklm/SKILL.md
Connections 34
- 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.