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.3.1 was prepared on 2026-10-13.

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

Watch video on YouTube

Watch the original demo on YouTube.

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.3.1 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 pytest suite (run python3 -m pytest --collect-only -q | tail -1 for the current count), 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.

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 layered Agent Skills architecture (a directive layer of SKILL.md files, an orchestration layer of one routing skill plus agents, and an execution layer of scripts) with orchestrator routing, sub-skill dispatch, agent handoffs, code-enforced delivery gates, installer hardening, and CI coherence checks.

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.

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.

More architecture detail lives in docs/ARCHITECTURE.md.

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

The order is fixed: draft, resolve markers and visuals, render, issue the review nonce, review, run the gates, and re-render, re-issue and re-review after any edit (maximum 3 iterations). The renderer's own footer link is checked for its scheme only, so a fully local article can pass Gate 5 offline; external links need network access, and a failure there may be a network or DNS problem rather than a dead link. The review nonce stops accidents and casual forgery; it does not stop a process running as the same user that can read its state file. The full sequence and every check live in one place: skills/blog/references/blog-delivery-contract.md.

Hero image ladder: Banana MCP, direct Gemini API, premium stock APIs, then Openverse. First working source wins. The ladder is specified in the same contract.

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.

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.

/blog update is a freshness alias routed to blog-rewrite; the project count remains 30 user-facing /blog commands. blog-chart remains internal-only.

Full reference: docs/COMMANDS.md.

claude-blog integrates the FLOW framework from AgriciDaniel/flow (CC BY 4.0). FLOW means Find, Leverage, Optimize, Win. The skill surfaces Find, Optimize, and Win as /blog flow commands; Leverage is available as a prompt family through /blog flow prompts and is applied inside drafting, repurposing, and distribution workflows.

• 5-gate Delivery Contract: code-enforced pre-presentation gates for format, visuals, review, assets, and links.
• AI Citation Readiness Heuristic: scripts/ai_citation_score.py produces non-calibrated 0-100 editorial-readiness views for AI Overview, Perplexity, and ChatGPT and feeds /blog geo.
• Writing style learning: /blog style learn <paths> builds an author voice profile from 5 to 10 posts.
• Content decay detection: /blog decay <current-gsc> <previous-gsc> flags 20%+ quarter-over-quarter GSC traffic drops and suggests refresh, consolidate, or prune actions.
• Pre-commit quality gate: scripts/quality_gate.py and .pre-commit-config.yaml block blog posts below score 70 before commit. The hook passes --select so non-post Markdown files are skipped; run directly, the gate fails closed on a bad path or a file without blog frontmatter.
• Brand and discourse context: /blog brand writes BRAND.md and VOICE.md; /blog discourse writes DISCOURSE.md. The orchestrator loads them through fenced, nonce-bound untrusted-data handling.
• Multilingual and topic clusters: /blog multilingual, /blog translate, /blog localize, /blog locale-audit, and /blog cluster support international hub-and-spoke publishing.
• Deterministic blog hygiene: scripts/blog_hygiene.py can add lazy image loading and a table of contents without replacing human review.

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, and FAQ knowledge base.

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

• Advisory editorial style diagnostics for sentence-length variation, configured phrase lists, and vocabulary sampling; these never infer authorship or affect scoring.
• Persona-driven writing with NNGroup tone dimensions, readability bands, and style enforcement.
• /blog factcheck source verification with exact match, paraphrase, and not-found confidence scoring.
• /blog cannibalization keyword overlap detection with merge or differentiate recommendations.
• CMS taxonomy management for WordPress, Shopify, Ghost, Strapi, and Sanity.
• Dual Google and AI-citation optimization, including evidence-backed explanations, intent-matched structure, optional visible Q&A, internal links, schema, and substantive maintenance.
• Visual media through Gemini image generation, verified stock sourcing, SVG charts, YouTube embeds, and alt text requirements.
• Google API integration across PageSpeed Insights, CrUX, Search Console, GA4, NLP, YouTube, URL Inspection, and Keyword Planner. Indexing API use is scoped to JobPosting or livestream URLs only and requires indexing_notify.py --confirm-eligible.
• NotebookLM (now Gemini Notebook, notebook.google.com) research for source-grounded answers from user-uploaded documents.
• Gemini TTS audio narration in summary, full-article, and two-speaker dialogue modes (default model alias flash38, with a --max-chunks cap on billed calls).
• Platform support for Next.js MDX, Astro, Hugo, Jekyll, WordPress, Ghost, 11ty, Gatsby, and static HTML.

Adapted attribution lives in CONTRIBUTORS.md.

The Claude Blog Brain is vendored at ./brain as a self-contained, evidence-gated Obsidian brain. It is not part of the plugin payload; all skill tooling remains scoped to skills/. Brain-derived updates land through reviewed reference, script, and documentation changes.

