CLAUDE.md@brain/.raw/sources/claude-blog-skill · git:20260709.9bf0b3e · 2026-07-09 · sha256 8ae778a77436654c
CLAUDE.md@brain/.raw/sources/claude-blog-skill git:20260709.9bf0b3eA
Immutable. This exact content is served forever at /api/v1/blob/8ae778a77436654c.
# Claude Blog - Blog Creation & Optimization Skill
## Project Overview
This repository contains **Claude Blog**, a Tier 4 Claude Code skill for blog content
creation, optimization, and management. It follows the Agent Skills open standard and the
3-layer architecture (directive, orchestration, execution). 32 skill directories
(1 orchestrator + 31 sub-skills), 30 user-facing `/blog` commands, 5 specialized
subagents, 12 content templates, and 22 reference docs are dual-optimized for Google rankings
(2026 core and spam update timeline, E-E-A-T) and AI citations (GEO/AEO). Includes FLOW framework
integration, semantic topic-cluster planning + execution, multilingual publishing (Pro Hub
Challenge v1.7.0), BRAND.md/VOICE.md/DISCOURSE.md project-root context auto-load (v1.8.0,
fenced via `scripts/load_untrusted_root.py` with CSPRNG nonces, v1.8.3+), CI-enforced
prose hygiene via `scripts/lint_prose.py` (v1.8.4+), and the 5-gate Blog Delivery Contract
(v1.9.0, `skills/blog/references/blog-delivery-contract.md`) that runs `blog_preflight.py`
+ a BLOCKING `blog-reviewer` agent between every draft and the user.
## Architecture
```
claude-blog/
CLAUDE.md # Project instructions (this file)
docs/CONTRIBUTORS.md # Pro Hub Challenge attribution and integration decisions
CHANGELOG.md # Keep a Changelog format
.claude-plugin/plugin.json # Plugin manifest (v1.11.0)
.claude-plugin/marketplace.json # Marketplace catalog for distribution
.mcp.example.json # MCP config example (tracked; .mcp.json is gitignored)
pyproject.toml # Python packaging (3.11+)
scripts/analyze_blog.py # 5-category quality scoring (stdlib)
scripts/blog_preflight.py # 5-gate delivery contract runner (v1.9.0)
scripts/blog_render.py # md -> html -> pdf renderer; XSS-safe JSON-LD (v1.9.0)
scripts/blog_hygiene.py # Optional deterministic hygiene: lazy-load imgs + auto-TOC (v1.11.0)
scripts/cognitive_load.py # Per-section concept-density analyzer (v1.8.0)
scripts/discourse_research.py # Discourse brief synthesis from SERP JSON (v1.8.0)
scripts/generate_hero.py # Hero image ladder: Banana -> Gemini -> stock -> Openverse (v1.9.0)
scripts/load_untrusted_root.py # Code-enforced fence helper for BRAND/VOICE/DISCOURSE (v1.8.3)
scripts/lint_prose.py # Fence-aware prose-hygiene linter (v1.8.4; CI-enforced)
scripts/sync_flow.py # Pulls FLOW references (stdlib, sandboxed)
scripts/ai_citation_score.py # AI citation probability 0-100 per post (v1.10.0)
scripts/content_decay.py # GSC content-decay detector: 20%+ QoQ decline (v1.10.0)
scripts/quality_gate.py # Pre-commit gate: block posts scoring < 70 (v1.10.0)
scripts/style_learn.py # Author voice-profile learner from sample posts (v1.10.0)
skills/ # 32 skill directories (1 orchestrator + 31 sub-skills)
blog/SKILL.md # Main orchestrator, routing, scoring
references/ # 22 on-demand knowledge files (5 in v1.8.0, 1 in v1.9.0)
templates/ # 12 content templates
scripts/ # Python analysis scripts
blog-write/SKILL.md # Write new articles from scratch
blog-rewrite/SKILL.md # Optimize existing blog posts
blog-analyze/SKILL.md # 5-category 100-point scoring
blog-brief/SKILL.md # Detailed content briefs
blog-outline/SKILL.md # SERP-informed outlines
blog-calendar/SKILL.md # Editorial calendars
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-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)
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-taxonomy/SKILL.md # CMS taxonomy management
blog-notebooklm/ # NotebookLM source-grounded research
SKILL.md # NotebookLM query sub-skill
references/ # 2 reference docs (commands, troubleshooting)
scripts/ # 10 Python scripts + requirements.txt
blog-audio/ # Audio narration via Gemini TTS
SKILL.md # Audio generation sub-skill
references/ # 1 reference doc (30 voice catalog)
scripts/ # 5 Python scripts + requirements.txt
blog-google/ # Google API integration
SKILL.md # Google API sub-skill (13 commands, 4 tiers)
references/ # 3 reference docs (auth, API, quotas)
scripts/ # 11 Google API scripts + venv wrapper
assets/templates/ # 3 report templates
blog-cluster/ # Semantic topic-cluster planning + execution (v1.7.0)
SKILL.md # Cluster planning + execute orchestrator
references/ # 3 ref docs (semantic clustering, architecture, execution)
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)
blog-multilingual/ # One-command international publishing (v1.7.0)
SKILL.md # Multilingual orchestrator
blog-translate/ # SEO-optimized translation (v1.7.0)
SKILL.md
references/ # Translation rules + cultural adaptation profiles
blog-localize/ # Cultural deep-adaptation (v1.7.0)
SKILL.md
blog-locale-audit/ # Multilingual content QA (v1.7.0)
SKILL.md
blog-brand/SKILL.md # BRAND.md + VOICE.md context files (v1.8.0)
blog-discourse/SKILL.md # Last-30-days discourse research (v1.8.0)
blog-style/SKILL.md # Author voice-profile learner (v1.10.0)
blog-decay/SKILL.md # GSC content-decay detector (v1.10.0)
agents/ # 5 specialized subagents
blog-researcher.md # Statistics and source research
blog-writer.md # Content generation
blog-seo.md # SEO validation
blog-reviewer.md # Quality scoring (no Bash, post v1.7.0 hardening)
blog-translator.md # Multilingual translation (no Bash, v1.7.0)
tests/ # pytest suite (242 tests) incl. test_blog_delivery_contract.py + test_security_guardrails.py
```
## Commands
| Command | Purpose |
|---------|---------|
| `/blog write` | Write new articles optimized for rankings + AI citations |
| `/blog rewrite` | Optimize existing posts with sourced statistics; `/blog update` aliases here |
| `/blog analyze` | 5-category 100-point scoring with AI detection |
| `/blog brief` | Detailed content briefs with competitive analysis |
| `/blog outline` | SERP-informed outlines with heading hierarchy |
| `/blog calendar` | Editorial calendars with topic clusters |
| `/blog strategy` | Blog positioning and content planning |
| `/blog seo-check` | Post-writing SEO validation checklist |
| `/blog schema` | JSON-LD schema markup generation |
| `/blog repurpose` | Multi-platform content repurposing |
| `/blog geo` | AI citation optimization audit |
| `/blog image` | AI image generation and editing via Gemini |
| `/blog audit` | Full-site blog health assessment |
| `/blog cannibalization` | Detect keyword overlap across posts |
| `/blog factcheck` | Verify statistics against cited sources |
| `/blog persona` | Manage writing personas and voice profiles |
| `/blog taxonomy` | Tag/category CMS management |
| `/blog notebooklm` | Query NotebookLM for source-grounded research |
| `/blog audio` | Generate audio narration via Gemini TTS |
| `/blog google` | Google API data: PSI, CrUX, GSC, GA4, NLP, YouTube, Keywords |
| `/blog cluster` | Semantic topic-cluster planning + execution (v1.7.0) |
| `/blog multilingual` | Write + translate + localize + emit hreflang in one command (v1.7.0) |
| `/blog translate` | SEO-optimized translation with format preservation (v1.7.0) |
| `/blog localize` | Cultural deep-adaptation per locale (v1.7.0) |
| `/blog locale-audit` | Multilingual content QA (v1.7.0) |
| `/blog flow` | FLOW framework prompts: find, optimize, win, prompts index, sync (v1.7.0) |
| `/blog brand` | Generate BRAND.md + VOICE.md context auto-loaded by all sub-skills (v1.8.0) |
| `/blog discourse` | API-free last-30-days discourse research; produces DISCOURSE.md (v1.8.0) |
| `/blog style` | Learn author voice profile from existing posts (v1.10.0) |
| `/blog decay` | Detect content decay from GSC exports (v1.10.0) |
Internal capability: `blog-chart` generates inline SVG charts for `/blog write`
and `/blog rewrite`; it is not a top-level user command.
## Development Rules
- Keep SKILL.md files under 500 lines / 5000 tokens
- SKILL.md frontmatter: only valid fields (name, description, user-invokable, argument-hint, compatibility, license, metadata, disable-model-invocation). Do NOT use `allowed-tools`; it is not a Claude Code spec field
- New reference files should be focused and under 200 lines. Existing comprehensive references (platform-guides, schema-stack, content-templates, distribution-playbook) are exempt from this guideline
- Scripts must have docstrings, CLI interface, and JSON output
- Follow kebab-case naming for all skill directories
- Agents invoked via Task tool, never via Bash
- Python 3.11+ required; dependencies in pyproject.toml
- Test with `python3 -m pytest tests/` after changes
- Run `claude plugin validate .` before pushing plugin changes
- Run `python3 scripts/lint_prose.py` locally to catch forbidden prose chars before CI does (v1.8.4+)
- Project-root file loading (BRAND.md/VOICE.md/DISCOURSE.md): use `scripts/load_untrusted_root.py` via Bash; never hand-roll a fence (v1.8.3+)
- Plugin skills auto-discovered from `skills/` directory (do not list in plugin.json)
## Distribution
### Anthropic Official Marketplace
Submit at: claude.ai/settings/plugins/submit or platform.claude.com/plugins/submit
### Self-Hosted Marketplace
```
/plugin marketplace add AI-Marketing-Hub/claude-blog
/plugin install claude-blog@ai-marketing-hub-claude-blog
```
### Standalone Install (no marketplace)
```bash
curl -sL https://raw.githubusercontent.com/AI-Marketing-Hub/claude-blog/main/install.sh | CLAUDE_BLOG_REF=v1.11.0 bash
```
## Release Blog Post
After cutting a new release (git tag + `gh release create`), run:
```
/release-blog
```
This generates a blog post on https://claude-blog.md/blog/, handles cover image generation, SEO metadata, FAQ schema, internal linking, sitemap/llms.txt updates, Vercel deployment, and Google indexing.