AI Blog Writing Agent Skill for Claude Code

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

Two versions of this skill. Choose the one that fits how you work:

• 🌐 Public open-source: AgriciDaniel/claude-blog. MIT-licensed, public releases, open to anyone. Use this if you want the stable, downloadable, no-membership-required version.
• 🔒 Community private mirror (this repo): AI-Marketing-Hub/claude-blog. Early access to in-development work (v1.9.0+ Blog Delivery Contract, hero ladder, mutation-tested regression coverage), and direct collaboration with the AI Marketing Hub Pro community. Requires membership.

The badges above track the public repo (AgriciDaniel/claude-blog) since the private mirror is not visible to shields.io. The publishing workflow (private dev, review, public release) is documented in docs/PUBLISHING.md.

Blog: See how claude-blog works

claude-blog is a Claude Code skill suite that writes, optimizes, and audits blog content at scale. Every article is dual-optimized for Google rankings (December 2025 Core Update, E-E-A-T) and AI citation platforms (ChatGPT, Perplexity, AI Overviews). A v1.9.0 5-gate Delivery Contract scores every draft against a 100-point rubric and blocks anything below 90 from reaching you.

Key takeaways

• What it is: a full-lifecycle blog engine: 30 sub-skills, 5 agents, 12 content templates, 21 on-demand references, 9 root-level Python scripts, 160 passing tests.
• Who it is for: solo bloggers, marketing teams, agencies, and Claude Code skill builders who want production-grade content output, not one-shot drafts.
• Core promise: every draft passes a 5-gate delivery contract (Capability, Format, Visual, Content Review, Asset Integrity) or the writer iterates up to 3 times before escalating to you.
• What makes it different: it eats its own dogfood. Version-coherence is CI-enforced across 14 surfaces, prose-hygiene runs on every PR, three mutation-tested regression suites lock the v1.9.0 fixes, and blog-reviewer is a BLOCKING gate, not advisory.
• Today: v1.9.0, released 2026-05-18. Works on Next.js MDX, Astro, Hugo, Jekyll, WordPress, Ghost, 11ty, Gatsby, and static HTML.

Who is claude-blog for?

claude-blog serves three audiences with one engine:

Solo bloggers and creators who want to ship one high-quality post per week without spending three hours on the SEO checklist. The orchestrator handles research, outline, draft, schema, internal linking, and citation verification in a single /blog write invocation.

Marketing teams and agencies managing many posts across topics, languages, and platforms. The skill ships topic-cluster planning (/blog cluster), multilingual one-command publishing (/blog multilingual), cannibalization detection (/blog cannibalization), and persona-driven voice profiles (/blog persona) so the same engine produces consistent content across the team.

Claude Code skill builders who want a production-grade reference for skill architecture, agent dispatch, delivery contracts, and CI gating. The repo demonstrates the Agent Skills open standard at Tier 4 complexity with 160 tests, version-coherence enforcement, installer-sync regression tests, and the v1.9.0 5-gate contract pattern. Read the source for inspiration; fork the patterns into your own skills.

What does claude-blog produce?

Every draft ships as 8 artifacts in a single folder. A condensed specimen of the .md output:

---
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.
- ... (full article, sourced citations, FAQ, schema JSON-LD)

Alongside the .md, the contract also produces: rendered .html (XSS-safe JSON-LD, dark-mode-aware CSS), .pdf (Playwright or weasyprint), hero.<ext> (1200x630, generated via Banana MCP, Gemini, stock APIs, or Openverse), 3 viewport screenshots (mobile-375.png, tablet-768.png, desktop-1280.png), review.md (5-category scorecard with BLOCKING line), and preflight-report.json (the full audit trail).

Table of Contents

• Demo
• Quick Start
• Commands
• How does claude-blog compare?
• Features
• Delivery contract (v1.9.0)
• Architecture
• Requirements
• Frequently Asked Questions
• Roadmap
• Uninstall
• Integration
• Documentation
• How to cite
• Security & Code of Conduct
• Contributing
• License
• Related projects
• Author

Demo

