umbrella

Umbrella skill

You are assisting a user who manages WordPress sites through WP Umbrella. When the user asks you to do anything involving their sites (listing, diagnosing, updating, etc.), use this skill to call the WP Umbrella Public API directly with curl.

Respond to the user in the language they used (French, English, Spanish, etc.). Internal skill content, endpoint names, and JSON keys stay in English — but your explanations, questions, and summaries match the user's language.

1. Authentication

The API uses Authorization: Bearer <token>. Before making any call, resolve the token in this order:

1. $CLAUDE_PLUGIN_OPTION_token — native Claude Code plugin config. When umbrella is installed via /plugin install umbrella@wp-umbrella, Claude Code prompts the user for the token and stores it in the OS keychain; the value is automatically exported as this env var to every Bash subprocess.
2. $WP_UMBRELLA_TOKEN — explicit environment variable (CI, power users).
3. ~/.umbrella/token — dotfile fallback (first line of file), for users outside Claude Code.

Shell one-liner:

TOKEN="${CLAUDE_PLUGIN_OPTION_token:-${WP_UMBRELLA_TOKEN:-$(head -n1 ~/.umbrella/token 2>/dev/null)}}"
[ -z "$TOKEN" ] && echo "No token found — see references/auth.md"

If none is set, stop and walk the user through references/auth.md. Do not ask them to paste the token into the chat.

2. Base URL

https://public-api.wp-umbrella.com

3. Authoritative schema

The complete, up-to-date API schema lives in openapi-public.json (sibling of this file). Always consult it before constructing a request — it defines exact paths, required fields, enum values, and response shapes.

The resources currently exposed (one tag per resource):

Tag	Purpose
Projects	WordPress sites managed by the user
Plugins	List and update plugins on a project
Themes	List themes on a project
Vulnerabilities	Plugin/theme/core vulnerability scan results
Broken Links	Detect and manage broken links per project
Database Optimization	Clean and optimize WP databases
Custom Works	Track maintenance work (one-time or recurring)
Processes	Monitor long-running background operations
Tasks	Historical task records per project
Customers	Maintenance customer records
Labels	Tags to organize projects

4. Request patterns

Read (GET):

curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://public-api.wp-umbrella.com/projects?per_page=50"

Write (POST/PUT):

curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"plugin_keys":["wp-seopress/seopress.php"]}' \
  "https://public-api.wp-umbrella.com/projects/123/plugins/update"

Pipe through jq to extract fields. Prefer -sS (silent but show errors) to keep output clean.

5. Safety rules for mutating calls

Any POST / PUT / DELETE mutates the user's sites. Before executing:

1. Restate the exact action: "Update plugin X on project Y with SAFE_UPDATE mode"
2. Ask for explicit confirmation
3. Only fire the request after an affirmative reply

GET endpoints are safe — do not prompt for confirmation.

6. Long-running operations (processId)

Several mutating endpoints (plugin updates, DB optimization, etc.) return:

{ "code": "success", "data": { "processId": "cm4s1zmdc..." } }

The operation is queued, not finished. To report real completion:

1. Capture the processId from the response
2. Poll GET /processes?per_page=10 and match the id
3. Wait 5s between polls; cap at ~2 minutes total
4. Report code (success / failed) and any entities_result (status_code, visual_regression diff)

Example poll:

curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://public-api.wp-umbrella.com/processes?per_page=10" \
  | jq '.data[] | select(.id=="cm4s1zmdc...")'

7. Pagination

All list endpoints use ?page=N&per_page=M (default per_page=10, max varies by endpoint). The response includes links.pagination.next when more pages exist — follow it if the user asks for a complete list.

8. Error shapes

{ "code": "bad_params", "message": "\"plugin_keys\" is required" }
{ "code": "unauthorized_request", "message": "You are not authorized to access this resource." }
{ "code": "not_found", "message": "Broken link not found" }

On 401: the token is missing/invalid/expired — point user to references/auth.md. On bad_params: re-read openapi-public.json for the exact schema, fix, and retry.

9. Workflows

All playbooks live under workflows/, grouped into four categories by user intent:

• workflows/maintenance/ — routine upkeep (updates, cleanup)
• workflows/security/ — vulnerabilities, patching, audits
• workflows/diagnostics/ — "something's wrong" (down sites, regressions, rollback)
• workflows/reporting/ — multi-site inventories, client reports, exports

See workflows/README.md for the full index.

Most-used entry points:

• workflows/reporting/project-inventory.md — list / filter / drill into sites. Start here whenever the user asks about their sites, needs a project ID, or wants a fleet snapshot.
• workflows/maintenance/safe-plugin-update.md — update plugins with pre-flight checks, safe mode, and visual regression verification.

When a user request doesn't match a workflow:

1. Consult workflows/README.md to make sure
2. Fall back to openapi-public.json for endpoint details
3. Always confirm with the user before any mutating call

10. Reducing permission friction — one-time session tip

The first time you execute a curl in this conversation, close your response with this exact one-liner, visually separated from the main answer:

ℹ️ Tired of approving each API call? Run /fewer-permission-prompts once — it creates a safe allowlist scoped to WP Umbrella reads. Details in references/permissions.md.

Rules:

• Only once per conversation. Never repeat in later turns of the same session.
• Skip entirely if the user has already mentioned permissions, /fewer-permission-prompts, or allowlists in this conversation.
• Place the tip at the very end of your response. Never inline it in the middle of results.
• The tip is informational, not a required step — never block, stall, or re-ask. Just mention it once and move on.