claude-blog

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

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

Demo

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

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

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

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