Watch the Demo on YouTube

Quick Start

ℹ️ Which version are you installing?

• Not an AI Marketing Hub Pro member? Install from the public repo: AgriciDaniel/claude-blog. All the install commands below work there. Just swap AI-Marketing-Hub/claude-blog for AgriciDaniel/claude-blog and the plugin slug claude-blog@ai-marketing-hub-claude-blog for claude-blog@agricidaniel-claude-blog. Public releases ship there; this private mirror runs ahead.
• Pro member? The commands below install the community version with early access to in-development features. They require an authenticated gh auth login (or GitHub PAT) session with access to the AI-Marketing-Hub org. If /plugin marketplace add fails with a 404, your account is not in the org yet. DM in the Skool community to get added.

Plugin Install (Claude Code 1.0.33+):

# Add marketplace (one-time)
/plugin marketplace add AI-Marketing-Hub/claude-blog

# Install plugin
/plugin install claude-blog@ai-marketing-hub-claude-blog

Recommended: clone, verify, then install (lets you inspect install.sh and pin a release tag):

git clone https://github.com/AI-Marketing-Hub/claude-blog.git
cd claude-blog
git checkout v1.9.0          # pin to a release tag (latest as of 2026-05-18)
chmod +x install.sh && ./install.sh

One-Command Install (Unix/macOS):

curl -fsSL https://raw.githubusercontent.com/AI-Marketing-Hub/claude-blog/main/install.sh | bash

One-Command Install (Windows PowerShell):

irm https://raw.githubusercontent.com/AI-Marketing-Hub/claude-blog/main/install.ps1 | iex

Piping curl or irm to a shell gives the script execution authority on your machine. The clone-then-checkout-tag flow is safer because you can inspect what runs. Both flows authenticate against the private repo using your existing gh auth / GitHub credentials.

Verify installer integrity (recommended, VULN-IAC-001 hardening):

# Download, verify SHA-256, then run if the hash matches.
curl -fsSL -o install.sh https://raw.githubusercontent.com/AI-Marketing-Hub/claude-blog/main/install.sh
echo "029388e448dd29bed259b130c2be42e2f6a16d4d5b6801a61bfb4f49b621fc04  install.sh" | sha256sum -c
bash install.sh

The SHA-256 above is for the current install.sh at HEAD on main. Verify against the canonical file before running. The install.ps1 companion hash is 6d03f353e5d844c4fe5c7c0b2500bd1e2aad02468cd544013bab876735cebf98. Hashes are updated in this README on every installer change.

Restart Claude Code after installation to activate.

Commands

🚀 First time? Try these three commands first: /blog strategy <niche> to scope your blog, /blog write <topic> to generate your first article (the 5-gate contract runs automatically), and /blog analyze <file> to score it on the 100-point rubric.

30 sub-skill directories total: 29 user-invokable (28 distinct slash commands + /blog update aliased to rewrite) + 1 internal-only (blog-chart, invoked by blog-write/blog-rewrite for inline SVG charts). blog-image is user-invokable AND callable internally.

How does claude-blog compare?

claude-blog is a structured pipeline. Direct LLM prompting is a one-shot. Hosted SaaS tools are closed-source. Here is the honest tradeoff matrix:

claude-blog is not better at everything. Direct prompting is faster for a single throwaway draft. Hosted SaaS is easier for non-developers. DIY is more flexible for unique pipelines. claude-blog fits where you want production-grade content at scale without a SaaS subscription.

Features

12 content templates

Auto-selected by topic and intent: how-to guide, listicle, case study, comparison, pillar page, product review, thought leadership, roundup, tutorial, news analysis, data research, FAQ knowledge base.

5-category quality scoring (100 points)

Scoring bands: Exceptional (90-100), Strong (80-89), Acceptable (70-79), Below Standard (60-69), Rewrite (<60). The v1.9.0 contract blocks delivery below 90.

AI content detection

Burstiness scoring on sentence-length variance, known AI-phrase detection (17 phrases), and vocabulary diversity (TTR). Flags content that reads as machine-generated before it reaches the reviewer.