Plugin install. Tested on Claude Code 2.1.296. The Claude Code changelog first lists the plugin system in 2.0.12 and the ${CLAUDE_SKILL_DIR} skill variable that these skills rely on in 2.1.69 (changelog, checked 2026-10-12), so 2.1.69 is the oldest version this README can justify and nothing older has been tested:

/plugin marketplace add AgriciDaniel/claude-blog
/plugin install claude-blog@agricidaniel-blog

Placeholder used below: <commit-sha-or-release-tag> is the first release that contains the ownership-aware installer (scripts/installer_ownership.py), or a commit you reviewed. Prefer a full 40-character commit SHA. The first such release is v2.3.0.

Do not install or uninstall from the v2.2.0 tag. It predates the ownership-aware installer, and its uninstall.sh recursively deletes whole blog and blog-* skill directories, including files you added to them. An existing v2.2.0 standalone install can be migrated or removed safely by the newer installer; it adopts files only when their bytes match the reviewed release inventory.

Recommended clone, review, then install flow:

git clone https://github.com/AgriciDaniel/claude-blog.git
cd claude-blog
git checkout <commit-sha-or-release-tag>
# Review install.sh, uninstall.sh and scripts/installer_ownership.py.
chmod +x install.sh
./install.sh

Download, inspect, and run on Unix and macOS:

curl -fsSLo install.sh https://raw.githubusercontent.com/AgriciDaniel/claude-blog/main/install.sh
# Inspect install.sh and verify the digest below before execution.
CLAUDE_BLOG_REF=<commit-sha-or-release-tag> bash install.sh

One-command install on Windows PowerShell:

$env:CLAUDE_BLOG_REF = "<commit-sha-or-release-tag>"
irm https://raw.githubusercontent.com/AgriciDaniel/claude-blog/main/install.ps1 -OutFile install.ps1
pwsh -File ./install.ps1

Verify the downloaded wrapper before running it:

curl -fsSL -o install.sh https://raw.githubusercontent.com/AgriciDaniel/claude-blog/main/install.sh
echo "cd471aabcf08bd208d3377ee432add8f1addeb79d6767e6acb34518972df0164  install.sh" | sha256sum -c
CLAUDE_BLOG_REF=<commit-sha-or-release-tag> bash install.sh

Integrity is only as pinned as CLAUDE_BLOG_REF. What the digests cover: each is the SHA-256 of that one file's bytes in this repository with CRLF line endings normalized to LF, the form raw.githubusercontent.com serves (install.sh: the digest above; install.ps1: aa80fa99aaacc5dec3acabcbd714801b4a3e63635c09db9264041f8b8f48dd97). A local copy with CRLF endings or edits will not match until normalized. They do not cover the code that does the work: the wrapper clones the repository at CLAUDE_BLOG_REF and hands over to that revision's own install.sh, scripts/installer_ownership.py and payload. A branch such as main moves, a tag can be re-pointed by whoever controls the repository, and a full commit SHA cannot. Pin a commit SHA you reviewed, or use the clone, review, install flow above. Compare against the canonical file. The digests are refreshed at release time; if they disagree with main, treat the commit you reviewed as the authority and report the mismatch.

The Unix installer installs optional Python extras with pip --user (or plain pip inside a virtual environment), never with sudo; on an externally managed Python it prints virtual-environment steps instead. If it stops with "managed installation file was modified", it names the files and the safe recovery (--force-adopt on Unix, -ForceAdopt on Windows, for both the installer and the uninstaller). Each edited file is first copied to ~/.claude/claude-blog-backups/<timestamp>/. CLAUDE_BLOG_SKIP_PIP=1 skips the optional Python dependency step. install.ps1 rejects a CLAUDE_BLOG_REPO, CLAUDE_BLOG_REF or CLAUDE_BLOG_URL that git could read as an option or a command transport; details and the exact rules are in docs/INSTALLATION.md.

Restart Claude Code after installation to activate.

Uninstall on Unix and macOS:

chmod +x uninstall.sh
./uninstall.sh

Uninstall on Windows PowerShell:

.\uninstall.ps1

Installation details: docs/INSTALLATION.md.

plugins/blog-studio is a separate, optional Claude Code mod in the same marketplace. It adds a status band, a live pipeline and five-gate review panel, a history of past blogs, and a Run checks control that runs the strict preflight. It is not part of the claude-blog plugin and the standalone installers never enable it.

/plugin marketplace add AgriciDaniel/claude-blog
/plugin install blog-studio@agricidaniel-blog
/blog-studio configure /path/to/claude-blog/scripts

It needs a Claude Code release with mods support (checked on 2.1.294 to 2.1.296, Linux CLI; the Desktop app is fixture-tested only). See plugins/blog-studio/README.md.

