# Wpcom Remote Management

> Manage a remote WordPress.com site with wpcom_request, including API namespace selection, endpoint discovery, content/template/theme/plugin operations, response-size limits, and visual verification.

- Skill: `automattic/wpcom-remote-management` (Agent Skill)
- Install (CLI): `npx skillmds@latest add automattic/wpcom-remote-management`
- Raw SKILL.md: https://api.skillmd.com/api/skills/automattic/wpcom-remote-management/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: Automattic (https://skillmd.com/u/automattic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/automattic/wpcom-remote-management

---


# WordPress.com Remote Management

Use this skill after the mandatory remote-site plan check, before selecting endpoints or making changes to a WordPress.com site through `wpcom_request`.

## Tool Shape

`wpcom_request` supports both the WordPress REST API and WordPress.com REST API endpoints:

- `method`: `GET`, `POST`, `PUT`, or `DELETE`
- `path`: relative to `/sites/{siteId}/`, such as `/posts`, `/posts/123`, or `/templates`
- `query`: optional query parameters object
- `body`: optional request body for `POST` and `PUT`
- `bodyFile`: optional staged JSON file path for `POST` and `PUT`; the parsed JSON object becomes the entire request body
- `bodyFiles`: optional map of top-level request body field names to staged file paths for `POST` and `PUT`; each file becomes that field's string value
- `apiNamespace`: defaults to `"wp/v2"`; set to `""` for WordPress.com REST API v1.1, or `"wpcom/v2"` for WordPress.com v2 endpoints

Prefix `path` with `!` only for absolute paths such as `!/me`.

## Namespace Selection

Prefer `wp/v2` for standard WordPress resources:

- Posts, pages, media, categories, tags, users, comments
- Templates, template parts, navigation, global styles, block patterns
- Block types and search

Use WordPress.com v1.1 by setting `apiNamespace: ""` for WordPress.com-specific resources:

- Site info: `GET /`
- Site settings: `POST /settings`
- Plugin management: `GET /plugins`, `POST /plugins/{slug}/install`, `POST /plugins/{slug}` with body `{ active: true }` or `{ active: false }`
- Theme switching: `GET /themes`, `POST /themes/mine` with body `{ theme: "slug" }`
- Media upload from URL: `POST /media/new` with body `{ media_urls: [...] }`

## Common wp/v2 Endpoints

- Posts and pages: `GET /posts`, `GET /posts/{id}`, `POST /posts`, `POST /posts/{id}`, `DELETE /posts/{id}`
- Media: `GET /media`, `POST /media`
- Templates: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `POST /templates/{id}`, `DELETE /templates/{id}`
- Template parts: `GET /template-parts`, `GET /template-parts/{id}`, `POST /template-parts`, `POST /template-parts/{id}`
- Navigation: `GET /navigation`, `POST /navigation`, `POST /navigation/{id}`
- Global styles: `GET /global-styles/{id}`, `POST /global-styles/{id}`
- Categories and tags: `GET /categories`, `POST /categories`, `GET /tags`, `POST /tags`
- Block types: `GET /block-types`, `GET /block-types/{name}`
- Search: `GET /search?search={query}`

To find the global styles ID, first call `GET /themes?status=active`; the active theme's `_links["wp:user-global-styles"][0].href` contains the ID.

Use `per_page` and `page` for pagination. Use `status` to filter by publish status. For creating or updating content, pass block markup in the `content` field of the request body.

## Response Size Control

Minimize response sizes to avoid exceeding tool output limits:

- Use `_fields` for `wp/v2`.
- Use `fields` for WordPress.com v1.1.
- Exclude heavy fields such as `content` when listing resources.
- Fetch lightweight listings first, then fetch individual resources by ID when full content is needed.
- When using `fields` with v1.1, always include `ID`.

Examples:

```text
GET /posts?_fields=id,slug,title,status
GET /plugins?fields=ID,name,description,URL
```

## Large Request Bodies

For generated page content, template content, template-part content, global styles, or CSS, do not inline large generated strings in `wpcom_request.body`.

Stage request payload files under `tmp/ai-payloads/` within Studio app data using small `Write` or `Edit` steps.

Use `bodyFiles` when staged files should become string fields inside the request body:

```text
body: { "status": "publish" }
bodyFiles: { "content": "tmp/ai-payloads/home.html" }
```

The `bodyFiles` keys must be top-level REST body field names such as `content`, `excerpt`, or `css`, not filenames or nested paths. Do not use keys like `home.html`, `styles.css`, `content.raw`, or `styles.color.background`.

Use `bodyFile` when the staged file is the complete JSON request body, especially for endpoints that expect nested JSON objects such as `POST /global-styles/{id}`:

```text
bodyFile: "tmp/ai-payloads/global-styles.json"
```

Do not combine `bodyFile` with `body` or `bodyFiles`.

## Workflow

1. Check the site plan first. This is already required by the remote system prompt and must happen before any change.
2. Understand the site with lightweight reads, such as `GET /posts` and `GET /themes?status=active`.
3. Make changes with POST requests to create or update content, manage templates, switch themes, or manage plugins.
4. Verify with `take_screenshot` using `viewport: "all"` for desktop and mobile; when you cannot view images, verify from the rendered DOM with `inspect_design` instead.
5. If an operation fails, inspect the error and try a lightweight GET request to discover the available shape before retrying.

Always confirm destructive operations, including deleting posts or deactivating plugins, before proceeding.