Ghost Publishing Pro

intent

Publish, update, schedule, and audit Ghost CMS posts entirely through API calls from your workflow , no browser, no dashboard, no manual steps. use this skill when you need to write + send newsletters in one call, batch import content from WordPress/Squarespace/Substack, audit your entire site for missing metadata, analyze email performance, or repair GSC indexing. covers 17 end-to-end workflows including migrations, theme uploads, and content audits. the skill enforces hard gates on credential setup, concurrent write safety, and email delivery , these prevent 409 conflicts, missed newsletters, and irreversible bulk mistakes.

inputs

credentials file (required)

• location: ~/.openclaw/credentials/ghost-admin.json
• format: json with two fields: url (your ghost site url), key (admin api key in id:secret format)
• how to get: ghost admin > settings > integrations > add custom integration > copy admin api key
• scope: covers all post operations, image uploads, scheduling, newsletters, analytics, batch updates
• credential security: use a dedicated integration key, not owner credentials. this key is fully revocable and isolated to post/image/member operations

binaries (required)

• node (verify with node --version) , used for jwt token generation, xml parsing, and batch operations
• curl (verify with curl --version) , used for all api calls except image uploads
• python3 (verify with python3 --version) , used for image uploads only (multipart form-data requires python requests on macos/linux; curl fails silently on zsh)

optional npm dependency

• fast-xml-parser@5.7.2 , install only if running squarespace/wordpress xml migrations. all other workflows (publish, update, schedule, image upload, analytics) require zero third-party packages

external connection: ghost admin api

• endpoint: https://{your-ghost-domain}/ghost/api/admin/
• auth method: short-lived jwt tokens (5-minute expiry), generated fresh before each api call
• token generation: uses node.js built-ins (fs, standard hmac module) , no npm required. implementation in references/api.md
• rate limits: ghost pro allows 2,000 requests per 5 minutes per integration key. batch operations should add 500ms delay between calls
• network timeouts: set curl timeout to 30s minimum for large image uploads; regenerate token every 50 posts in long operations

ghost platform limitations (out of scope)

• staff management: owner-only, no api path
• site settings / code injection write: returns 403 noPermissionError for integration tokens by design
• redirects management: post /admin/redirects/ returns 403 for integration tokens
• these are ghost platform restrictions, not skill gaps. the skill does not provide workarounds

procedure

step 1: verify credentials file exists and is valid

input: filesystem access to ~/.openclaw/credentials/ghost-admin.json

action: read the file and parse json. confirm both url and key fields are present and non-empty. do not proceed if file is missing or malformed.

output: shell variable GHOST_URL set to the url value; GHOST_KEY set to the key value (format id:secret)

edge case: if file is missing, fail with "credentials file not found at ~/.openclaw/credentials/ghost-admin.json. create it first with url and key fields." do not attempt to create it automatically.

step 2: generate jwt token before every api call

input: GHOST_KEY (id:secret format), current unix timestamp, 5-minute expiry window

action: parse the key into id and secret. use node.js built-in hmac to generate a jwt token with payload containing iat (issued at), exp (expires at +5 minutes), and aud (audience = /admin/). encode as {header}.{payload}.{signature}. the full implementation is in references/api.md , copy it into your workflow.

output: shell variable TOKEN set to the jwt string

edge case: if token generation fails (bad key format, wrong binary), fail with "token generation failed. verify ghost_key is in id:secret format." tokens expire after 5 minutes; regenerate before each api call or every 50 posts in batch operations.

step 3: publish a post + send as newsletter (one atomic call)

input: GHOST_URL, TOKEN, post data object with title, html, status: "published", and email_segment: "all"

action: curl post to {GHOST_URL}/ghost/api/admin/posts/?source=html with authorization header Authorization: Ghost {TOKEN} and content-type application/json. body is json array {"posts":[{...}]}. this fires publication and newsletter send in a single call , there is no second step.

output: response json with post id, url, and email status

edge case: if email_segment is missing or added after publish, the newsletter cannot be resent via api , ghost admin resend is the only fallback. the gate prevents this by requiring email_segment in the same call as status: published.

step 4: create a draft (no newsletter)

