Free, open source blog writer for Claude Code. Researches current sources, writes answer-first posts for Google and AI answers, has an independent reviewer score each one out of 100 and ships only after five delivery gates. 32 skills, 30 /blog commands, 5 agents. Active development at AI-Marketing-Hub/claude-blog; public releases ship here.
Installation Guide
This guide covers all installation methods for claude-blog, a Claude Code skill
ecosystem for blog content creation, optimization, and management.
Prerequisites
| Requirement | Version | Purpose |
|---|---|---|
| Claude Code CLI | 2.1.69 or later; tested on 2.1.296 | Runtime for all /blog commands |
| Python | 3.11+ | Quality scoring + 5-gate delivery contract runners (analyze_blog, blog_preflight, blog_render, generate_hero, lint_prose, ...) |
| pip | Latest | Python dependency management |
Claude Code must be installed and configured before installing claude-blog.
Version note: the Claude Code changelog first lists the plugin system in
2.0.12 and the ${CLAUDE_SKILL_DIR} skill variable, which this bundle's skills
use to find their scripts and references, in 2.1.69
(changelog,
checked 2026-10-12). 2.1.69 is therefore the oldest version this guide can
justify; only 2.1.296 has been tested.
Python 3.11+ is required for quality scoring and helper workflows including
analyze_blog.py, blog_preflight.py, blog_render.py, generate_hero.py,
lint_prose.py, and related script checks. Commands that do not invoke those
helpers may still run without Python, but production installs should include it.
Quick Install (One Command)
Linux / macOS
curl -fsSLo install.sh https://raw.githubusercontent.com/AgriciDaniel/claude-blog/main/install.sh
# Read install.sh, then pin the revision that will actually run:
CLAUDE_BLOG_REF=<commit-sha-or-release-tag> bash install.sh
Windows (PowerShell)
irm https://raw.githubusercontent.com/AgriciDaniel/claude-blog/main/install.ps1 -OutFile install.ps1
$env:CLAUDE_BLOG_REF = "<commit-sha-or-release-tag>"
pwsh -File ./install.ps1
<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 downloaded wrapper clones
the repository at that ref and hands over to the installer in the clone, so the
wrapper's digest only covers the wrapper. Without CLAUDE_BLOG_REF the wrapper
follows the moving main branch. Do not use the v2.2.0 tag for installing or
uninstalling: it predates the ownership-aware installer, and its uninstall.sh
recursively deletes whole blog and blog-* skill directories, including any
files you added to them.
install.ps1 validates the variables that reach git before it clones:
CLAUDE_BLOG_REPO must look like owner/name; CLAUDE_BLOG_REF must be a tag,
branch or commit name that starts with a letter or digit and contains none of
.., a trailing / or a trailing .lock; CLAUDE_BLOG_URL must not start with
-, contain control characters, or use the ext:: or fd:: command
transports. A value that fails stops the install with a message naming the
variable. install.sh does not apply these checks yet, so set
CLAUDE_BLOG_REF and CLAUDE_BLOG_URL only from values you typed yourself.
Downloading either script before running it lets you inspect the exact bytes first and avoids direct download-to-execution pipelines. It also removes the PowerShell pattern reported in issue #33. See SECURITY.md.
Both installers automatically copy all skills, agents, references, templates, and scripts to the correct Claude Code configuration directories.
Standard Install (Git Clone)
git clone https://github.com/AgriciDaniel/claude-blog.git
cd claude-blog
git checkout <commit-sha-or-release-tag> # see the note above; review install.sh first
chmod +x install.sh
./install.sh
Install Python Dependencies
The installers (Unix and Windows) then try to install the optional packages from
requirements.txt with python3 -m pip install --user (the same interpreter it
version-checked), or plain pip inside an active virtual environment. They never
use sudo and never pass --break-system-packages. Failure is only a
warning: the skills are already installed. On an externally managed Python
(PEP 668, common on Debian, Fedora and Homebrew) pip refuses, and the installer
prints the virtual-environment commands to use instead:
python3 -m venv ~/.claude-blog-venv
~/.claude-blog-venv/bin/python -m pip install -r requirements.txt
Set CLAUDE_BLOG_SKIP_PIP=1 (Unix and Windows) to skip the step entirely. Python 3.11+ is
required; the stock macOS /usr/bin/python3 is too old, so install a current
Python first (for example brew install [email protected]) and open a new terminal.
Reproducible install via uv (v1.9.1+)
For deterministic supply-chain hygiene, the repo ships uv.lock with hashes
for resolved artifacts. Reproduce the exact
dev environment with:
pip install uv # one-time
uv sync --frozen --extra dev # installs the declared dev environment
This is the recommended path for CI, audit, and any context where
"works on my machine" is not enough. The legacy pip install -e ".[dev]"
flow still works; it just resolves transitives freshly each time.
Regenerate uv.lock after editing pyproject.toml dependency bounds:
uv lock
Core dependencies (requirements.txt and the core extra in pyproject.toml):
| Package | Version | Purpose |
|---|---|---|
| textstat | >=0.7.3,<1.0.0 | Readability scoring (Flesch, Gunning Fog, SMOG) |
| beautifulsoup4 | >=4.12.0,<5.0.0 | HTML and schema parsing |
Optional dependencies (the advanced extra; unlock advanced features in analyze_blog.py):
pip install lxml # Faster HTML parser backend for BeautifulSoup
pip install jsonschema # JSON-LD schema validation
pip install spacy # NER, advanced NLP
python -m spacy download en_core_web_sm
pip install sentence-transformers # Semantic similarity / duplicate detection
pip install scikit-learn # Topic cannibalization clustering
pip install language-tool-python # Grammar and style checking (requires Java)
The analysis script works without optional dependencies by falling back to basic mode automatically.
Manual Install (File by File)
If you prefer not to run the installer, copy files to these paths manually.
~ refers to your home directory ($HOME on Unix, %USERPROFILE% on Windows).
Directory Structure
~/.claude/
├── skills/
│ ├── blog/
│ │ ├── SKILL.md # Main orchestrator
│ │ ├── references/ # 22 files; copy the whole directory
│ │ │ └── *.md
│ │ ├── templates/ # 12 content type templates
│ │ │ └── *.md
│ │ └── scripts/
│ │ └── analyze_blog.py
│ ├── blog-write/SKILL.md
│ ├── blog-rewrite/SKILL.md
│ ├── blog-analyze/SKILL.md
│ ├── blog-brief/SKILL.md
│ ├── blog-calendar/SKILL.md
│ ├── blog-strategy/SKILL.md
│ ├── blog-outline/SKILL.md
│ ├── blog-seo-check/SKILL.md
│ ├── blog-schema/SKILL.md
│ ├── blog-repurpose/SKILL.md
│ ├── blog-geo/SKILL.md
│ ├── blog-audit/SKILL.md
│ ├── blog-chart/SKILL.md # internal-only
│ ├── blog-image/SKILL.md # v1.4.0
│ ├── blog-cannibalization/SKILL.md
│ ├── blog-factcheck/SKILL.md
│ ├── blog-persona/SKILL.md
│ ├── blog-taxonomy/SKILL.md
│ ├── blog-notebooklm/SKILL.md # v1.5.0
│ ├── blog-audio/SKILL.md # v1.6.0
│ ├── blog-google/SKILL.md # v1.6.5
│ ├── blog-cluster/SKILL.md # v1.7.0
│ ├── blog-flow/SKILL.md # v1.7.0
│ ├── blog-multilingual/SKILL.md # v1.7.0
│ ├── blog-translate/SKILL.md # v1.7.0
│ ├── blog-localize/SKILL.md # v1.7.0
│ ├── blog-locale-audit/SKILL.md # v1.7.0
│ ├── blog-brand/SKILL.md # v1.8.0
│ ├── blog-discourse/SKILL.md # v1.8.0
│ ├── blog-style/SKILL.md # v1.10.0
│ └── blog-decay/SKILL.md # v1.10.0
└── agents/
├── blog-researcher.md
├── blog-writer.md
├── blog-seo.md
├── blog-reviewer.md
└── blog-translator.md # v1.7.0
Copy Commands (Unix)
# Create directories. Auto-discover sub-skills via shell glob so we never
# fall behind on the directory list (v1.8.6: replaces the hand-rolled
# 14-skill mkdir from v1.4.0).
mkdir -p ~/.claude/skills/blog/{references,templates,scripts}
mkdir -p ~/.claude/scripts
for d in skills/blog-*/; do
mkdir -p "${HOME}/.claude/skills/$(basename "$d")"
done
mkdir -p ~/.claude/agents
# Main skill
cp skills/blog/SKILL.md ~/.claude/skills/blog/SKILL.md
# References
cp -R skills/blog/references/. ~/.claude/skills/blog/references/
# Templates
cp -R skills/blog/templates/. ~/.claude/skills/blog/templates/
# Sub-skills plus their payload directories
for d in skills/blog-*/; do
name=$(basename "$d")
cp "$d/SKILL.md" "${HOME}/.claude/skills/$name/SKILL.md"
for payload in references scripts assets templates; do
if [ -d "$d/$payload" ]; then
mkdir -p "${HOME}/.claude/skills/$name/$payload"
cp -R "$d/$payload"/. "${HOME}/.claude/skills/$name/$payload/"
fi
done
if [ -d "${HOME}/.claude/skills/$name/scripts" ]; then
find "${HOME}/.claude/skills/$name/scripts" -type f -name '*.py' -exec chmod +x {} +
fi
done
# Agents
cp agents/*.md ~/.claude/agents/
# Root scripts
for f in scripts/*.py; do
name=$(basename "$f")
cp "$f" "${HOME}/.claude/scripts/$name"
chmod +x "${HOME}/.claude/scripts/$name"
if [ "$name" = "analyze_blog.py" ]; then
cp "$f" ~/.claude/skills/blog/scripts/analyze_blog.py
chmod +x ~/.claude/skills/blog/scripts/analyze_blog.py
fi
done
Optional: AI Image Generation
claude-blog can generate custom blog images via Gemini AI (hero images, inline
illustrations, social cards). This requires the nanobanana-mcp server and a free
Google AI API key.
Setup
# Get your free API key at: https://aistudio.google.com/apikey
# Prefer --key-file (or the interactive prompt) over --key, which leaves the key in shell history
python3 skills/blog-image/scripts/setup_image_mcp.py --key-file /path/to/key.txt
# Verify setup
python3 skills/blog-image/scripts/validate_image_setup.py
Requirements
| Requirement | Version | Purpose |
|---|---|---|
| Node.js | 18+ | Runs npx @ycse/nanobanana-mcp |
| Google AI API key | Free tier | Image generation via Gemini |
Without this setup, all /blog commands work normally using stock photos from
Pixabay/Unsplash/Pexels. AI image generation is an optional enhancement.
Optional: Blog Studio
Blog Studio adds a live status band, a pipeline and five-gate panel, a history
of past posts and a Run checks control. It is a separate plugin in the same
marketplace, served from the blog-studio branch of this repository
(https://github.com/AgriciDaniel/claude-blog/tree/blog-studio/plugins/blog-studio) and pinned to a commit:
/plugin marketplace add AgriciDaniel/claude-blog
/plugin install blog-studio@agricidaniel-blog
Studio 0.3.0 needs claude-blog 2.3.2 or later, because its Run checks passes
blog_preflight.py --manual-check.
Verification
After installation, verify everything is in place:
1. Check installed files
# Main skill
ls ~/.claude/skills/blog/SKILL.md
# Blog-* directories should list 31 (30 user-facing commands plus the internal blog-chart); total is 32 skill directories (1 orchestrator + 31 sub-skills)
ls ~/.claude/skills/blog-*/SKILL.md | wc -l
# Agents (should list 5: blog-researcher, blog-writer, blog-seo, blog-reviewer, blog-translator)
ls ~/.claude/agents/blog-*.md | wc -l
# References (should list 22 .md files)
ls ~/.claude/skills/blog/references/*.md | wc -l
# Python script
ls ~/.claude/skills/blog/scripts/analyze_blog.py
2. Restart Claude Code
Close and reopen Claude Code (or restart the CLI) to load the new skills:
# If running in terminal, exit and relaunch
claude
3. Test a command
# Inside Claude Code, run:
/blog strategy "home automation"
You should see the orchestrator route to the blog-strategy sub-skill and
begin gathering context about the niche.
4. Test the Python analysis script
python3 ~/.claude/skills/blog/scripts/analyze_blog.py --help
Expected output:
usage: analyze_blog.py [-h] [--version] [--output OUTPUT]
[--format {json,markdown,table}] [--batch]
[--sort {score,name,words}] [--category CATEGORY]
[--fix]
input
Blog Quality Analyzer - 5-category, 100-point scoring system
...
The output above is abridged to the usage line; run the command for the full help text, which is the source of truth.
Updating
Pull the latest changes and re-run the installer:
cd claude-blog
git pull
./install.sh
The installer verifies ownership before replacing files. It can migrate a legacy directory manifest from the reviewed public v2.2.0 release or the pinned public audit baseline when installed bytes match the bundled historical hash inventory. Unknown user additions remain outside package ownership.
Modified managed files, unknown collisions and unsafe paths stop the update before payload changes. A legacy installation from another revision needs reviewed ownership evidence before automatic adoption. Restart Claude Code after a successful update.
If the installer reports "managed installation file was modified"
You edited a file the installer owns, and it will not overwrite or delete your
edit silently. Both install.sh and uninstall.sh stop, name the files and
change nothing. Safe steps:
- Copy any edit you want to keep outside
~/.claude/skills,~/.claude/agentsand~/.claude/scripts. - Run
bash install.sh --force-adopt(orbash uninstall.sh --force-adopt). Each modified file is first copied to~/.claude/claude-blog-backups/<timestamp>/with its relative path, then replaced (install) or removed (uninstall). Missing managed files are tolerated in this mode; a path replaced by a directory or symlink is still refused, and a backup directory that is a symlink aborts before any change. - Re-apply your edits from the backup if you still want them.
Backups are never deleted by the installer. On Windows the flag is
-ForceAdopt (--force-adopt is also accepted) for both install.ps1 and
uninstall.ps1; it uses the same backup folder
(~/.claude/claude-blog-backups/<timestamp>/) and also tolerates a managed file
you deleted. Without it, a Windows install or uninstall refuses and names the
files.
If uninstall.sh finds no manifest it removes nothing and says so. That is
normal for a plugin install (use /plugin uninstall claude-blog@agricidaniel-blog
instead) or when the manifest was already removed.
Uninstall
Automated Uninstall (Unix)
# From the claude-blog repository
chmod +x uninstall.sh
./uninstall.sh
The uninstaller removes verified package-owned files from:
~/.claude/skills/blog/and~/.claude/skills/blog-*/(32 skill directories: 1 orchestrator + 31 sub-skills; 30 user-facing commands;blog-chartis internal-only)~/.claude/scripts/(the rootscripts/*.pyhelpers, 23 at the time of writing, including the sharedinstaller_ownership.pyengine)~/.claude/agents/blog-*.md(all 5 agents: blog-researcher, blog-writer, blog-seo, blog-reviewer, blog-translator)
Shared Google credentials under ~/.config/claude-seo/ are owned by the user
and may be used by other skills. Both uninstallers leave them intact.
User additions and unknown skills remain. Directories are pruned only after
verified files are removed and only when empty. Modified managed files or
unsafe ownership paths stop removal before payload changes.
Manual Uninstall
Use the ownership-aware uninstaller from the reviewed repository. For manual
recovery, inspect ~/.claude/claude-blog-manifest.txt, preserve local edits,
and remove only individually verified package files. A directory name or
blog-* prefix alone does not establish ownership. Keep unknown files and
prune a directory only after confirming it is empty.
Clean Up Python Dependencies (Optional)
Remove dependencies only from a disposable environment dedicated to this plugin. Shared Python environments can support other skills, so their dependency ownership must be reviewed separately.
Restart Claude Code after uninstalling to complete removal.
Troubleshooting Installation
| Symptom | Cause | Fix |
|---|---|---|
/blog command not found |
Claude Code not restarted | Close and reopen Claude Code |
python3: command not found |
Python not installed or not in PATH | Install Python 3.11+ via your package manager |
pip install fails |
Missing pip or wrong Python version | Run python3 -m ensurepip --upgrade |
Permission denied on install.sh |
Script not executable | Run chmod +x install.sh |
Files not in ~/.claude/ |
Wrong install location | Verify $HOME points to your home directory |
For additional issues, see TROUBLESHOOTING.md.