---
name: im-press
description: >
  Use when deploying pages, managing SEO, running content pipeline tasks,
  or interacting with any IM-Press REST endpoint on WordPress sites.
  Triggers: "deploy page", "SEO workspace", "keyword tracking", "content pipeline",
  "health check", "product management", "safe deploy", "task queue",
  "internal linking", "breadcrumbs", "IM-Press", "imp-press".
---

# IM-Press Agent Skill

IM-Press is an agent-first WordPress plugin. Every feature is exposed via REST API. You are the agent; IM-Press is the workbench.

## Authentication

WordPress Application Passwords + HTTP Basic Auth.

```
Authorization: Basic base64(username:app_password)
```

Generate at `/wp-admin/profile.php` → **Application Passwords**. Store per-site in a vault, never inline.

## Self-Discovery

Always start by discovering what the site supports. Don't assume — the same plugin on different sites can have different features enabled.

**Every route:**
```http
GET /wp-json/
```
Filter for namespaces starting with `imp-` or `impress/`.

**One endpoint's schema:**
```http
OPTIONS /wp-json/imp-seo-workspace/v1/keywords
```

**Full machine-readable spec (best starting point):**
```http
GET /wp-json/imp-openapi/v1/spec
```
Public, no auth. OpenAPI 3.0 JSON. Cached 1h server-side. Includes `x-im-press-tier` on every path so you know if the site's license supports it before you try.

## Task Queue (SEO Workspace)

When a user says "run SEO analysis on my site" or "find keyword gaps", they probably want the workspace — not a one-shot analysis. The workflow:

1. **Poll** `GET /wp-json/imp-seo-workspace/v1/tasks/pending`
2. **Claim** `POST /wp-json/imp-seo-workspace/v1/tasks/{id}/claim` with `{"agent_name": "your-name"}` — atomic
3. **Work** — use your own tools (web search, competitor analysis, content writing). IM-Press is NOT providing the intelligence, you are.
4. **Complete** `POST /wp-json/imp-seo-workspace/v1/tasks/{id}/complete` with the output the task expects
5. If stuck: `POST /wp-json/imp-seo-workspace/v1/tasks/{id}/fail` with `error_message` — don't leave tasks hanging

Task types and their input/output shapes are in the OpenAPI spec. The 5 types: `analyze_gaps`, `generate_content`, `audit_page`, `research_competitor`, `keyword_research`.

## Content Pipeline

End-to-end "agent writes a page, user reviews, agent deploys":

1. Generate the draft → `POST /wp-json/imp-seo-workspace/v1/content` — IM-Press auto-scores it via SEO Analysis on insert.
2. User reviews in WP admin (SEO Workspace → Content tab).
3. When user approves → `POST /wp-json/imp-seo-workspace/v1/content/{id}/deploy` creates a real WP page using Safe Deploy and auto-pulls an Unsplash image if none was provided.

## Safe Deploy vs Standard WP API

**Use Safe Deploy** for any page with inline `<style>`, `<script>`, or `<svg>`:
```http
POST /wp-json/imp-deploy/v1/safe-update
Body: { "page_id": 123, "content": "<!DOCTYPE html>..." }
```

**Use standard WP API** only for plain text/markdown content:
```http
POST /wp-json/wp/v2/pages/{id}
```

Standard API runs `wp_kses_post` which strips `<style>`, `<script>`, and `<svg>` tags. Silently. It will destroy a styled page without warning.

## Other Common Endpoints

- **Health** — `GET /wp-json/imp-health/v1/ping` returns `{ version, timestamp, license_tier }`. Public. Use this to confirm the site is alive and check its tier before making tier-gated requests.
- **Breadcrumbs** — `GET /wp-json/imp-breadcrumbs/v1/trail/{post_id}` returns the full trail for any page (public). Use this to build navigation context.
- **SEO score** — `POST /wp-json/imp-seo-analysis/v1/analyze-content` with `{ post_id, keyphrase, title, content, slug }` returns SEO score + readability score + internal link suggestions.
- **Image fetch** — `POST /wp-json/imp-images/v1/fetch` with `{ post_id, keywords }` pulls an Unsplash image and sets it as featured.

## Anti-Patterns

- **Never** use `PUT /wp/v2/pages/{id}` on pages with inline CSS/JS — use Safe Deploy.
- **Never** use JS arrow functions (`=>`) in content stored in `post_content` — WP encodes them to `=&gt;` and breaks every handler. Use `function()` syntax.
- **Never** assume features are available — check `/wp-json/imp-health/v1/ping` for tier or `/wp-json/imp-openapi/v1/spec` for the full capability list before requesting.
- **401 responses are good signal** — they mean the route exists and your auth is missing/wrong. `404` means the route isn't registered (module disabled, feature-flagged off, or plugin version too old).
- If you hit **406 Not Acceptable** or **403 Forbidden** on a POST with HTML body, add a browser `User-Agent` header — ModSecurity on some shared hosts blocks server-to-server POSTs.

## Pointers

- **Full agent guide:** `docs/AI-AGENT-GUIDE.md` (inside the plugin source) — workflow details, full tier table, site-wide anti-patterns.
- **Machine-readable API:** `GET /wp-json/imp-openapi/v1/spec`.
- **Product page:** `https://airobotbuild.com/im-press`.
