ghost-cms-skill

name	ghost-cms-skill
description	Comprehensive Ghost CMS integration for creating, publishing, scheduling, and managing blog content, newsletters, members, and analytics. Use when working with Ghost blogs for content creation (drafts, publishing, scheduling), member/subscriber management (tiers, newsletters), comment moderation, or analytics (popular posts, subscriber growth). Supports all Ghost Admin API operations.
author	Chris Giddings
homepage	https://github.com/chrisagiddings/moltbot-ghost-skill
repository	https://github.com/chrisagiddings/moltbot-ghost-skill
metadata	{"openclaw":{"disable-model-invocation":true,"capabilities":["content-management","member-management","subscription-management","comment-management","user-management","media-management","destructive-operations","public-publishing"],"requires":{"env":["GHOST_ADMIN_KEY","GHOST_API_URL"],"bins":["node","npm"]},"primaryEnv":"GHOST_ADMIN_KEY","install":{"type":"npm","directory":"scripts","command":"npm install","dependencies":["form-data@^4.0.5","jsonwebtoken@^9.0.3"]},"credentials":{"types":[{"type":"file","locations":["~/.config/ghost/api_key","~/.config/ghost/api_url"],"description":"Ghost Admin API credentials"},{"type":"env","variables":[{"name":"GHOST_ADMIN_KEY","description":"Ghost Admin API key (JWT)","required":true},{"name":"GHOST_API_URL","description":"Ghost site URL (Ghost Pro OR self-hosted, include :PORT if needed)","required":true}]}]}}}

Ghost CMS

Manage Ghost blog content, members, analytics, and newsletters through the Ghost Admin API.

⚠️ Security Warning

Ghost Admin API keys provide FULL access to your Ghost site:

• Content Management: Create, update, delete, publish posts and pages
• Member Management: Add, modify, delete members and subscriptions
• Subscription Management: Create, modify, delete membership tiers
• Comment Management: Reply to, approve, delete comments
• User Management: Invite, modify, delete users
• Media Management: Upload images and files (affects storage)
• Site Configuration: Modify newsletters and settings

Published content is IMMEDIATELY PUBLIC - be extra careful with publish operations.

Security Best Practices:

• Store API keys securely - Use 1Password CLI or secure env vars
• Review before publishing - Always check content before making it public
• Never commit keys - Keep credentials out of version control
• Rotate keys regularly - Create new integrations every 90 days
• Use dedicated integrations - Separate keys for different use cases
• Test on staging first - Use a test Ghost site when possible

Admin API Key Scope: Ghost Admin API keys have no scoping options - they provide full access to everything. There are no read-only keys.

Operation Types:

Read-Only Operations (✅ Safe):

• List posts, pages, tags, members, tiers, newsletters, comments
• Get analytics and member stats
• All GET requests

Destructive Operations (⚠️ Modify or delete data, may be public):

• Create/update/delete posts, pages, tags (POST, PUT, DELETE)
• Publish/unpublish/schedule posts (makes content public)
• Create/update/delete members, tiers, newsletters
• Create replies, approve/delete comments
• Upload images (uses storage quota)
• All POST, PUT, DELETE requests

For detailed operation documentation, see api-reference.md.

Quick Setup

1. Get your Ghost Admin API credentials:

   • Ghost dashboard → Settings → Integrations
   • Create a new "Custom Integration"
   • Copy the Admin API Key and API URL

