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.
Troubleshooting
Common issues, their causes, and fixes for claude-blog. Issues are grouped
by category and ordered from most to least common.
Installation Issues
"Command not found" after installation
Symptom: Running /blog write produces no response or a "skill not found"
error.
Cause: Claude Code caches skill definitions at startup. New skills are not detected until the CLI is restarted.
Fix:
- Close Claude Code completely (exit the CLI or close the terminal)
- Reopen Claude Code
- Try
/blog write <topic>again
Python script errors
Symptom: /blog analyze fails when running analyze_blog.py, or the
script exits with an import error.
Cause: Python dependencies are not installed.
Fix: use a virtual environment, so no system Python is modified and no
sudo is needed:
python3 -m venv ~/.claude-blog-venv
~/.claude-blog-venv/bin/python -m pip install -r requirements.txt
Then run the helper scripts with ~/.claude-blog-venv/bin/python (or activate
the environment first). Outside a virtual environment, python3 -m pip install --user -r requirements.txt works on Python builds that are not externally
managed.
Installer warns "pip install failed" or "externally managed"
Symptom: install.sh finishes, but prints WARNING: pip install failed,
possibly mentioning externally-managed-environment (PEP 668).
Cause: Debian, Fedora, Homebrew and similar Pythons refuse package installs outside a virtual environment. The skills are already installed; only the optional Python extras are missing.
Fix: create the virtual environment shown above. Do not use sudo or
--break-system-packages. Set CLAUDE_BLOG_SKIP_PIP=1 to silence the step.
Installer says "python3 3.x found; python3 3.11+ is required"
Cause: macOS ships /usr/bin/python3 at 3.9 or older, and some Linux
releases ship 3.10 or older.
Fix: install a current Python (brew install [email protected], the python.org
installer, uv python install 3.12, or your distribution's python3.12
package), open a new terminal, confirm python3 --version reports 3.11 or
newer, then run the installer again.
Installer says "managed installation file was modified"
Cause: a file the installer owns was edited after installation. Both
install.sh and uninstall.sh refuse to overwrite or delete it and change
nothing.
Fix: copy any edit you want to keep somewhere outside ~/.claude, then run
bash install.sh --force-adopt (or bash uninstall.sh --force-adopt). Each
modified file is first copied to ~/.claude/claude-blog-backups/<timestamp>/.
Re-apply your edits from there. Details and limits:
INSTALLATION.md.
Plugin validate reports "claude-blog" as reserved
Symptom: claude plugin validate . fails with Plugin name "claude-blog" is reserved: it passes as one of Anthropic's own.
Cause: newer Claude Code validators reserve third-party plugin names that
start with claude-. Verified results for this repository: Claude Code 2.1.218
passes; 2.1.292 and 2.1.296 fail on this one error only (plus a harmless
warning that a root CLAUDE.md is not loaded as plugin context). The v2.2.0
release fails the same way. In maintainer testing the plugin still installs and
loads, so treat it as a validation error, not an observed install failure.
What to do: nothing for normal use. CI runs the validator through
.github/scripts/validate_plugin_tolerate_reserved_name.py, which tolerates
exactly this finding (and the root CLAUDE.md notice) and fails on anything else. The project's own tests and
scripts/validate_public_release.py do not depend on the newer validator. If a
future Claude Code release enforces the reservation when installing, report it
in an issue; the standalone installer is unaffected.
Missing textstat or beautifulsoup4
Symptom: analyze_blog.py runs but reports ModuleNotFoundError: No module named 'textstat' or similar.
Cause: The optional Python dependencies are not installed.
Behavior: The analysis script is designed for graceful degradation. Without optional dependencies, it falls back to basic mode:
| Dependency | When Missing | Fallback |
|---|---|---|
| textstat | No Flesch/Gunning Fog scores | Sentence length heuristics |
| beautifulsoup4 | No HTML schema parsing | Regex-based detection |
| lxml | BeautifulSoup uses html.parser | Slower but functional |
| spacy | No NER analysis | Skipped (optional feature) |
| sentence-transformers | No semantic similarity | Skipped (optional feature) |
| scikit-learn | No topic clustering | Skipped (optional feature) |
| language-tool-python | No grammar checking | Skipped (optional feature) |
The script will produce results with reduced detail but will not crash. Install dependencies for full functionality:
pip install -r requirements.txt # Core deps
# Optional (install individually as needed):
pip install spacy sentence-transformers scikit-learn language-tool-python
Permission denied on install.sh
Symptom: ./install.sh returns "Permission denied".
Fix:
chmod +x install.sh
./install.sh
Windows: PowerShell execution policy blocks install
Symptom: install.ps1 fails with "running scripts is disabled on this
system."
Fix:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-WebRequest `
-Uri https://raw.githubusercontent.com/AgriciDaniel/claude-blog/main/install.ps1 `
-OutFile install.ps1
Get-FileHash ./install.ps1 -Algorithm SHA256
pwsh -File ./install.ps1
Inspect the downloaded file and compare its digest with the release documentation before running it.
Content Quality Issues
Low quality scores (below 60)
Symptom: /blog analyze returns a score below 60 ("Poor" rating).
Common Causes and Fixes:
| Issue | Impact | Fix |
|---|---|---|
| Important claims lack clarity or support | Readiness and content points vary | State the point early and add verified evidence where needed; no fixed length |
| Fabricated statistics | Critical integrity issue | Remove or replace with verified support |
| Missing images | Context-dependent | Add an image only when it improves understanding |
| Missing charts | Context-dependent | Add a chart only when data relationships need one |
| No FAQ section | No score penalty | Add Q&A only when genuine reader questions warrant it |
| Difficult paragraph pacing | Advisory only | Split or combine passages when comprehension improves |
Missing lastUpdated |
No automatic penalty | Add it only after a substantive update and keep it truthful |
| Excessive self-promotion | Editorial issue | Remove promotion that distracts from the reader task |
Quick fix workflow:
1. /blog analyze <file> # Get the score and issues
2. /blog rewrite <file> # Auto-fix most issues
3. /blog analyze <file> # Verify improvement
Important section point not detected
Symptom: Score report says an important section lacks a clear, supported point even though the section contains data.
Cause: A material claim needs source support close enough for readers to identify what the source substantiates. Put evidence where it best supports comprehension; it may appear in the first or a later paragraph.
Supported placement example:
## How Does AI Search Impact Blog Traffic?
AI Overviews initially caused a 61% decline in organic CTR across 3,119 queries
in a 2025 Seer Interactive study
([Seer Interactive](https://seerinteractive.com), 2025). Later 2026 reporting
showed partial CTR rebound in some query sets, so treat this as historical
context rather than a universal current rate.
Unsupported attribution example:
## How Does AI Search Impact Blog Traffic?
The landscape of search is changing rapidly. Many marketers are concerned
about the future of organic traffic.
According to Seer Interactive, CTR declined 61%.
The problem in the second example is not paragraph position. The material measurement lacks a usable citation and enough study context to verify it.
Statistics flagged as "fabricated"
Symptom: Quality report flags statistics as fabricated or unsourced.
Cause: The scoring system looks for inline attribution within 200 characters of a number. Missing or malformed citations trigger this flag.
Correct attribution format:
initial 61% decline in organic CTR ([Seer Interactive](https://seerinteractive.com), 2025)
Formats that may not be detected:
According to a recent study, CTR declined 61%. # No source name or link
CTR declined 61% (source: Seer Interactive) # No URL
CTR declined 61%. Source: Seer Interactive [1] # Footnote style
Template Issues
Template not loading
Symptom: /blog write does not follow the expected template structure
for the content type.
Causes and fixes:
Templates not installed: Verify the templates directory exists:
ls ~/.claude/skills/blog/templates/If empty or missing, re-run
./install.sh.Wrong install path: Templates must be in
~/.claude/skills/blog/templates/, not in the repository'sskills/blog/templates/directory.Template file corrupted: Re-copy from the repository:
cp skills/blog/templates/*.md ~/.claude/skills/blog/templates/
Wrong template selected
Symptom: /blog write picks a how-to template when you wanted a listicle.
Fix: Specify the content type explicitly:
/blog write listicle: "10 Best Monitoring Tools for 2026"
/blog write --type comparison "Datadog vs Grafana"
Or state the type in natural language:
/blog write a comparison post about Datadog vs Grafana
Agent Issues
Agent not spawning
Symptom: The sub-skill does not delegate to a subagent (blog-researcher, blog-writer, etc.), and instead tries to do everything inline.
Causes:
Agent file not installed: Check that agent files exist:
ls ~/.claude/agents/blog-*.mdExpected:
blog-researcher.md,blog-writer.md,blog-seo.md,blog-reviewer.md,blog-translator.mdSkill metadata or tool restrictions: validate frontmatter with
python3 scripts/validate_skills.py --root .in the source checkout. The correct visibility field isuser-invocable;allowed-toolsis supported by Claude Code and grants permission preapprovals. It does not spawn agents or restrict the available tool pool. This project keeps skill preapprovals empty by policy. Agenttoolsfields define their tool allowlists; ensure the orchestrator can delegate and passes resolved reference paths to the child.Claude Code version: Agent spawning via
Taskrequires a recent version of Claude Code. Update to the latest version.
Agent produces low-quality output
Symptom: The blog-writer agent produces content that does not follow answer-first formatting or other rules.
Fix: This typically means the agent did not load the relevant reference files. Run the command again: the orchestrator should load references before spawning the agent. If the issue persists:
- Verify reference files exist:
ls ~/.claude/skills/blog/references/ - Re-install references:
cp skills/blog/references/*.md ~/.claude/skills/blog/references/
Schema and SEO Issues
Schema detection failing
Symptom: /blog seo-check or /blog analyze reports "No schema detected"
even though the post has JSON-LD markup.
Causes:
Schema injected via JavaScript: AI crawlers (GPTBot, ClaudeBot, PerplexityBot) and the analysis script cannot see schema that is injected client-side via JavaScript. Schema must be present in the HTML source (server-rendered).
How to check: Disable JavaScript in your browser and view source. If the
<script type="application/ld+json">block is missing, your schema is JS-injected.Fix: Move schema to server-rendered HTML:
- Next.js: Use
generateMetadata()or<script>inlayout.tsx - Hugo: Add to template
<head>partial - WordPress: Use a plugin that renders in PHP, not JS
- Next.js: Use
Schema in wrong format: The analyzer looks for
<script type="application/ld+json">blocks. Other formats (Microdata, RDFa) may not be detected.MDX FAQSchema component: If using a React component like
<FAQSchema>, ensure it renders the JSON-LD in the HTML output, not just the visual FAQ.
JSON-LD validation errors
Symptom: /blog schema generates markup that fails validation.
Fix: Test the generated JSON-LD at:
Common issues:
- Missing
@contextor@typefields dateModifiednot matchinglastUpdatedin frontmatter- Image URL not accessible (returns 404)
- Author
@typeshould bePerson, notOrganization
Delivery Gate Issues
The gates are specified once, in
skills/blog/references/blog-delivery-contract.md.
These are the messages people hit most.
Gate 4: "review verifier state missing"
Cause: the review nonce was never issued for this draft. Fix: after
rendering, run blog_preflight.py --init-review-nonce --draft <D>, spawn
blog-reviewer with that nonce, and save its report verbatim to <D>/review.md
(the reviewer has no Write tool, so the orchestrator saves it).
Gate 4: "draft changed after the review nonce was issued: "
Cause: S.md, S.html, S.pdf or the hero changed after the nonce was
issued, so the stored review no longer describes the files. This is intended
behavior, not a flaky test. Fix: re-render, re-issue the nonce and re-review.
Older state files written before digests existed skip this check with a warning.
Gate 2: placeholders, filenames, hero, PDF, source hash
Gate 2 reports leftover [IMAGE, [CHART or [INTERNAL-LINK markers, artifact
or image filenames that are not lowercase slugs, a hero that does not decode or
is smaller than 1200x630, a PDF that is not a real PDF, and an HTML
blog-source-sha256 that does not match the .md, or an .html body edited by hand after render
(blog-body-sha256). The fix for the last two is
always to re-run blog_render.py (which also refuses .html input). It also
reports static HTML problems (lang, title, meta description, one H1, heading
order, og tags, noindex, missing alt, <script>, inline handlers, iframes),
each naming the element and the fix.
Gate 5: external link failures
The renderer's own footer link is checked for its scheme only, so a fully local
article can pass offline. External links need network access: when several fail
at once the message says the cause may be a network or DNS problem on your
machine. Run curl -I <url> from the same machine to tell the difference, then
re-run the gates on a working connection.
Platform-Specific Issues
MDX compilation errors after blog write/rewrite
Symptom: The generated MDX file fails to compile in Next.js.
Common causes:
| Error | Cause | Fix |
|---|---|---|
stroke-width is not valid |
HTML attributes in JSX | Convert to camelCase: strokeWidth |
class is not valid |
HTML class in JSX |
Use className |
style="..." syntax error |
String style in JSX | Use object: style={{...}} |
Unexpected { |
Curly braces in markdown text | Escape: \{ |
< in text content |
Angle brackets in prose | Use < or wrap in backticks |
Prevention: When the platform is detected as MDX/Next.js, the sub-skills automatically use JSX-compatible syntax. If errors persist, specify the platform explicitly:
/blog write "topic" --format mdx
Hugo front matter format mismatch
Symptom: Hugo does not recognize the YAML frontmatter fields.
Fix: Hugo uses TOML frontmatter by default (+++ delimiters). If your
Hugo site uses YAML (--- delimiters), add to hugo.toml:
[markup.frontmatter]
date = ["date"]
lastmod = ["lastUpdated", "lastmod"]
Performance Issues
Commands running slowly
Symptom: /blog write or /blog brief takes a long time to complete.
Causes:
- Research phase: WebSearch calls for statistics and images can take 30-60 seconds depending on the topic
- Chart generation: Each
blog-chartinvocation adds 10-20 seconds - Large context: Loading many reference files increases processing time
Mitigation:
- Provide a brief first (
/blog brief) to pre-do research, then use/blog writewith the brief (skips research phase) - For analysis, use
analyze_blog.pydirectly for faster automated metrics
analyze_blog.py batch mode slow on large directories
Symptom: --batch mode takes a long time on directories with many files.
Fix: The script processes files sequentially. For large directories, analyze subsets:
python3 analyze_blog.py posts/2026/ --batch # Only 2026 posts
python3 analyze_blog.py posts/drafts/ --batch # Only drafts
Getting Help
If your issue is not listed here:
Check the version: Ensure you have the latest
claude-bloginstalled:cd claude-blog && git pull && ./install.shVerify file integrity: Compare installed files with the repository:
diff ~/.claude/skills/blog/SKILL.md skills/blog/SKILL.mdReset installation: Remove and reinstall:
./uninstall.sh && ./install.shIf this stops with "managed installation file was modified", follow the
--force-adoptrecovery above. Run these from a checkout of a release that contains the ownership-aware installer, not thev2.2.0tag.Open an issue: https://github.com/AgriciDaniel/claude-blog/issues