• claude plugin validate rejects the name claude-blog on newer Claude Code. Claude Code 2.1.292 and later (checked on 2.1.292 and 2.1.296) report Plugin name "claude-blog" is reserved because third-party plugin names that start with claude- are reserved for Anthropic. The v2.2.0 release fails the same way; Claude Code 2.1.218 passes. In maintainer testing the plugin still installs and loads, so this is a validation error rather than an observed install failure, but a future release could enforce it at install time. The repository's own tests and scripts/validate_public_release.py do not depend on this check. CI runs claude plugin validate . through .github/scripts/validate_plugin_tolerate_reserved_name.py, which tolerates exactly that reserved-name finding (once in the marketplace check and once in the plugin.json check) plus the root CLAUDE.md notice, and fails on any other error or warning. Details: docs/TROUBLESHOOTING.md.

• Claude Code CLI installed and configured (tested on 2.1.296; see the version note under Install).
• Python 3.11+ for quality scoring, the delivery contract runners, renderers, and lint.
• Optional: pip install -r requirements.txt for advanced analysis, readability scoring, schema detection, and media workflows.

1. pytest: the complete security, behavioral, regression, installer, and delivery-contract suite.
2. Plugin validation: claude plugin validate . (tolerating only the known reserved-name finding, see Known Issues) plus manifest, marketplace, and frontmatter checks.
3. Stale-path lint: catches drift in references/, templates/, command docs, and installer payloads.
4. Prose hygiene: scripts/lint_prose.py enforces no em dash, no en dash, and no ASCII double-hyphen prose.
5. Secret adjudication: scripts/check_secrets.py fails on unapproved detector findings and credential-shaped values without printing raw values.
6. Version coherence: canonical version surfaces must all match the release version.
7. Command coherence: skills/blog/SKILL.md and docs/COMMANDS.md must declare the same command set.
8. Repository consistency: validates local reference targets, FLOW prompt locks, and reports orphaned resources without blocking.
9. Hash-locked dependency smoke: installs the audio and NotebookLM locks with --require-hashes, then initializes google-genai, Patchright, and preflight without API calls or a browser launch.
10. Brain validation: changes under brain/** run its pytest suite, vault lint, and report-only audit.

Run locally before pushing:

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

This section lists only what this repository ships and how you can check each item yourself. It makes no claims about the capabilities of other products, which change and which this project has not benchmarked.

Maintainer opinion, written 2026-10-12 and not a benchmark: direct prompting is faster for a single throwaway draft, hosted writing tools are easier for non-developers, and building your own pipeline is more flexible for unusual needs. claude-blog is aimed at people who already use Claude Code and want a repeatable, gated workflow they can read and change.

claude-blog is a Claude Code skill suite for writing, optimizing, and auditing blog content. Drafts go through a 5-gate delivery contract, including an independent review that must score 90/100 or higher with no P0 issues, before they are presented to you.

Direct prompting gives you one draft from one prompt. claude-blog gives you a structured pipeline (see the verifiable list above): research with sourced statistics, outline approval, draft generation, multi-pass quality scoring, advisory editorial pattern review, fact verification, schema injection, and a blocking review that iterates up to 3 times before delivery.

Yes. AgriciDaniel/claude-blog is MIT-licensed and available to anyone using Claude Code.

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

The workflow is designed to block invented numbers. /blog factcheck fetches cited source URLs and scores each claim as exact match, paraphrase, or not found. blog-reviewer treats a load-bearing claim without adequate source support as a P0 issue, which blocks delivery.

It is a pre-presentation pipeline for Capability Discovery, Format Completeness, Visual Verification, Content Review, and Asset and Link Integrity. The orchestrator iterates up to 3 times on any gate failure before escalating to you, and any edit after the review means re-rendering and re-reviewing. Full spec: skills/blog/references/blog-delivery-contract.md.

Yes. /blog multilingual <topic> --languages <codes> writes the post, translates it while preserving frontmatter and schema, runs cultural adaptation per locale, and emits hreflang tags plus a CMS-ready language map.

See How To Cite or CITATION.cff. GitHub also surfaces the citation through the public mirror.

The recommended flow downloads the installer as a file so you can inspect it before execution. The installers use ownership-verified payload copies, manifest-backed uninstall, backups before any forced replacement, and regression tests; pin CLAUDE_BLOG_REF to a reviewed commit SHA (never the v2.2.0 tag, whose uninstall.sh predates these protections). See SECURITY.md.

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

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      = {2.3.1},
  license      = {MIT}
}

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

• Security policy and threat model: SECURITY.md. To report a vulnerability privately, follow the disclosure procedure there.
• Code of Conduct: CODE_OF_CONDUCT.md. Contributor Covenant.

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

1. Run python3 -m pytest tests/ and confirm the full suite passes.
2. Run python3 scripts/lint_prose.py and confirm zero violations.
3. Run claude plugin validate ..
4. Bump versions coherently if you touch user-visible counts or behavior.

MIT License. See LICENSE.

• Rankenstein: GUI-based content publishing workflow.
• FLOW framework: Evidence-led Find, Leverage, Optimize, Win prompts (CC BY 4.0).
• Claude Ads and Claude SEO: sibling Claude Code skills.
• AI Marketing Hub: Free community for AI-powered marketing.

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.