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. 1. Get your Ghost Admin API credentials:

1. 2. Store credentials securely:

Option A: Environment Variables (Recommended)
CODEBLOCK0

API URL Examples (works with ALL hosting types):
CODEBLOCK1

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
CODEBLOCK2

Option C: 1Password CLI (Most Secure)
CODEBLOCK3

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)

1. 3. Install dependencies:

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: INLINECODE7

All dependencies from public npm registry. No custom downloads.

1. 4. Test connection:

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:
CODEBLOCK5

Workflow:

1. 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 INLINECODE8

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:
CODEBLOCK6

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:
CODEBLOCK7

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:
CODEBLOCK8

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:
CODEBLOCK9

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

Usage:
CODEBLOCK10

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:
CODEBLOCK11

CI/CD integration:
CODEBLOCK12

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

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. 1. Create extraction post in Ghost with all snippets (one-time setup)
2. Run extractor: INLINECODE14
3. Done! All snippets saved to snippets/library/ for programmatic use

Commands:
CODEBLOCK13

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

See analytics.md for:

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

Comments & Engagement

See comments.md for:

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

Members & Subscribers

See members.md for:

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

Newsletters

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. 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. 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. 1. "Are there any pending comments?"
2. Review list of comments with post titles
3. "Respond to comment #123 with [response]"

Analytics check:

1. 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?"