AI Blog Writing & SEO Optimization Skill for Claude Code (claude-blog)

<p align="center"> <img src="assets/cover-blog.svg" alt="Claude Blog cover: AI blog writing, SEO optimization, AI citation readiness, and a 5-gate delivery contract for Claude Code" width="100%"> </p> <p align="center"> <a href="https://agentskills.io"><img src="https://img.shields.io/badge/Agent%20Skills-Compatible-blue" alt="Agent Skill"></a> <a href="https://github.com/AgriciDaniel/claude-blog/releases"><img src="https://img.shields.io/github/v/release/AgriciDaniel/claude-blog?label=public%20release" alt="Version"></a> <a href="https://github.com/AgriciDaniel/claude-blog/actions"><img src="https://img.shields.io/github/actions/workflow/status/AgriciDaniel/claude-blog/ci.yml?branch=main&label=public%20CI" alt="CI"></a> <a href="https://github.com/AgriciDaniel/claude-blog/stargazers"><img src="https://img.shields.io/github/stars/AgriciDaniel/claude-blog?style=social" alt="GitHub stars"></a> <a href="https://github.com/AgriciDaniel/claude-blog/discussions"><img src="https://img.shields.io/badge/Community-GitHub%20Discussions-blue" alt="GitHub Discussions"></a> <img src="https://img.shields.io/badge/License-MIT-green" alt="License: MIT"> <img src="https://img.shields.io/badge/Python-3.11%2B-blue" alt="Python 3.11+"> <img src="https://img.shields.io/badge/Skill%20Dirs-32-orange" alt="Skill directories: 32"> <img src="https://img.shields.io/badge/Sub--Skills-31-orange" alt="Sub-skills: 31"> <img src="https://img.shields.io/badge/Commands-30-blueviolet" alt="User-facing commands: 30"> <img src="https://img.shields.io/badge/Tests-250%2B%20passing-brightgreen" alt="Tests: more than 250 passing"> </p>

claude-blog is a Claude Code skill suite that writes, optimizes, audits, localizes, and refreshes blog content at scale. Every article is evaluated for Google-aligned usefulness and internal AI citation readiness heuristics. Version 2.2.0 was prepared on 2026-08-26.

The core promise is simple: the user is never the first reviewer. A 5-gate Blog Delivery Contract scores every draft against a 100-point rubric, blocks delivery below 90, verifies artifacts and links, and iterates up to 3 times before escalation.

This is the public, MIT-licensed distribution at AgriciDaniel/claude-blog. The publishing workflow is documented in docs/PUBLISHING.md.

Blog: See how claude-blog works

<p align="center"> <strong><a href="https://youtu.be/7Q4GaSgUFHo">Watch video on YouTube</a></strong> </p>

Demo

<p align="center"> <img src="assets/blog-command-demo.gif" alt="claude-blog command demo: routing /blog subcommands through the orchestrator" width="100%"> </p> <p align="center"> <img src="assets/blog-write-demo.gif" alt="claude-blog /blog write demo: end-to-end article generation with the 5-gate Delivery Contract" width="100%"> </p>

Watch the original demo on YouTube.

What It Is

claude-blog is a full-lifecycle blog engine for strategy, briefs, outlines, writing, rewriting, analysis, schema, AI citation readiness, site audits, topic clusters, multilingual publishing, audio narration, and content decay detection.

Current v2.2.0 shape: 32 skill directories = 1 orchestrator + 31 sub-skills; 30 user-facing /blog commands (blog-chart is internal, not a command). It also includes 5 specialized agents, repository consistency and public-release validators, 22 core references, 12 templates, a 250+ test suite, and the bundled Claude Blog Brain at ./brain.

Every draft ships as an artifact folder with the markdown source, rendered HTML, PDF, real hero.<ext>, 3 viewport screenshots, review.md, and preflight-report.json. The renderer uses XSS-safe JSON-LD handling, dark-mode-aware CSS, and the same source for every output format.