2. Store credentials securely:

   Option A: Environment Variables (Recommended)

   # Add to your shell profile (~/.zshrc, ~/.bashrc)
   export GHOST_ADMIN_KEY="YOUR_ADMIN_API_KEY"
   export GHOST_API_URL="YOUR_GHOST_URL"
   

   API URL Examples (works with ALL hosting types):

   # Ghost(Pro) hosted
   export GHOST_API_URL="https://yourblog.ghost.io"
   
   # Self-hosted with reverse proxy (production)
   export GHOST_API_URL="https://blog.yourdomain.com"
   
   # Self-hosted development (Ghost default port 2368)
   export GHOST_API_URL="http://localhost:2368"
   
   # Self-hosted with custom port
   export GHOST_API_URL="https://ghost.example.com:8080"
   

   Important:

   • Always include protocol (http:// or https://)
   • Include :PORT if Ghost runs on non-standard port
   • Do NOT include trailing slash
   • Do NOT include /ghost/api/admin (added automatically)

   Option B: Config Files

   mkdir -p ~/.config/ghost
   echo "YOUR_ADMIN_API_KEY" > ~/.config/ghost/api_key
   echo "YOUR_GHOST_URL" > ~/.config/ghost/api_url
   
   # Secure the files (owner read-only)
   chmod 600 ~/.config/ghost/api_key
   chmod 600 ~/.config/ghost/api_url
   

   Option C: 1Password CLI (Most Secure)

   # Store key in 1Password
   op item create --category=API_CREDENTIAL \
     --title="Ghost Admin API" \
     admin_key[password]="YOUR_ADMIN_API_KEY" \
     api_url[text]="YOUR_GHOST_URL"
   
   # Use in commands
   export GHOST_ADMIN_KEY=$(op read "op://Private/Ghost Admin API/admin_key")
   export GHOST_API_URL=$(op read "op://Private/Ghost Admin API/api_url")
   

   Security Notes:

   • Keys provide full site access - protect them like passwords
   • Rotate keys every 90 days (create new integration, revoke old)
   • Never commit to git or share keys publicly
   • Consider separate keys for production vs. staging
   • HTTPS recommended: Use HTTPS for production (HTTP acceptable for localhost only)

3. Install dependencies:

   cd ghost-cms-skill/scripts
   npm install
   

   Dependencies installed:

   • form-data (^4.0.5) - Multipart file uploads (theme ZIP files)
   • jsonwebtoken (^9.0.3) - JWT token generation for Ghost Admin API authentication

   Optional dependencies (install manually if needed):

   • gscan (^5.2.4) - Official Ghost theme validator (from TryGhost)
     • Only needed for theme validation feature
     • Install with: cd scripts && npm install gscan

   All dependencies from public npm registry. No custom downloads.

4. Test connection: See setup.md for detailed authentication and troubleshooting.

Tools & Utilities

Snippet Extractor

Purpose: Migrate existing Ghost snippets to local library for programmatic use.

Why needed: Ghost Admin API blocks snippet access (403 Forbidden) for integration tokens. This tool works around that limitation.

Usage:

# Extract snippets from a specially-formatted draft post
node scripts/snippet-extractor.js my-snippets-post

# Validate format before extracting
node scripts/snippet-extractor.js my-snippets-post --validate

# Preview without saving
node scripts/snippet-extractor.js my-snippets-post --dry-run

# Custom marker prefix
node scripts/snippet-extractor.js my-snippets-post --marker "This is:"

# Full help
node scripts/snippet-extractor.js --help

Workflow:

1. Create draft post in Ghost
2. For each snippet: add paragraph marker (e.g., "SNIPPET: name" or "This is: name")
3. Insert the snippet content below each marker
4. Run extractor → all snippets saved to snippets/library/

Features:

• ✅ Extracts all card types (bookmarks, callouts, images, markdown, HTML, etc.)
• ✅ Preserves exact Lexical structure
• ✅ Auto-detects credentials from ~/.config/ghost/ or env vars
• ✅ Supports custom marker formats
• ✅ Dry-run and validation modes
• ✅ Verbose output for debugging

Example:

# User has 12 snippets in Ghost
# Creates "My Snippets" draft with markers
# Runs: node scripts/snippet-extractor.js my-snippets --marker "This is:"
# Result: All 12 snippets in library/ ready for use

See snippets/README.md for complete documentation.

Theme Manager

Purpose: Upload, activate, switch, and manage Ghost themes programmatically.

Why needed: Automate theme deployments, switch themes, manage theme versions.

Usage:

cd scripts

# List all installed themes
node theme-manager.js list

# Upload theme ZIP
node theme-manager.js upload /path/to/theme.zip

# Upload and activate immediately
node theme-manager.js upload /path/to/theme.zip --activate

# Activate existing theme
node theme-manager.js activate theme-name

# Download theme backup
node theme-manager.js download theme-name backup.zip

# Delete theme (cannot delete active theme)
node theme-manager.js delete old-theme

# Show current active theme
node theme-manager.js active

Features:

• ✅ Upload custom themes from ZIP files
• ✅ Switch between installed themes
• ✅ Download theme backups
• ✅ Delete unused themes
• ✅ Validation and error handling
• ✅ Immediate activation - theme changes are public instantly

⚠️ Important:

• Theme activation is immediate and public - site appearance changes instantly
• Cannot delete the currently active theme (switch first)
• Themes must be valid Ghost theme ZIP files

Workflow:

# Safe theme switching with rollback
node theme-manager.js active              # Note current theme
node theme-manager.js activate new-theme  # Switch to new theme
# Test site in browser
node theme-manager.js activate old-theme  # Rollback if needed

See references/themes.md for complete theme management documentation and best practices.

Theme Validator

Purpose: Validate Ghost themes before uploading using official gscan validator.

⚠️ Optional Feature: Requires gscan package. Install with:

cd scripts
npm install gscan

Why needed: Catch errors early - missing files, invalid syntax, deprecated helpers, version incompatibility.

Usage:

cd scripts

# Validate theme directory
node theme-validator.js ~/themes/my-theme/

# Validate ZIP file  
node theme-validator.js theme.zip

# Target specific Ghost version
node theme-validator.js theme.zip --version v6

# JSON output for CI/CD
node theme-validator.js theme.zip --json

# Show only errors (hide warnings)
node theme-validator.js theme.zip --errors-only

Features:

• ✅ Official Ghost validator (gscan from TryGhost)
• ✅ Same validation as Ghost Admin
• ✅ Validates directories or ZIP files
• ✅ Ghost v5/v6 compatibility checking
• ✅ Finds deprecated helpers and syntax errors
• ✅ CI/CD integration (JSON output, exit codes)
• ✅ Categorized issues (errors, warnings, recommendations)

Validation levels:

• Errors - Must fix before upload (theme will be rejected)
• Warnings - Should fix for best compatibility
• Recommendations - Nice to have (best practices)

Safe deployment workflow:

# 1. Validate before upload
node theme-validator.js my-theme.zip

# 2. Fix any errors

# 3. Re-validate
node theme-validator.js my-theme.zip

# 4. Upload when clean
node theme-manager.js upload my-theme.zip

CI/CD integration:

node theme-validator.js theme.zip --json
if [ $? -eq 0 ]; then
  node theme-manager.js upload theme.zip --activate
fi

Exit codes: 0 = valid, 1 = errors found, 2 = invalid arguments

See references/themes.md for complete validation documentation and common error fixes.

---

Core Operations

This skill covers all major Ghost operations. Navigate to the relevant reference for detailed guidance:

Content Management

When to use: Creating drafts, publishing posts, scheduling content, managing pages

See content.md for:

• Creating new posts (drafts)
• Publishing and scheduling posts
• Updating existing content
• Managing tags, featured images, metadata
• Working with pages vs posts

See lexical-cards.md for:

• Complete Lexical card type reference (23 documented types)
• Most comprehensive Ghost Lexical documentation available
• Full JSON structures with field references
• Video, audio, file uploads, buttons, toggles, embeds
• Product cards, headers, call-to-action, paywall
• Member visibility and content personalization

⚠️ Ghost Snippets Limitation:

Ghost's native snippet feature (reusable content blocks saved in the editor) cannot be accessed via the Admin API with integration tokens (403 Forbidden). This means:

• ❌ Cannot list available snippets
• ❌ Cannot fetch snippet content
• ❌ Cannot programmatically use author's existing snippets

Solution: Automated Snippet Extraction

The skill includes a snippet extractor tool that migrates Ghost snippets to local files:

1. Create extraction post in Ghost with all snippets (one-time setup)
2. Run extractor: node scripts/snippet-extractor.js post-slug
3. Done! All snippets saved to snippets/library/ for programmatic use

Commands:

# Extract snippets (auto-detects credentials from ~/.config/ghost/)
node scripts/snippet-extractor.js my-snippets-post

# Validate format before extracting
node scripts/snippet-extractor.js my-snippets-post --validate

# Preview without saving
node scripts/snippet-extractor.js my-snippets-post --dry-run

# Custom marker format
node scripts/snippet-extractor.js my-snippets-post --marker "This is:"

# Full help
node scripts/snippet-extractor.js --help

Benefits:

• ✅ Migrate all existing Ghost snippets in seconds
• ✅ Preserves exact Lexical structure (bookmarks, callouts, images, etc.)
• ✅ Git version control
• ✅ Use programmatically in automated posts
• ✅ Works with any card types

See snippets/README.md for complete documentation on extraction workflow and local snippet usage.

Analytics & Insights

When to use: Checking subscriber counts, popular content, traffic trends

See analytics.md for:

• Subscriber growth and counts
• Most popular posts (views, engagement)
• Tag/topic performance over time
• Member tier distribution

Comments & Engagement

When to use: Responding to comments, moderating discussions

See comments.md for:

• Listing pending/unanswered comments
• Responding to comments
• Comment moderation

Members & Subscribers

When to use: Managing subscriber tiers, member access, premium content

See members.md for:

• Subscriber tier management
• Member-only content settings
• Recent subscriber activity
• Subscription status

Newsletters

When to use: Managing newsletter settings, email campaigns

See newsletters.md for:

• Newsletter configuration
• Sending newsletters
• Subscriber email settings

API Reference

For advanced operations or endpoint details, see api-reference.md.

Common Workflows

Draft → Notion → Ghost:

1. Draft content collaboratively in Notion
2. Finalize content
3. Use this skill to copy to Ghost as draft
4. Review in Ghost admin
5. Schedule or publish

Weekly content series:

1. "Navi, write and publish a unique weekly post about [topic from our discussions this week]"
2. Skill creates post, sets author to "Navi", publishes automatically

Comment management:

1. "Are there any pending comments?"
2. Review list of comments with post titles
3. "Respond to comment #123 with [response]"

Analytics check:

1. "What tags have been most popular in the past 6 months?"
2. "How many new subscribers this month?"
3. "When was my last subscriber-exclusive post?"