input: same as step 3 but with status: "draft" instead of published

action: curl post to {GHOST_URL}/ghost/api/admin/posts/?source=html with same headers and body structure

output: response json with post id and draft status

edge case: drafts can be published later via update (step 6) without re-sending newsletters

step 5: upload image

input: GHOST_URL, TOKEN, local file path to image (jpg, png, gif, webp)

action: use python3 with requests library (not curl) to post multipart form-data to {GHOST_URL}/ghost/api/admin/images/upload/. field file is the image file; field purpose is image. this is the only endpoint where python is required , curl multipart fails silently on macos zsh for this endpoint.

output: response json with images array containing url field , use this url as the feature_image value in post objects

edge case: curl multipart fails silently on macos; use python requests exclusively for image upload. file size limit is 10mb per ghost pro specs.

step 6: update an existing post (with conflict safety)

input: GHOST_URL, TOKEN, post id, new post data (html, title, tags, etc.), and updated_at value from the most recent fetch

action: first, curl get to {GHOST_URL}/ghost/api/admin/posts/{id}/ to fetch the current post and capture its updated_at timestamp. then curl put to the same endpoint with the updated post object, including the updated_at value in the body. this prevents 409 conflicts if another write occurred between fetch and update.

output: response json with updated post data

edge case: if put does not include updated_at from a fresh fetch in this same session, ghost returns 409 conflict. the gate requires a fetch before every put. do not skip this step.

step 7: list posts with filtering and field selection

input: GHOST_URL, TOKEN, optional filter string (e.g., status:draft, tag:science), optional field list

action: curl get to {GHOST_URL}/ghost/api/admin/posts/?limit=15&filter={filter}&fields=id,title,slug,status,updated_at with authorization header

output: response json with posts array containing requested fields

edge case: tags in the fields param causes 400 BadRequestError , use &include=tags instead of adding tags to fields. rate limit: default limit is 15; use limit=all for full list but expect slower response.

step 8: schedule a post

input: GHOST_URL, TOKEN, post data with status: "scheduled" and published_at: "2026-03-20T18:00:00.000Z" (utc iso format)

action: curl post to {GHOST_URL}/ghost/api/admin/posts/?source=html with the scheduled post object in the body

output: response json with post id and scheduled status

edge case: time must be in utc iso format. the scheduled post will publish automatically at the specified time.

step 9: batch tag assignment (multi-post)

input: GHOST_URL, TOKEN, tag id, list of post ids to tag

action: for each post, curl get to {GHOST_URL}/ghost/api/admin/posts/{id}/?include=tags to fetch the post and its current tags. extract the existing tag id array. append the new tag id to the array. curl put to {GHOST_URL}/ghost/api/admin/posts/{id}/ with the updated tags array and the updated_at value from the fetch. add 500ms delay between calls to respect rate limits.

output: log of posts tagged with count and any failures

edge case: tag write endpoints (post, put, delete) require owner-level admin api credentials , integration tokens return 403. the tag list endpoint (get) works with standard integration tokens.

step 10: batch import posts (from xml migration)

input: xml file path (wordpress or squarespace export), GHOST_URL, TOKEN

action: parse xml using fast-xml-parser (npm install required for this workflow only). extract post title, content, publish date, tags, and featured image url from each item. for each post, construct a ghost post object with html (cleaned), title, published_at, tags (array of tag objects with name field), and feature_image (url). curl post to {GHOST_URL}/ghost/api/admin/posts/?source=html for each post. add 500ms delay between calls. log success and failure counts.

output: import report with total posts, successful imports, and failed post titles with error codes

edge case: squarespace imports preserve old internal link paths with /blog/ prefix , after import, audit all posts for /blog/ references and batch fix them via step 6 (update). wordpress xml may contain malformed html , use a html sanitizer or manual review before import.

step 11: site audit (metadata completeness scan)

input: GHOST_URL, TOKEN, optional output file path

action: curl get to {GHOST_URL}/ghost/api/admin/posts/?limit=all&include=tags to fetch all published posts. for each post, check for presence of: feature_image, custom_excerpt, meta_description, tags (at least one), and updated_at timestamp older than 30 days. flag posts missing any of these. generate a report with post title, slug, missing fields, and last update date.