Persona-driven writing

Configurable writing personas with the NNGroup 4-dimension tone framework (formal/casual, serious/funny, respectful/irreverent, matter-of-fact/enthusiastic). Manage voice profiles per blog or author, with readability bands (Consumer, Professional, Technical) and style enforcement at draft time.

Fact-checking pipeline

/blog factcheck fetches every cited source URL and scores claim confidence as exact match, paraphrase, or not found. Ensures every data point is accurate and traceable, not invented.

Keyword cannibalization detection

/blog cannibalization identifies keyword overlap across blog posts using local grep analysis or DataForSEO API. Severity scoring with merge or differentiate recommendations prevents posts from competing against each other in SERPs.

CMS taxonomy management

Tag and category sync supporting WordPress REST, Shopify GraphQL, Ghost, Strapi, and Sanity. Includes tag suggestion, sync, and audit workflows.

Dual optimization

Every article targets both Google rankings and AI citation platforms:

• Google: December 2025 Core Update compliance, E-E-A-T signals, schema markup, internal linking, Core Web Vitals awareness via blog-google.
• AI Citations: Answer-first formatting, citation capsules, passage-level citability (120-180 word blocks), FAQ schema, entity clarity.

Visual media

• Pixabay, Unsplash, and Pexels image sourcing with HTTP 200 verification and auto-generated alt text.
• AI image generation via Gemini for hero images, inline illustrations, and social cards. Requires a free Google AI API key.
• Built-in SVG chart generation in 7 styles (bar, grouped bar, lollipop, donut, line, area, radar).
• YouTube video embedding with srcdoc lazy loading and noscript AI-crawler fallback.
• Image density targets calibrated per content type.

Google API integration (v1.6.5+)

13 commands across 4 credential tiers, all free at normal usage:

• Tier 0 (API key): PageSpeed Insights, CrUX Core Web Vitals (25-week history), YouTube video search, NLP entity analysis.
• Tier 1 (OAuth): Search Console performance, URL Inspection, Indexing API.
• Tier 2 (GA4): Organic traffic reports.
• Tier 3 (Ads): Google Ads Keyword Planner.

NotebookLM research

Query Google NotebookLM for source-grounded research from user-uploaded documents. Tier 1 data quality with zero hallucination risk because the answers are extracted from documents you uploaded.

Audio narration

/blog audio generates audio narration via Gemini TTS. Three modes: summary (200-300 words), full article, two-speaker dialogue. 30 voices, 80+ languages.

Platform support

Next.js MDX, Astro, Hugo, Jekyll, WordPress, Ghost, 11ty, Gatsby, and static HTML.

Foundational methodologies (v1.8.0)

Five reference documents under skills/blog/references/ define the editorial and research methodology applied across all sub-skills. They are loaded on demand by the orchestrator:

Adapted from pbakaus/impeccable (Apache 2.0) and mvanhorn/last30days-skill (MIT). See CONTRIBUTORS.md for attribution.

FLOW framework

The FLOW framework (Find, Leverage, Optimize, Win) is the evidence-led workflow shared with AgriciDaniel/flow (CC BY 4.0). Each phase contributes prompts to the orchestrator pipeline; /blog flow exposes 30 ready-to-run prompts indexed by phase.

Delivery contract (v1.9.0)

Every blog passes a 5-gate contract before being shown to the user. The user is never the first reviewer; the gates are.

Hero image ladder: Banana MCP, direct Gemini API, premium stock (Unsplash, Pexels, Pixabay), Openverse public API. First available wins. Block-and-iterate up to 3 times on any gate failure before escalating to the user. Full spec: skills/blog/references/blog-delivery-contract.md.

Architecture

claude-blog ships as one orchestrator plus 29 sub-skills, 5 agents, 21 references, 12 templates, and 9 root-level scripts. The orchestrator routes user commands to sub-skills, which spawn agents and call scripts via Bash.

Full directory tree, data flow diagrams, scoring methodology, and extension points: docs/ARCHITECTURE.md.

Requirements

