` | Cultural deep-adaptation (DACH, FR, ES, JA, custom) |
| `/blog locale-audit ` | 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 ` | Learn author voice profile from 5-10 posts (feeds blog-write and blog-persona) |
| `/blog decay ` | Detect content decay: flag 20%+ QoQ traffic decline from GSC exports |
`/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`](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/docs/COMMANDS.md).
## FLOW Framework
claude-blog integrates the FLOW framework from [`AgriciDaniel/flow`](https://github.com/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.
## Features
### v1.10 and v1.11 Highlights
- **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 ` builds an author voice profile from 5 to 10 posts.
- **Content decay detection**: `/blog decay ` 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.
- **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.
### 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, and FAQ knowledge base.
### 5-Category Quality Scoring
| Category | Points | Focus |
|---|---:|---|
| Content Quality | 30 | Depth, readability, originality, engagement |
| SEO Optimization | 25 | Headings, title, keywords, links, meta |
| E-E-A-T Signals | 15 | Author, citations, trust, evidence basis |
| Technical Elements | 15 | Schema, images, speed, mobile, OG tags |
| AI Citation Readiness | 15 | Evidence-backed citability, purpose fit, entity clarity |
Scoring bands: Exceptional (90-100), Strong (80-89), Acceptable (70-79), Below Standard (60-69), Rewrite (<60). The delivery contract blocks delivery below 90.
### More Capabilities
- 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.
- NotebookLM research for source-grounded answers from user-uploaded documents.
- Gemini TTS audio narration in summary, full-article, and two-speaker dialogue modes.
- Platform support for Next.js MDX, Astro, Hugo, Jekyll, WordPress, Ghost, 11ty, Gatsby, and static HTML.
### Methodology References
| Reference | Purpose |
|---|---|
| `ai-slop-detection.md` | Two-tier advisory editorial pattern review; never an authorship classifier or scoring input |
| `editorial-heuristics.md` | Nielsen-adapted 0-4 scoring with P0-P3 severity |
| `cognitive-load.md` | Per-section concept-density scoring |
| `research-quality.md` | Source-tier, freshness, and synthesis quality checks |
| `synthesis-contract.md` | Research synthesis LAWs for citation-safe output |
Adapted attribution lives in [`CONTRIBUTORS.md`](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/docs/CONTRIBUTORS.md).
## Brain Provenance
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.
## Install
Plugin install for Claude Code 1.0.33+:
```bash
/plugin marketplace add AgriciDaniel/claude-blog
/plugin install claude-blog@agricidaniel-blog
```
Recommended clone, verify, then install flow:
```bash
git clone https://github.com/AgriciDaniel/claude-blog.git
cd claude-blog
git checkout v2.1.1
chmod +x install.sh
./install.sh
```
One-command install on Unix and macOS:
```bash
curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-blog/main/install.sh | CLAUDE_BLOG_REF=v2.1.1 bash
```
One-command install on Windows PowerShell:
```powershell
$env:CLAUDE_BLOG_REF = "v2.1.1"
irm https://raw.githubusercontent.com/AgriciDaniel/claude-blog/main/install.ps1 -OutFile install.ps1
pwsh -File ./install.ps1
```
Verify installer integrity before running:
```bash
curl -fsSL -o install.sh https://raw.githubusercontent.com/AgriciDaniel/claude-blog/main/install.sh
echo "b4fcd5aa6767529bc8d11017699bd8211519c93b0d6c28c5cf032f76ada98381 install.sh" | sha256sum -c
CLAUDE_BLOG_REF=v2.1.1 bash install.sh
```
The SHA-256 above is for the current `install.sh` at HEAD on `main`; `CLAUDE_BLOG_REF` pins the repository clone performed by the installer. Verify against [the canonical file](https://github.com/AgriciDaniel/claude-blog/blob/main/install.sh) before running. The `install.ps1` companion hash is `9532d3014aa24468d8dd309e19acb5557c9cc7e4edab718381c26515aab48a79`.
Restart Claude Code after installation to activate.
Uninstall on Unix and macOS:
```bash
chmod +x uninstall.sh
./uninstall.sh
```
Uninstall on Windows PowerShell:
```powershell
.\uninstall.ps1
```
Installation details: [`docs/INSTALLATION.md`](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/docs/INSTALLATION.md).
## Requirements
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed and configured.
- 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.
### Automated CI Quality Gates
1. **pytest**: the complete security, behavioral, regression, installer, and delivery-contract suite.
2. **Plugin validation**: `claude plugin validate .` 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. **Version coherence**: canonical version surfaces must all match the release version.
6. **Command coherence**: `skills/blog/SKILL.md` and [`docs/COMMANDS.md`](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/docs/COMMANDS.md) must declare the same command set.
7. **Repository consistency**: validates local reference targets, FLOW prompt locks, and reports orphaned resources without blocking.
8. **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.
9. **Brain validation**: changes under `brain/**` run its pytest suite, vault lint, and report-only audit.
Run locally before pushing:
```bash
python3 -m pytest tests/
python3 scripts/lint_prose.py
claude plugin validate .
```
## How Does claude-blog Compare?
claude-blog is a structured pipeline. Direct LLM prompting is a one-shot. Hosted SaaS tools are closed-source. The tradeoffs are:
| Capability | claude-blog | Direct Claude or ChatGPT prompt | Copy.ai or Jasper | Build it yourself |
|---|:---:|:---:|:---:|:---:|
| Full article in one command with iteration loop | Yes | One-shot | Yes | No |
| Sourced statistics with verification | Yes | No | No | Manual |
| AI citation optimization (GEO / AEO) | Yes | No | No | Partial |
| Blocking content review with score 90+ | Yes | No | No | No |
| Multilingual plus hreflang in one command | Yes | Partial | Partial | No |
| Topic-cluster planning | Yes | No | Partial | No |
| Audio narration | Yes | No | No | No |
| Hero image generation ladder | Yes | No | Stock only | Partial |
| Persistent brand and voice context | Yes | Per-prompt | Limited | No |
| Open-source, MIT, no SaaS subscription | Yes | No | No | Yes |
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 when you want production-grade content at scale without a SaaS subscription.
## Frequently Asked Questions
### What is claude-blog?
claude-blog is a Claude Code skill suite for writing, optimizing, and auditing blog content. It runs 32 skill directories through a 5-gate delivery contract so 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, advisory editorial pattern review, fact verification, schema injection, and a blocking review that iterates up to 3 times before delivery.
### Is claude-blog free and open source?
Yes. [`AgriciDaniel/claude-blog`](https://github.com/AgriciDaniel/claude-blog)
is MIT-licensed and available to anyone using Claude Code.
### 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 and adjusts frontmatter, image embedding, and schema injection.
### Does claude-blog hallucinate statistics?
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` blocks publication when citations cannot be verified.
### What is the 5-gate Blog Delivery Contract?
It is a pre-presentation pipeline for Capability Discovery, Format Completeness, Visual Verification, Content Review, and Asset and Link Integrity. The orchestrator iterates the writer up to 3 times on any gate failure before escalating to you. Full spec: [`skills/blog/references/blog-delivery-contract.md`](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/skills/blog/references/blog-delivery-contract.md).
### Can I use claude-blog in multiple languages?
Yes. `/blog multilingual --languages ` 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.
### How do I cite claude-blog in academic work?
See [How To Cite](#how-to-cite) or [`CITATION.cff`](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/CITATION.cff). GitHub also surfaces the citation through the public mirror.
### Is claude-blog secure to install?
The recommended flow downloads the installer as a file so you can inspect it before execution. v2.1.1 uses pinned refs, allowlisted recursive payload copies, manifest-backed uninstall, prose lint, version coherence checks, repository consistency checks, and installer regression tests. See [`SECURITY.md`](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/.github/SECURITY.md).
## Documentation Index
- [Installation Guide](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/docs/INSTALLATION.md): Unix, macOS, Windows, manual install, and reproducible `uv` setup.
- [Command Reference](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/docs/COMMANDS.md): Full command reference with examples.
- [Architecture](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/docs/ARCHITECTURE.md): System design and component overview.
- [Publishing Workflow](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/docs/PUBLISHING.md): Private-to-public release flow.
- [Templates](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/docs/TEMPLATES.md): Template reference and customization.
- [Troubleshooting](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/docs/TROUBLESHOOTING.md): Common issues and fixes.
- [MCP Integration](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/docs/MCP-INTEGRATION.md): Optional MCP server setup.
- [Demo](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/docs/DEMO.md): Worked end-to-end example.
## How To Cite
If you use claude-blog in research or production, please cite the project:
```bibtex
@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.1.1},
license = {MIT}
}
```
GitHub also surfaces the structured [`CITATION.cff`](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/CITATION.cff) file via "Cite this repository" on the public mirror page.
## Security & Code of Conduct
- **Security policy and threat model**: [`SECURITY.md`](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/.github/SECURITY.md). To report a vulnerability privately, follow the disclosure procedure there.
- **Code of Conduct**: [`CODE_OF_CONDUCT.md`](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/.github/CODE_OF_CONDUCT.md). Contributor Covenant.
## Contributing
Contributions are welcome. See [`CONTRIBUTING.md`](https://github.com/AgriciDaniel/claude-blog/blob/HEAD/.github/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.
## License
MIT License. See [`LICENSE`](https://github.com/AgriciDaniel/claude-blog/tree/HEAD/LICENSE).
## Related Projects
- **[Rankenstein](https://rankenstein.pro)**: GUI-based content publishing workflow.
- **[FLOW framework](https://github.com/AgriciDaniel/flow)**: Evidence-led Find, Leverage, Optimize, Win prompts (CC BY 4.0).
- **[Claude Ads](https://github.com/AgriciDaniel/claude-ads)** and **[Claude SEO](https://github.com/AgriciDaniel/claude-seo)**: sibling Claude Code skills.
- **[AI Marketing Hub](https://www.skool.com/ai-marketing-hub)**: Free community for AI-powered marketing.
## Author
Built by [Daniel Agrici](https://agricidaniel.com/about), AI Workflow Architect, with Claude Code.
- [Blog](https://agricidaniel.com/blog): Deep dives on AI marketing automation.
- [YouTube](https://www.youtube.com/@AgriciDaniel): Tutorials and demos.
- [All open-source tools](https://github.com/AgriciDaniel): Other Claude Code skills.
- [AI Marketing Hub](https://www.skool.com/ai-marketing-hub): Free community for AI-powered marketing.