output: audit report (json or csv) with flagged posts and missing field counts

edge case: if limit=all times out (large sites with 1000+ posts), use pagination with limit=100 and ?page=1, ?page=2, etc. to avoid timeout.

step 12: email performance report

input: GHOST_URL, TOKEN, time range (e.g., last 30 days)

action: curl get to {GHOST_URL}/ghost/api/admin/posts/?limit=all&include=email to fetch all posts with email send data. filter posts published in the time range. extract open_rate, click_rate, and cto (click to open) for each email. calculate divergence between expected open rate (based on subscriber count at send time) and actual. generate three-section report: email performance summary (avg open, avg ctr, top posts by engagement), web-only post health (posts with no email send, flag for amplification), subscriber tier breakdown.

output: performance report (json or markdown table) with email stats, engagement rankings, and web-only candidates

edge case: email data is only available for posts sent via the email_segment field , drafts and web-only posts have no email metrics.

step 13: batch excerpt writer

input: GHOST_URL, TOKEN, excerpt data mapping (slug or post id to custom excerpt text), optional dry-run flag

action: for each excerpt mapping, curl get to fetch the post by slug or id to get its updated_at. construct the custom_excerpt field (max 300 char hard cap). curl put to update the post with the custom_excerpt and updated_at. add 500ms delay between calls. log success, skip (if excerpt already set), and fail cases.

output: batch report with count of updated, skipped, and failed posts

edge case: custom excerpts drive ghost's content api search results and feed preview text. if a post needs to surface in client-side search, the search keyword must appear in the custom excerpt. 300-char limit is enforced by ghost.

step 14: gsc to ghost indexing repair loop

input: gsc coverage report (downloaded from google search console), GHOST_URL, TOKEN

action: parse gsc report to identify unindexed urls. classify each unindexed url by status (not submitted, crawled but not indexed, indexed but removed). for submitted but not indexed urls, verify the post exists in ghost (curl get by slug). if post exists and is published, check for missing canonical, robots, or noindex meta tags. flag posts for resubmission. for indexed but removed urls, check if post still exists , if so, fix any noindex tags or stale meta descriptions. log resubmission candidates and posts needing meta fixes.

output: gsc repair report with url classification, resubmission list, and meta tag recommendations

edge case: ghost's api does not support redirect writes (post /admin/redirects/ returns 403 for integration tokens) , redirect management is outside this skill's scope. focus on canonical verification and noindex removal only.

step 15: theme upload and activation

input: GHOST_URL, TOKEN, local zip file path of custom theme

action: curl post multipart form-data to {GHOST_URL}/ghost/api/admin/themes/upload/ with file field set to the theme zip. response includes theme name and active status. if activation is needed, curl post to {GHOST_URL}/ghost/api/admin/themes/{name}/activate/ to set it as the active theme.

output: response json with theme name, version, and active status

edge case: theme zip must contain valid hbs template files and package.json. custom theme templates must use triple-brace syntax {{{content}}} , double-braced {{content}} escapes html and renders undefined instead of post body.

step 16: custom html content formatting

input: content in markdown, plaintext, or structured format; desired html output (standard article, literary typography, embeds)

action: convert markdown/plaintext to html using standard tags: <p>, <h2>, <h3>, <hr>, <blockquote>, <ul>, <ol>. for literary typography (fiction, essays), wrap in <div> with georgia serif font, justify alignment, and paragraph indent. for youtube embeds, use <figure class="kg-card kg-embed-card"> wrapper with <iframe> pointing to youtube-nocookie.com. construct the full html object and pass to step 3 or step 6.

output: html string ready for post body

edge case: js is stripped in email delivery , no scripts or interactive elements in html. subscribe widgets are web-only. ghost wraps content in its own email template.

step 17: squarespace/wordpress/substack migration full workflow

input: export file (xml for squarespace/wordpress, csv + html for substack), GHOST_URL, TOKEN, optional mapping config (redirect rules, tag remapping)

