Skip to content

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.

17.7 KB
Raw Blame

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:

  1. Close Claude Code completely (exit the CLI or close the terminal)
  2. Reopen Claude Code
  3. 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:

  1. Templates not installed: Verify the templates directory exists:

    ls ~/.claude/skills/blog/templates/
    

    If empty or missing, re-run ./install.sh.

  2. Wrong install path: Templates must be in ~/.claude/skills/blog/templates/, not in the repository's skills/blog/templates/ directory.

  3. 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:

  1. Agent file not installed: Check that agent files exist:

    ls ~/.claude/agents/blog-*.md
    

    Expected: blog-researcher.md, blog-writer.md, blog-seo.md, blog-reviewer.md, blog-translator.md

  2. Skill metadata or tool restrictions: validate frontmatter with python3 scripts/validate_skills.py --root . in the source checkout. The correct visibility field is user-invocable; allowed-tools is 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. Agent tools fields define their tool allowlists; ensure the orchestrator can delegate and passes resolved reference paths to the child.

  3. Claude Code version: Agent spawning via Task requires 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:

  1. Verify reference files exist:
    ls ~/.claude/skills/blog/references/
    
  2. 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:

  1. 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> in layout.tsx
    • Hugo: Add to template <head> partial
    • WordPress: Use a plugin that renders in PHP, not JS
  2. Schema in wrong format: The analyzer looks for <script type="application/ld+json"> blocks. Other formats (Microdata, RDFa) may not be detected.

  3. 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 @context or @type fields
  • dateModified not matching lastUpdated in frontmatter
  • Image URL not accessible (returns 404)
  • Author @type should be Person, not Organization

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 &lt; 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-chart invocation 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 write with the brief (skips research phase)
  • For analysis, use analyze_blog.py directly 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:

  1. Check the version: Ensure you have the latest claude-blog installed:

    cd claude-blog && git pull && ./install.sh
    
  2. Verify file integrity: Compare installed files with the repository:

    diff ~/.claude/skills/blog/SKILL.md skills/blog/SKILL.md
    
  3. Reset installation: Remove and reinstall:

    ./uninstall.sh && ./install.sh
    

    If this stops with "managed installation file was modified", follow the --force-adopt recovery above. Run these from a checkout of a release that contains the ownership-aware installer, not the v2.2.0 tag.

  4. Open an issue: https://github.com/AgriciDaniel/claude-blog/issues