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.

docs: correct counts, validation steps and command sections

Agrici Daniel320665fe2da4
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 6268684..7f48d5c 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -7,7 +7,9 @@ Thank you for your interest in contributing to claude-blog!
1. Fork and clone the repository
2. Install dev dependencies: `pip install -e ".[dev]"`
3. Run tests: `python -m pytest tests/ -v`
-4. Validate plugin metadata: `claude plugin validate .`
+4. Validate plugin metadata: `python3 .github/scripts/validate_plugin_tolerate_reserved_name.py`
+ (plain `claude plugin validate .` on Claude Code 2.1.292 or later reports the
+ reserved `claude-` name once per manifest; the wrapper tolerates exactly that)
## Development
@@ -38,7 +40,7 @@ claude-blog/
- **Template paths** in sub-skills use `templates/` (relative to installed location).
- **Agent frontmatter** must NOT include `Bash` in the `tools` list (blast-radius reduction for prompt-injection surfaces; enforced by tests).
- Run `python -m pytest tests/ -v` before submitting.
-- Run `claude plugin validate .` before submitting.
+- Run the plugin validation wrapper from step 4 before submitting.
### Code Style
@@ -77,7 +79,7 @@ claude-blog/
1. Create a feature branch from `main`.
2. Make your changes with clear conventional-commit messages.
3. Ensure all tests pass (`python -m pytest tests/`).
-4. Ensure plugin validates (`claude plugin validate .`).
+4. Ensure plugin validates (the wrapper from the Getting Started steps).
5. Update `CHANGELOG.md` with an `[Unreleased]` entry describing the change.
6. Submit a PR using the template. Fill in: type of change, linked issue, test plan, docs checklist, and security checklist (if applicable).
diff --git a/.gitignore b/.gitignore
index 2a5e210..f5dfa31 100644
--- a/.gitignore
+++ b/.gitignore
@@ -61,7 +61,7 @@ firebase-debug.log
# Generated output
output/
demo-output/
-.raw/
+/.raw/
# Working documents
definitive-resesarch-blueprint-for-claude-blog.md
diff --git a/CLAUDE.md b/CLAUDE.md
index b802052..c15dcc7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -67,17 +67,21 @@ claude-blog/
blog-strategy/SKILL.md # Blog positioning and planning
blog-seo-check/SKILL.md # Post-writing SEO validation
blog-schema/SKILL.md # JSON-LD schema generation
- blog-chart/SKILL.md # Inline SVG data visualizations
+ blog-chart/ # Inline SVG data visualizations
+ SKILL.md
+ references/ # 1 reference doc (chart input schema)
blog-repurpose/SKILL.md # Multi-platform repurposing
blog-geo/SKILL.md # AI citation optimization
blog-audit/SKILL.md # Full-site blog health assessment
blog-image/ # AI image generation via Gemini
SKILL.md # Image generation sub-skill
- references/ # 3 reference docs (models, tools, prompts)
+ references/ # 4 reference docs (models, tools, prompts, MCP route)
scripts/ # MCP setup and validation scripts
blog-cannibalization/SKILL.md # Keyword overlap detection
blog-factcheck/SKILL.md # Statistics verification
- blog-persona/SKILL.md # Writing persona management
+ blog-persona/ # Writing persona management
+ SKILL.md
+ references/ # personas/ directory for saved personas
blog-taxonomy/SKILL.md # CMS taxonomy management
blog-notebooklm/ # NotebookLM source-grounded research
SKILL.md # NotebookLM query sub-skill
@@ -85,7 +89,7 @@ claude-blog/
scripts/ # 11 Python modules + requirements.txt/lock
blog-audio/ # Audio narration via Gemini TTS
SKILL.md # Audio generation sub-skill
- references/ # 1 reference doc (30 voice catalog)
+ references/ # 2 reference docs (30 voice catalog, dated models and pricing)
scripts/ # 5 Python scripts + requirements.txt
blog-google/ # Google API integration
SKILL.md # Google API sub-skill (13 commands, 4 tiers)
@@ -98,6 +102,7 @@ claude-blog/
blog-flow/ # FLOW framework prompts (v1.7.0)
SKILL.md # FLOW orchestrator (find/optimize/win/prompts/sync)
references/ # Synced from github.com/AgriciDaniel/flow (CC BY 4.0)
+ scripts/ # sync_flow.py wrapper around the core scripts/sync_flow.py
blog-multilingual/ # One-command international publishing (v1.7.0)
SKILL.md # Multilingual orchestrator
blog-translate/ # SEO-optimized translation (v1.7.0)
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index a7f289b..5a4e916 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -216,7 +216,7 @@ dependencies are stdlib-only or narrowly pinned.
| `dependency_smoke.py` | Offline initialization smoke checks for the optional runtimes | Maintenance |
| `discourse_research.py` | Discourse-brief synthesis from SERP JSON; depth-bounded parsing; path-traversal guards | v1.8.0 |
| `generate_hero.py` | Hero image ladder: Banana MCP -> Gemini API -> Unsplash/Pexels/Pixabay -> Openverse | v1.9.0 |
-| `installer_ownership.py` | Shared Unix legacy/v2 ownership verification, migration and rollback | Unreleased |
+| `installer_ownership.py` | Shared Unix legacy/v2 ownership verification, migration and rollback | v2.3.0 |
| `lint_prose.py` | Fence-aware prose-hygiene linter (no em-dash, en-dash, ` -- `); CI-enforced | v1.8.4 |
| `load_untrusted_root.py` | Code-enforced BRAND/VOICE/DISCOURSE fencing with CSPRNG nonces; O_NOFOLLOW + size cap | v1.8.3 |
| `quality_gate.py` | Pre-commit gate: block posts scoring < 70; fail-closed on bad paths and missing frontmatter; `--select` is the pre-commit hook mode that skips Markdown files that are not blog posts | v1.10.0 |
@@ -278,8 +278,8 @@ dependencies are stdlib-only or narrowly pinned.
+-- Writes file to user's project
|
v
- Delivery summary: md, html, pdf, hero, 3 viewport screenshots (preview/),
- review.md, preflight-report.json
+ Delivery summary: md, html, pdf, hero, 3 viewport screenshots plus a dark-mode
+ screenshot (preview/), review.md, preflight-report.json
```
The authoritative sequence and the full list of what each gate enforces live
diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md
index 547a0b8..a0e2872 100644
--- a/docs/COMMANDS.md
+++ b/docs/COMMANDS.md
@@ -6,11 +6,9 @@ blog-write/blog-rewrite.
Every command is invoked through the main orchestrator
(`skills/blog/SKILL.md`), which routes to the appropriate sub-skill.
-> **For detailed command flows beyond the overview table below, see each
-> sub-skill's `SKILL.md` directly. Sections in this file are abbreviated
-> for the v1.7.0 and v1.8.0 commands that joined after this doc was
-> originally written; the full overview table below is the canonical
-> command list.**
+> **The overview table below is the canonical command list. The sections
+> after it are short summaries; the full flow, options and limits of every
+> command live in its sub-skill's `SKILL.md`.**
## Command Overview
@@ -854,6 +852,45 @@ correctness, meta-tag parity, freshness).
---
+## /blog style
+
+**Purpose**: learn a measurable author voice profile from 5 to 10 existing
+posts, to feed `VOICE.md`, `/blog persona` and `/blog write`. The profile
+describes style (sentence length, vocabulary, transitions, phrasing); it does
+not detect or attribute authorship.
+
+```
+/blog style learn <paths>
+```
+
+The learner is `scripts/style_learn.py`; it accepts files or directories and
+the options `--min`, `--format {json,markdown}` and `--output`. Fewer samples
+than the minimum (default 5) produce a warning, not a failure.
+
+**Flow**: See `skills/blog-style/SKILL.md`.
+
+---
+
+## /blog decay
+
+**Purpose**: compare two Google Search Console page exports (current and
+previous period) and flag pages whose clicks or impressions fell by at least a
+threshold (default 20%), with a triage hint. The threshold is a screening
+heuristic, not proof of decay.
+
+```
+/blog decay <current-gsc.json> <previous-gsc.json>
+/blog decay <current-gsc.json> <previous-gsc.json> --threshold 0.30 --metric impressions
+```
+
+The analyzer is `scripts/content_decay.py` (`--threshold`, `--metric
+{clicks,impressions}`, `--format {json,markdown}`, `--output`). Both exports
+must come from the same property and use one URL form.
+
+**Flow**: See `skills/blog-decay/SKILL.md`.
+
+---
+
## Command Routing
The main orchestrator (`skills/blog/SKILL.md`) parses user input and routes to
@@ -892,6 +929,8 @@ User Input Routes To
/blog translate <file> --to --> blog-translate
/blog localize <file> --locale --> blog-localize
/blog locale-audit <directory> --> blog-locale-audit
+/blog style learn <paths> --> blog-style (v1.10.0)
+/blog decay <current> <previous> --> blog-decay (v1.10.0)
/blog flow [find|optimize|win|prompts|sync] --> blog-flow
```
diff --git a/docs/DEMO.md b/docs/DEMO.md
index a43f000..8d2cb64 100644
--- a/docs/DEMO.md
+++ b/docs/DEMO.md
@@ -135,7 +135,7 @@ here.
Output: file path under `~/Documents/nanobanana_generated/`. Banana
acts as Creative Director and constructs the 5-component prompt;
the skill auto-loads `references/gemini-models.md` and
-`references/prompt-engineering.md` per its MANDATORY rule.
+`references/prompt-engineering-blog.md` per its MANDATORY rule.
### B2. "Inline SVG chart from data"
diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md
index 93fdff9..0051d72 100644
--- a/docs/INSTALLATION.md
+++ b/docs/INSTALLATION.md
@@ -160,12 +160,8 @@ If you prefer not to run the installer, copy files to these paths manually.
├── skills/
│ ├── blog/
│ │ ├── SKILL.md # Main orchestrator
-│ │ ├── references/
-│ │ │ ├── content-rules.md
-│ │ │ ├── geo-optimization.md
-│ │ │ ├── google-landscape-2026.md
-│ │ │ ├── quality-scoring.md
-│ │ │ └── visual-media.md
+│ │ ├── references/ # 22 files; copy the whole directory
+│ │ │ └── *.md
│ │ ├── templates/ # 12 content type templates
│ │ │ └── *.md
│ │ └── scripts/