action: combine steps 10 (parse and import posts), 5 (upload featured images), and 13 (write custom excerpts). parse the export file for each post. download featured images from external urls and upload via step 5. construct post object with cleaned html, title, tags, published_at, and feature_image url. import via step 10. after all imports complete, audit for /blog/ link prefixes (squarespace only) and batch fix via step 6. generate migration report with total posts, successful imports, image upload success rate, and any manual fixes needed.

output: migration report with post count, image count, tag mapping, and flagged urls needing manual review

edge case: substack html may have inline styles or malformed tags , sanitize before import. squarespace always includes /blog/ in internal link paths , batch find/replace after import. wordpress xml guids may not match ghost slugs , use url slugification rules for consistency.

decision points

if credentials file is missing or malformed

stop execution immediately. output: "credentials file not found at ~/.openclaw/credentials/ghost-admin.json or file is invalid json. create it with url and key fields. example:

{"url": "https://yoursite.ghost.io", "key": "id:secret"}

"

if any api call requires owner-level permissions and token is integration-only

the endpoint returns 403 NoPermissionError. stop and output: "this operation requires owner-level admin api credentials. switch to an owner token in ~/.openclaw/credentials/ghost-admin.json, or manage this feature manually in ghost admin." do not suggest browser fallback.

if about to update (put) any post

check if the current session has already fetched that post and captured its updated_at timestamp. if yes, include updated_at in the put body. if no, fetch the post first (step 7), capture updated_at, then proceed with put. if you skip the fetch, ghost returns 409 conflict and the update fails.

if about to publish a post that should go to subscribers

check if email_segment field is included in the same api call as status: "published". if yes, proceed , newsletter will be sent automatically. if no, do not publish. output: "email_segment field is required in the same api call as status: published. do not publish without it. if you publish first, the newsletter cannot be resent via api , only ghost admin manual resend." wait for user to add email_segment to the request body.

if about to run any bulk operation (batch update, batch tag, batch import)

stop and ask the user to explicitly approve the scope: how many posts, what exact changes will be made. output the scope clearly. wait for explicit yes/no approval before proceeding. bulk writes are irreversible without manual rollback in ghost admin.

if image upload is failing with curl

image uploads always fail silently on macos zsh when using curl multipart. switch to python3 requests library (step 5). curl works fine for all other api calls (posts, tags, analytics) , this exception applies to image upload only.

if a batch operation hits rate limit (429 response)

ghost pro allows 2,000 requests per 5 minutes per integration key. add 500ms delay between calls. if rate limit is hit mid-batch, wait 5 minutes and resume from the last successful post.

if token expires during a long batch operation

jwt tokens expire 5 minutes after generation. regenerate token before each api call, or every 50 posts in batch operations. if you get a 401 unauthorized response, regenerate the token and retry.

if post has no feature_image or custom_excerpt

site audit (step 11) will flag it. if it's a high-priority post, update via step 6 to add these fields , they improve seo and email/feed preview appearance.

if squarespace import is complete but posts contain /blog/ prefixes in internal links

this is expected behavior from squarespace exports. batch find/replace all /blog/ urls in post html using step 6 (update). example: find /blog/post-title, replace with /post-title.

if gsc report shows unindexed urls

step 14 will classify them. if status is "submitted but not indexed", verify the post exists in ghost and has a canonical tag. if the post is deleted or unpublished, google will naturally remove it from the index over time. if the post is live and published, check robots/noindex tags and resubmit to google search console.

if theme upload fails with 403

integration tokens cannot manage themes. switch to an owner token in credentials file and retry.

output contract

publish + newsletter (step 3)

• format: json response body with keys: posts (array with single post object), post.id, post.url, post.email_sent_at (timestamp if email was sent, null if draft)
• file location: none; response is immediate
• success criteria: status code 201, email_sent_at is not null, post.status is "published"

draft create (step 4)

• format: json response body with keys: posts (array), post.status = "draft"
• success criteria: status code 201, post is not live (url does not resolve until published)

image upload (step 5)