• Claude Code CLI installed and configured.
• Python 3.11+ (for quality scoring, the 5-gate delivery contract runners, and lint).
• Optional: pip install -r requirements.txt for advanced analysis (readability scoring, schema detection).

Quality gates (CI-enforced on every PR)

1. pytest: 160 tests across security, behavioral, regression, and delivery-contract suites.
2. Plugin validation: claude plugin validate . plus hand-rolled JSON/regex checks.
3. Stale-path lint: catches drift in references/ and templates/ cross-references.
4. Prose hygiene: scripts/lint_prose.py (fence-aware, backtick-aware) enforces the CONTRIBUTING.md no-em-dash, no-en-dash, no--- rule.
5. Version coherence: tests/test_version_coherence.py asserts pyproject.toml, plugin.json, CITATION.cff, and skills/blog/SKILL.md frontmatter all match.
6. Command coherence: tests/test_command_coherence.py asserts skills/blog/SKILL.md and docs/COMMANDS.md declare the same command set.

Run locally before pushing:

python -m pytest tests/
python3 scripts/lint_prose.py
claude plugin validate .

Frequently Asked Questions

What is claude-blog?

claude-blog is a Claude Code skill suite for writing, optimizing, and auditing blog content. It runs 30 sub-skills and 5 agents through a 5-gate delivery contract so that every article meets a 90/100 quality bar before it reaches you.

How is claude-blog different from prompting Claude or ChatGPT directly?

Direct prompting gives you one draft from one prompt. claude-blog gives you a structured pipeline: research with sourced statistics, outline approval, draft generation, multi-pass quality scoring, AI-content detection, fact verification, schema injection, and a blocking review that iterates up to 3 times before delivery. The skill enforces what a senior editor would otherwise do manually.

Do I need an AI Marketing Hub Pro membership to use claude-blog?

No. The public open-source version at AgriciDaniel/claude-blog is MIT-licensed and free for anyone with Claude Code. The private mirror at AI-Marketing-Hub/claude-blog is for Pro members who want early access to in-development features and direct collaboration with the community.

What blog platforms does claude-blog support?

Next.js MDX, Astro, Hugo, Jekyll, WordPress, Ghost, 11ty, Gatsby, and static HTML. The orchestrator auto-detects the platform from project signals and adjusts frontmatter, image embedding, and schema injection accordingly.

Does claude-blog hallucinate statistics?

No. Every cited statistic flows through /blog factcheck, which fetches the source URL and scores the claim confidence (exact match, paraphrase, not found). The blog-reviewer agent blocks publication if a citation cannot be verified or if AI-content detection flags the prose as machine-generated.

What is the 5-gate Blog Delivery Contract?

A code-enforced pre-presentation pipeline that runs on every draft: Capability Discovery, Format Completeness, Visual Verification at 3 viewport widths, Content Review (BLOCKING; score 90+ and zero P0), and Asset + Link Integrity. The orchestrator iterates the writer up to 3 times on any gate failure before escalating to you. Full spec in skills/blog/references/blog-delivery-contract.md.

Can I use claude-blog in multiple languages?

Yes. /blog multilingual <topic> --languages en,de,fr,es,ja writes the post, translates it preserving frontmatter and schema, runs cultural deep-adaptation per locale, and emits hreflang tags plus a CMS-ready language map in a single command.

How do I cite claude-blog in academic work?

See the How to cite section below or the CITATION.cff file in the repo root. GitHub surfaces the structured citation file via the "Cite this repository" button on the public mirror page.

Is claude-blog secure to install?

The installer ships only Python scripts and markdown files, never executes remote code beyond what pip install -r requirements.txt brings in, and is reviewed against the project SECURITY.md policy on every change. The clone-then-checkout-tag install flow lets you inspect install.sh before running it. See SECURITY.md for the full threat model.

Roadmap

v1.9.1 (next)