Who It Is For

Solo bloggers and creators can ship high-quality posts without spending hours on SEO, schema, source checks, and internal linking.

Marketing teams and agencies can run consistent multi-post workflows across brands, languages, authors, and platforms with /blog cluster, /blog multilingual, /blog persona, /blog brand, and /blog discourse.

Claude Code skill builders can study a Tier 4 Agent Skills reference architecture with orchestrator routing, sub-skill dispatch, agent handoffs, code-enforced delivery gates, installer hardening, and CI coherence checks.

Where Should a Claude Code Skill Plugin Install Itself?

Most user-installable Claude Code skill plugins should ship to ~/.claude/skills/<name>/ for skill content, ~/.claude/agents/<name>.md for agents, and ~/.claude/scripts/<helper>.py for Python helpers.

This answer is intentionally kept in the README because it demonstrates the GEO and SEO writing pattern claude-blog produces: answer-first summary, explicit paths, source-ready structure, and a compact FAQ-ready section that AI systems can quote without extra context.

A condensed specimen of a generated article:

---
title: "Where Should a Claude Code Skill Plugin Install Itself?"
description: "A working answer to the install-path question..."
date: "2026-05-18"
author: "Daniel Agrici"
tags: [claude-code, skills, plugins, installation]
canonical: "https://example.com/blog/skill-plugin-install-path"
---

## Where Should a Claude Code Skill Plugin Install Itself?

The short answer: most user-installable Claude Code skill plugins
should ship to `~/.claude/skills/<name>/` for skill content,
`~/.claude/agents/<name>.md` for agents, and
`~/.claude/scripts/<helper>.py` for any Python helpers.

### Key Takeaways
- `~/.claude/skills/` is the SKILL.md surface area.
- `~/.claude/agents/` holds agent markdown files.
- The full article includes sourced citations, FAQ, and schema JSON-LD.

Architecture

<p align="center"> <img src="assets/diagrams/01-architecture-B.svg" alt="claude-blog system architecture: user command through orchestrator routing, sub-skill execution, agent dispatch, scripts, and 5-gate delivery contract" width="100%"> </p>

The orchestrator in skills/blog/SKILL.md parses /blog input, detects the target platform, loads only the references it needs, routes to a sub-skill, and coordinates agents plus scripts through the delivery contract.

