WordPress Blog Publisher

This skill turns an AI agent into a reliable publisher for WordPress sites via the REST API (/wp-json/wp/v2/*). Designed for batch SEO content workflows, it handles authentication, markdown-to-HTML conversion, media uploads, post scheduling, and status writeback to upstream systems like Airtable, Bitable, or Google Sheets.

Quick Reference

| Decision | Strong Choice | Acceptable | Weak / Avoid | |----------|---------------|------------||--------------| | Auth method | Application Password (HTTP Basic) | JWT token | Login password (never) | | Content format | Markdown → HTML (convert first) | Raw HTML | Raw markdown (WP won't render it) | | Batch approach | Dry-run first post, confirm, then batch | Process all with logs | Process all without validation | | Image handling | Upload to WP media library, rewrite src | External CDN links | Local file paths | | Post status | publish or future (scheduled) | draft for review | private (unless intentional) | | Error handling | Log and continue on non-critical errors | Stop on all errors | Silent fail | | Permalink writeback | Write to upstream system after publish | Log to file | No writeback |

Problems This Skill Solves

1. Manual copy-paste publishing bottleneck — writing and publishing blog posts one-by-one when a batch of 20–200 SEO articles needs to go live.
2. Markdown format mismatch — AI-generated content is usually markdown, but WP's classic editor expects HTML and the block editor has its own format requirements.
3. Image scatter — inline images in markdown that point to external URLs or local paths need to be uploaded to the WP media library and src-rewritten.
4. No upstream status tracking — after publishing, many workflows lose track of which posts are live vs. draft vs. scheduled.
5. Auth confusion — using login passwords (wrong) vs. Application Passwords (correct) is the #1 cause of 401 errors.
6. Category/tag ID mismatch — WP uses numeric IDs for categories and tags, not names; this skill handles the lookup.
7. Scheduling complexity — batch content often needs to be spread across a publication calendar rather than published all at once.

Workflow

Step 1 — Authenticate

Required credentials:

• site_url: e.g., https://example.com (no trailing slash)
• username: WP admin username
• app_password: Application Password from WP Admin → Users → Profile → Application Passwords

Auth header:

Authorization: Basic base64(username:app_password)

Test connection:

GET {site_url}/wp-json/wp/v2/users/me

If 200, auth is working. If 401, check Application Password setup. If 403, user lacks publish_posts capability.

Step 2 — Prepare Content

• Strip YAML front-matter; use title, slug, categories, tags fields from it
• Convert markdown to HTML using a proper converter (not regex substitution)
• Preserve: code fences (<pre><code>), tables, nested lists
• Remove: # H1 title (use as post title, not body content)

Step 3 — Resolve Category and Tag IDs

WP requires numeric IDs, not names:

GET {site_url}/wp-json/wp/v2/categories?search=seo&per_page=5

Cache the ID map for the batch to avoid repeated lookups.

Step 4 — Upload Media (Featured Image)

POST {site_url}/wp-json/wp/v2/media
Headers:
  Content-Disposition: attachment; filename="image.jpg"
  Content-Type: image/jpeg
Body: [binary image data]

Step 5 — Create or Update Post

POST {site_url}/wp-json/wp/v2/posts
{
  "title": "Your Post Title",
  "content": "<p>HTML content here</p>",
  "slug": "your-post-slug",
  "status": "publish",
  "categories": [12, 34],
  "tags": [56, 78],
  "featured_media": 1234,
  "date_gmt": "2025-06-15T09:00:00"
}

Response includes "link" — the live permalink. Save this.

Step 6 — Write Status Back to Upstream System

After each successful publish, write permalink and timestamp back:

• Airtable: PATCH record with permalink and wp_status fields
• Google Sheets: Update row via Sheets API
• Bitable: Update record via Lark Open API
• Local log: Append {slug, wp_post_id, permalink, published_at} to CSV/JSON

Step 7 — Batch Mode Protocol

1. Process first post fully, show draft URL
2. Wait for confirmation
3. Process remaining with 1–2 second delay between requests
4. Show running status: [3/20] Published: /seo-guide-2025 ✓
5. On failure: log error, continue with next post
6. Final summary: 20 published, 1 failed (see log)

Worked Examples

Example 1 — Batch Publish 10 SEO Articles from Airtable

1. Fetch rows where Status = "Ready to Publish" from Airtable
2. For each row: convert markdown → HTML, upload featured image, resolve category ID
3. Create WP post with status: "future" and date_gmt staggered by 1 day each
4. Write permalink + WP post ID back to Airtable

Example 2 — Update Existing Posts with New Content

1. For each slug: GET /wp-json/wp/v2/posts?slug={slug}&status=any to find post ID
2. Convert updated markdown to HTML
3. POST /wp-json/wp/v2/posts/{id} with updated content

Common Mistakes

1. Using login password — results in 401; use Application Password.
2. Posting raw markdown — always convert to HTML first.
3. Wrong category IDs — always look up IDs via the API.
4. Images > 2MB — resize before uploading.
5. Using date instead of date_gmt — always use UTC.
6. No dry-run on batches — validate one post before running 50.
7. Not writing permalink back — without writeback, you lose track of published posts.
8. Silent failures in batch — always log errors explicitly.

Resources

• references/api-reference.md — WP REST API endpoints quick reference
• references/markdown-to-html-rules.md — Conversion rules and edge cases
• assets/wp-publish-checklist.md — Pre-publish and post-publish quality checklist