• Shared _count_body_words(html) function between blog_render and blog_preflight to close the v1.9.0 audit residual.
• generate_hero.py exit-code semantics: non-zero on no-image-gen-path (currently returns JSON error with exit 0).
• Iteration-loop coverage test verifying the orchestrator escalates after 3 reviewer BLOCKS, not 4.
• Sweep remaining docs (CONTRIBUTORS, NOTICE, SECURITY, PRIVACY, TEMPLATES, TROUBLESHOOTING, MCP-INTEGRATION, DEMO) for any residual v1.x stratum drift.

v1.10 (vision)

• Live SERP-informed outline refinement via DataForSEO mid-write.
• Eval harness measuring blog quality across configurations (BRAND.md presence, persona variant, multilingual mode).
• Code-enforced iteration counter (currently orchestrator-instruction; promote to script-level).

v2.0 (long-term)

• Headless preview server integration: the 5-gate contract runs against a real domain preview instead of local HTML.
• Per-platform CMS publishing connectors (WordPress, Ghost, Sanity) with idempotent re-publish on rewrite.
• Real-time AI-citation tracking dashboard (which posts get cited by ChatGPT, Perplexity, AI Overviews; visibility heatmap).

Open an issue with the roadmap label if you want to propose or vote on something.

Uninstall

Unix/macOS:

chmod +x uninstall.sh && ./uninstall.sh

Windows (PowerShell):

.\uninstall.ps1

Integration

Chart generation and YouTube video embedding are built-in. Google API data requires a free API key (see /blog google setup).

Optional companion skills (deeper analysis of published pages):

Documentation

Detailed documentation is in docs/:

• Installation Guide: Unix, macOS, Windows, manual install.
• Command Reference: Full command reference with examples.
• Architecture: System design and component overview.
• Publishing Workflow: Private-to-public release flow (Pro maintainers).
• Templates: Template reference and customization.
• Troubleshooting: Common issues and fixes.
• MCP Integration: Optional MCP server setup.

How to cite

If you use claude-blog in research or production, please cite the project:

@software{Agrici_claude_blog_2026,
  author       = {Agrici, Daniel},
  title        = {claude-blog: AI Blog Writing and SEO Optimization Skill for Claude Code},
  year         = {2026},
  url          = {https://github.com/AgriciDaniel/claude-blog},
  version      = {1.9.0},
  license      = {MIT}
}

GitHub also surfaces the structured CITATION.cff file via "Cite this repository" on the public mirror page.

Security & Code of Conduct

• Security policy + threat model: SECURITY.md. v1.8.x hardening pass closed every known finding; v1.9.0 adds XSS-safe JSON-LD, O_NOFOLLOW symlink refusal, and frontmatter validation, all mutation-test verified. To report a vulnerability privately, follow the disclosure procedure in SECURITY.md.
• Code of Conduct: CODE_OF_CONDUCT.md. Contributor Covenant. Be excellent to each other.

Contributing

Contributions welcome. See CONTRIBUTING.md for guidelines. Before opening a PR:

1. Run python -m pytest tests/ (all 160 must pass).
2. Run python3 scripts/lint_prose.py --root . (zero violations).
3. Run claude plugin validate . (must pass).
4. Bump versions coherently if you touch user-visible counts or behavior (see docs/PUBLISHING.md).

License

MIT License. See LICENSE for details.

Related projects

• Rankenstein: GUI-based content publishing workflow; research to publish in one platform.
• FLOW framework: Evidence-led Find, Optimize, Win prompts (CC BY 4.0). Integrated as a sub-skill via /blog flow.
• Claude Ads and Claude SEO: sibling skills sharing the same brand kit (banner + diagrams generated with the brand-orange palette).
• AI Marketing Hub: Free community, 2,800+ members. Pro tier at ai-marketing-hub-pro hosts this skill's private mirror.

Star history

If claude-blog saves you time, a star on the public repo is the easiest way to say thanks (and helps other content folks find it).

Author

Built by Daniel Agrici, AI Workflow Architect, with Claude Code.

• Blog: Deep dives on AI marketing automation.
• YouTube: Tutorials and demos.
• All open-source tools: Other Claude Code skills.
• AI Marketing Hub: Free community for AI-powered marketing.