| Layer | Count | Where | |---|---:|---| | Skill directories | 32 | skills/blog plus skills/blog-* | | Orchestrator | 1 | skills/blog/SKILL.md | | Sub-skills | 31 | skills/blog-*/SKILL.md | | User-facing /blog commands | 30 | skills/blog/SKILL.md routing table | | Internal-only sub-skill | 1 | skills/blog-chart/SKILL.md | | Specialized agents | 5 | agents/blog-*.md | | Root scripts | 14 | scripts/*.py | | References | 22 | skills/blog/references/*.md | | Templates | 12 | skills/blog/templates/*.md | | Tests | 252 | tests/ |

More architecture detail lives in docs/ARCHITECTURE.md.

5-Gate Delivery Contract

<p align="center"> <img src="assets/diagrams/02-pipeline-B.svg" alt="5-gate Blog Delivery Contract pipeline: Capability Discovery, Format Completeness, Visual Verification, Content Review, Asset and Link Integrity, then user delivery" width="100%"> </p>

Every /blog write and /blog rewrite result must pass the delivery contract before it is shown to the user.

| Gate | Enforces | Implementation | |---|---|---| | 1. Capability Discovery | Required tools, agents, env vars, and optional dependencies are known before writing | scripts/blog_preflight.py --gate 1 | | 2. Format Completeness | .md, .html, .pdf, and a real hero image exist | scripts/blog_render.py, scripts/generate_hero.py | | 3. Visual Verification | Screenshots render at 375, 768, and 1280 widths, JSON-LD is valid, dark mode holds, SVGs do not overflow | patchright or playwright | | 4. Content Review | blog-reviewer score is 90+ with zero P0 issues | agents/blog-reviewer.md | | 5. Asset and Link Integrity | Images resolve, og:image exists, links return 200, word count matches schema within 5% | scripts/blog_preflight.py --gate 5 |

Hero image ladder: Banana MCP, direct Gemini API, premium stock APIs, then Openverse. First working source wins. Full spec: skills/blog/references/blog-delivery-contract.md.

Sub-Skill Ecosystem

<p align="center"> <img src="assets/diagrams/03-sub-skill-map-A.svg" alt="claude-blog sub-skill ecosystem: one orchestrator, 31 sub-skills, 30 user-facing commands, and internal blog-chart support grouped by writing, quality, search, media, multilingual, and distribution workflows" width="100%"> </p>

The ecosystem is intentionally modular. Most commands are user-facing sub-skills. blog-chart is internal-only, and blog-image can be called both by the user and internally by write and rewrite workflows.

Commands

First run: /blog strategy <niche> to scope the site, /blog write <topic> to generate a gated article, and /blog analyze <file-or-url> to score an existing post.

| Command | What it does | |---|---| | /blog write <topic> | Write a new blog post from scratch | | /blog rewrite <file> | Rewrite/optimize an existing blog post | | /blog analyze <file-or-url> | Audit blog quality with 0-100 score | | /blog brief <topic> | Generate a detailed content brief | | /blog calendar [monthly\|quarterly] | Generate an editorial calendar | | /blog strategy <niche> | Blog strategy and topic ideation | | /blog outline <topic> | Generate SERP-informed content outline | | /blog seo-check <file> | Post-writing SEO validation checklist | | /blog schema <file> | Generate JSON-LD schema markup | | /blog repurpose <file> | Repurpose content for other platforms | | /blog geo <file> | AI citation readiness audit | | /blog audit [directory] | Full-site blog health assessment | | /blog cannibalization [dir] | Detect keyword cannibalization across posts | | /blog factcheck <file> | Verify statistics against cited sources | | /blog image [generate\|edit\|setup] | AI image generation and editing via Gemini | | /blog persona [create\|list\|use\|show] | Manage writing personas and voice profiles | | /blog brand [init\|show\|update] | Generate BRAND.md + VOICE.md context files auto-loaded by all sub-skills | | /blog discourse <topic> | Research what people are actually saying about a topic in last 30 days; produces DISCOURSE.md (v1.8.0, API-free) | | /blog taxonomy [suggest\|sync\|audit] | Tag/category management across CMS platforms | | /blog notebooklm <question> | Query NotebookLM for source-grounded research | | /blog audio [generate\|voices\|setup] | Generate audio narration of blog posts | | /blog google [command] [args] | Google API data: PSI, CrUX, GSC, GA4, NLP, YouTube, Keywords | | /blog update <file> | Update existing post with fresh stats (routes to rewrite) | | /blog cluster [plan\|execute] <seed-or-plan> | Semantic topic-cluster planning + execution (hub and spoke) | | /blog multilingual <topic> --languages <codes> | Write + translate + localize + emit hreflang in one command | | /blog translate <file> --to <codes> | SEO-optimized translation with format preservation | | /blog localize <file> --locale <code> | Cultural deep-adaptation (DACH, FR, ES, JA, custom) | | /blog locale-audit <directory> | Multilingual content QA (completeness, hreflang, parity, freshness) | | /blog flow [find\|optimize\|win\|prompts\|sync] | FLOW framework prompts (evidence-led, 30 blog-applicable) | | /blog style learn <paths> | Learn author voice profile from 5-10 posts (feeds blog-write and blog-persona) | | /blog decay <current-gsc> <previous-gsc> | Detect content decay: flag 20%+ QoQ traffic decline from GSC exports |

/blog update is a freshness alias routed to blog-rewrite; the project