• format: json response body with keys: images (array with single image object), image.url (full cdn url)
• success criteria: status code 201, url is a valid https cdn path (example: https://yoursite.ghost.io/content/images/2026/03/filename.jpg)
• file location: image is now hosted on ghost cdn; use the url as feature_image value

update post (step 6)

• format: json response body with keys: posts (array), post.updated_at (new timestamp)
• success criteria: status code 200, updated_at timestamp is newer than the fetched value
• file location: none; changes are live immediately (or queued if scheduled)

list posts (step 7)

• format: json response body with keys: posts (array of post objects with requested fields), meta (object with pagination)
• success criteria: status code 200, posts array contains at least one entry (or empty array if no matches)

schedule post (step 8)

• format: json response body with keys: posts (array), post.status = "scheduled", post.published_at (iso timestamp)
• success criteria: status code 201, published_at is in the future, post is not live yet

batch tag assignment (step 9)

• format: log output or json report with keys: tagged (count), failed (count), failed_posts (array of post titles and error messages)
• success criteria: all posts in the input list have the tag id in their tags array
• edge case: if any post fails with 403, that's owner-level token required , log and continue

batch import (step 10)

• format: json or markdown report with keys: total_posts (count), successful (count), failed (count), failed_posts (array of original titles and error codes)
• success criteria: all posts created with status "published" (or "draft" if configured), urls are live and indexable
• file location: report file saved to optional output path (default: stdout)

site audit (step 11)

• format: json or csv with keys per post: title, slug, missing_fields (array), last_updated_date, feature_image (true/false), custom_excerpt (true/false), meta_description (true/false), tags (count), stale (true if updated_at > 30 days ago)
• success criteria: all published posts are scanned, flagged posts are identified with specific missing fields
• file location: saved to optional output file path (default: stdout)

email performance (step 12)

• format: markdown table or json with keys: email_count, avg_open_rate, avg_ctr, top_posts (array with title, open_rate, ctr), web_only_count, subscriber_tiers (breakdown by paid/free)
• success criteria: all posts with email sends in time range are included, metrics are calculated, divergence is identified
• file location: optional output file path

batch excerpt write (step 13)

• format: json report with keys: updated (count), skipped (count), failed (count), failed_posts (array with slug and error)
• success criteria: all target posts have custom_excerpt set (max 300 chars), char count is logged per post
• file location: optional output file path

gsc repair (step 14)

• format: markdown table or json with keys: unindexed_urls (count), classification (not_submitted, crawled, indexed_removed), resubmit_candidates (array with url and reason), meta_fixes (array with post slug and missing tags)
• success criteria: all unindexed urls are classified, resubmit candidates are flagged with canonical/robots status
• file location: optional output file path

theme upload (step 15)

• format: json response body with keys: themes (array), theme.name, theme.active (boolean)
• success criteria: status code 201, theme.name is populated, theme can be activated with a follow-up call

migration full (step 17)

• format: json report with keys: posts_imported (count), images_uploaded (count), image_failures (count), excerpts_written (count), /blog/ links_found(count),manual_review_needed` (array)
• success criteria: all posts from export are created, featured images are live on ghost cdn, /blog/ prefixes are identified for batch fix, report is logged
• file location: report file saved to optional output path

outcome signal

user knows the skill worked when:

1. publish + newsletter: post appears on the live site within 10 seconds, email arrives in subscriber inboxes within 30 seconds, email send timestamp is visible in ghost admin posts view

2. draft create: post appears in ghost admin drafts list, url does not resolve (404) until status is changed to published

3. image upload: feature image loads on the live post page, url in the response is a valid ghost cdn path, image is no longer referenced by local file path

4. update post: change is live on the site within 5 seconds, updated_at timestamp in ghost admin is newer than before, no 409 conflict error

5. list posts: output includes all posts matching the filter, field count matches request, pagination cursor moves correctly on subsequent calls

6. schedule post: post appears in ghost admin scheduled queue with future publish date, post does not go live before scheduled time, auto-publishes at exact scheduled time

7. batch tag assignment: all target posts show the tag in ghost admin post editor, tag count in posts list is incremented, bulk tag report shows 0 failed count

8. batch import: all posts appear in ghost admin with correct titles and publish dates, urls are indexable (no robots: noindex), featured images load, internal links point to correct ghost urls

9. **