WordPress Blog Publisher

intent

use this skill to publish, update, or batch-upload blog posts to a wordpress site via the rest api (/wp-json/wp/v2/*). handles application password auth, markdown-to-html conversion, media uploads to the wp library, post scheduling across a calendar, and status writeback to upstream systems (airtable, bitable, google sheets). designed for workflows where 20-200 seo articles need to go live on a schedule without manual copy-paste per post.

inputs

wordpress site credentials (required):

• site_url: base domain, no trailing slash (e.g., https://example.com)
• username: wp admin username
• app_password: application password from wp admin > users > [your profile] > application passwords section. never use login password.

content inputs (required):

• markdown file or structured data row with fields: title, slug, content (markdown), categories (comma-separated names or array of ids), tags (comma-separated names or array of ids), optional featured_image_url or featured_image_file

upstream system connection (optional but recommended):

• airtable: base id, table name, api key (env var AIRTABLE_API_KEY), and field names for permalink, wp_status, wp_post_id
• google sheets: sheet id, range, service account json (env var GOOGLE_SHEETS_CREDENTIALS), columns for permalink and publish timestamp
• bitable: app token (env var LARK_APP_TOKEN), table id, record id field
• local file: csv or jsonl log file path for writeback

external connections (optional):

• markdown-to-html converter library (e.g., commonmark, markdown-it) for proper conversion (not regex)
• wordpress media library already configured with upload directory writable

procedure

step 1: authenticate and validate credentials

1. build http basic auth header: authorization: basic [base64(username:app_password)]
2. send get {site_url}/wp-json/wp/v2/users/me with auth header
3. if response status 200, auth is valid and user has api access
4. if status 401, application password is incorrect or not configured
5. if status 403, user lacks publish_posts capability in wp admin
6. store auth header for all subsequent requests in this batch

inputs: site_url, username, app_password outputs: valid auth header, user object with capabilities confirmed

step 2: prepare and convert content

1. read source file or data row
2. extract yaml front-matter if present; retain title, slug, categories, tags, publish_date (optional), featured_image_url (optional)
3. strip the h1 heading (# Title) from markdown body (this becomes post title, not body content)
4. convert markdown to html using a standards-compliant converter (commonmark, markdown-it, or similar; not regex substitution)
5. preserve markdown features in conversion: code fences as <pre><code>, tables as <table>, nested lists as nested <ul>/<ol>, blockquotes as <blockquote>
6. scan html for inline image tags (<img src="...">) and note all image urls for later upload

inputs: markdown content with optional front-matter outputs: post title (string), post slug (string), post content (valid html), list of image urls, metadata dict with categories, tags, publish_date

step 3: resolve category and tag numeric ids

1. for each category name in the content metadata:
   • send get {site_url}/wp-json/wp/v2/categories?search={category_name}&per_page=5 with auth header
   • parse response and extract numeric id field from matching category
   • cache this id in a local map (key: category name, value: id) for the duration of the batch
2. if category not found, log warning and skip category for this post
3. repeat for each tag name in the same manner using /wp-json/wp/v2/tags endpoint
4. return array of numeric category ids and array of numeric tag ids

inputs: category names list, tag names list, site_url, auth header outputs: dict mapping {category_name: id}, dict mapping {tag_name: id}

step 4: upload featured image and inline images to wp media library

1. if featured_image_url or featured_image_file exists in metadata:
   • download image file (if url) or read local file
   • check file size; if > 2mb, resize/compress before upload
   • extract filename from url or file path
   • send post {site_url}/wp-json/wp/v2/media with headers: content-disposition: attachment; filename="{filename}", content-type: image/jpeg (or appropriate type), body as binary image data, auth header
   • parse response for media id and media source url
   • store featured_media_id for post creation step
2. for each inline image url found in step 2:
   • download image file
   • check file size; if > 2mb, resize/compress
   • extract filename
   • send post {site_url}/wp-json/wp/v2/media with same headers and auth
   • parse response for media id and media source url
   • replace inline image src in html content from original url to wp media library url

inputs: featured_image url or file, list of inline image urls, post content html, site_url, auth header outputs: featured_media_id (numeric), updated post content html with rewritten image src attributes

step 5: create or update post in wordpress

1. determine whether this is a new post or update to existing post:
   • if slug not provided or first time seeing slug in batch, assume new post
   • if slug already published or wp_post_id known, lookup existing post: get {site_url}/wp-json/wp/v2/posts?slug={slug}&status=any with auth header; extract post id from response
2. construct post payload (json object) with required fields:
   • title: post title (string)
   • content: post content (valid html from step 2)
   • slug: post slug (string)
   • status: "publish" for immediate publish, "future" for scheduled, or "draft" for review
   • categories: array of numeric category ids from step 3
   • tags: array of numeric tag ids from step 3
   • featured_media: numeric media id from step 4 (if featured image exists)
   • date_gmt: utc datetime string for publication (e.g., "2025-06-15T09:00:00"); use this field, never date (local timezone)
3. if new post: send post {site_url}/wp-json/wp/v2/posts with json payload and auth header
4. if updating existing post: send post {site_url}/wp-json/wp/v2/posts/{post_id} with json payload and auth header
5. parse response: extract id (post id), link (permalink), date_gmt (published datetime)
6. if status >= 400, log error with post title and response body; do not proceed to writeback

inputs: post title, slug, html content, category ids, tag ids, featured media id, publish status, publish datetime (utc), wp_post_id (if update), site_url, auth header outputs: wp_post_id (numeric), permalink (url string), published_datetime (utc string)

step 6: write status and permalink back to upstream system

1. if upstream system is airtable:
   • send patch https://api.airtable.com/v0/{base_id}/{table_name}/{record_id} with auth authorization: bearer {airtable_api_key} and json payload: {"fields": {"permalink": "{permalink}", "wp_status": "published", "wp_post_id": {wp_post_id}, "published_at": "{published_datetime}"}}
   • parse response; if status 200, record updated successfully
2. if upstream system is google sheets:
   • use google sheets api v4 with service account credentials
   • send put https://sheets.googleapis.com/v4/spreadsheets/{sheet_id}/values/{range}!A1 with values array containing permalink, post id, status, timestamp
   • parse response; if status 200, cells updated
3. if upstream system is bitable (lark):
   • send patch https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/{record_id} with auth authorization: bearer {access_token} and json payload with field updates
   • parse response; if status 0, record updated
4. if upstream is local file:
   • append json line {"slug": "{slug}", "wp_post_id": {wp_post_id}, "permalink": "{permalink}", "published_at": "{published_datetime}"} to jsonl log file, or csv row to csv log file
   • if file does not exist, create it first with headers

inputs: wp_post_id, permalink, published_datetime, upstream_system_type, upstream credentials (airtable key, google sheets credentials, bitable token, or log file path) outputs: writeback success status (true/false), upstream record id or row updated count

step 7: batch mode protocol (for 2+ posts)

1. before processing batch:
   • send dry-run: process first post fully through step 5 (create post as draft), show user the draft post url and content preview
   • wait for user confirmation to proceed with remaining posts
2. on confirmation:
   • process remaining posts (step 2-6) sequentially
   • insert 1-2 second delay between requests to avoid rate-limit errors
   • after each post: print status line to stdout: [{current}/{total}] published: {slug} {permalink} ✓ or [{current}/{total}] failed: {slug} , {error_reason}
3. on any post failure:
   • log full error response (status code, body) to error log file or stderr
   • continue to next post (do not halt batch)
4. after batch completes:
   • print summary: {count_published} published, {count_failed} failed, {count_skipped} skipped. see log: {log_file_path}
   • if any failures, display log file excerpt with error details

inputs: list of posts (2+), dry_run_mode (true for batch), user_confirmation, upstream_system_type outputs: batch summary dict with counts, completion status, log file path

decision points

if user provides markdown content then convert to html using step 2 procedure. else if user provides raw html then skip conversion; validate html is well-formed before posting. else reject input and ask for markdown or html.

if featured image url provided then download and upload to wp media library via step 4. else if featured_image_file path provided then read local file and upload via step 4. else proceed without featured image (featured_media field omitted from post payload).

if category or tag name does not exist in wordpress then log warning "{category_name} not found, skipping for this post". continue post creation without that category or tag.

if image file size > 2mb then compress/resize image before upload. else upload as-is.

if api response status is 401 (unauthorized) then stop batch immediately. log "auth failed: check application password and site url". do not attempt retry.

if api response status is 429 (rate limit) then pause for 60 seconds. retry the request once. if retry fails, log error and continue to next post.

if post status is "future" (scheduled) and publish datetime is in the past then change status to "publish" and post immediately. log warning "scheduled date is past, publishing immediately".

if batch mode is enabled (2+ posts) and no user confirmation after dry-run then abort batch. delete draft post created in dry-run (optional). log "batch cancelled by user".

if upstream writeback fails (e.g., airtable api error) then log error with response status and body. continue to next post. do not halt batch.

if post update (not create) and post id lookup returns 0 results then treat as new post and create instead. log "post slug not found; creating as new post".

output contract

on successful post creation:

• http response status: 201
• response body contains: id (numeric), link (permalink string), date_gmt (utc datetime string), slug (string)
• example: {"id": 1234, "slug": "seo-guide-2025", "link": "https://example.com/seo-guide-2025/", "date_gmt": "2025-06-15T09:00:00"}

on successful post update:

• http response status: 200
• response body contains: id (numeric), link (permalink string), modified_gmt (utc datetime string)

on successful writeback to upstream:

• airtable: status 200, response contains updated record id
• google sheets: status 200, response contains updated range and values count
• bitable: status 0 in response json, record_id in response
• local file: json/csv line appended; file size increased

batch completion log file:

• location: {working_dir}/wp-publish-log-{timestamp}.jsonl or .csv
• format (jsonl): one object per line with keys slug, wp_post_id, permalink, published_at, status (success/failed), error_message (if failed)
• format (csv): headers slug,wp_post_id,permalink,published_at,status,error_message
• example line: {"slug":"seo-guide-2025","wp_post_id":1234,"permalink":"https://example.com/seo-guide-2025/","published_at":"2025-06-15T09:00:00","status":"success"}

error log file:

• location: {working_dir}/wp-publish-errors-{timestamp}.log
• format: one error per line with timestamp, post slug, http status, response body
• example: 2025-06-15T09:00:15Z | seo-guide-2025 | 400 | {"code":"rest_invalid_param","message":"Invalid parameter(s): categories"}

outcome signal

user knows the skill worked when:

1. post is live or scheduled: permalink is accessible at expected url (e.g., https://example.com/seo-guide-2025/) and post content appears with correct title, html-converted body, featured image, categories, and tags. if status is "future", post is not yet visible but appears in wp admin with scheduled datetime.

2. images are in wp library: featured image and all inline images are uploaded to wp media library (wp admin > media library lists them) and src attributes in post body point to wp media urls (not external urls or local paths).

3. upstream record is updated: airtable/sheets/bitable record or log file contains permalink, wp post id, and publish timestamp. user can click permalink in upstream system and land on live post.

4. batch summary is printed: for batches, stdout shows final count: "{N} published, {M} failed". user can open log file and see each post's status and any error details.

5. no silent failures: every post attempt is logged (success or failure); user never publishes without knowing whether each post succeeded.

6. dry-run works: first post in batch is created as draft with correct title, content, and formatting. user sees draft url in output and can review before confirming batch.

credits: original skill by leooooooow (clawhub).