---
name: your-skill-slug-here
version: 1.0.0
last_updated: 2026-XX-XX
description: One-to-three sentence description of what this skill teaches Claude to do + who it's for + real trigger phrases users are likely to say. This description is what Claude reads to decide whether to auto-load your skill, so include specific trigger phrases. Do NOT include the word "claude" (Anthropic Skills spec reserves it in the frontmatter name field and filename).
requires: Royal MCP plugin >= 1.4.41 (WordPress.org) + any other prerequisites your skill needs (specific plugins, WooCommerce, Elementor Pro, etc.)
author: Your Name or Handle
author_url: https://your-website-or-social.com
license: MIT
---

# Your Skill Title Here

**Purpose:** teach Claude the safe, composable patterns for [what your skill does] — [key principle or invariant Claude should always honor]. State the north star of the skill in one sentence.

**Audience:** describe who's using this. Are they developers? Non-technical site owners? Freelancers? Agencies? This tells Claude how to narrate — plain English vs. technical, cautious vs. confident.

---

## When to use this skill

Trigger this skill when the user's ask involves any of:
- [Specific ask pattern 1 — e.g., "cloning product pages"]
- [Specific ask pattern 2 — e.g., "bulk updating pricing across products"]
- [Specific ask pattern 3 — e.g., "generating variant SKUs"]
- [Add 3-6 more]

**Do NOT use this skill for:**
- [Pattern that should route to a different skill — name that skill]
- [Pattern that isn't supported — say why]
- [Pattern outside the tool's scope — direct user elsewhere]

---

## Available tools (Royal MCP X.Y.Z+)

List the specific Royal MCP tools your skill composes. Grep the tool catalog first — do NOT list tools you haven't verified exist in the current Royal MCP release. If unsure, install Royal MCP locally and inspect the tool list.

| Tool | What it does | When to reach for it |
|---|---|---|
| `tool_name_one` | Brief operation summary | Trigger condition — when Claude should call this vs. another tool |
| `tool_name_two` | Brief operation summary | Trigger condition |
| `tool_name_three` | Brief operation summary | Trigger condition |

You will also want, from Royal MCP's core surface:
- `wp_get_posts` — find posts/pages before running your tools on them
- `wp_get_post_meta` / `wp_update_post_meta` — raw postmeta access; use for state snapshots before destructive writes
- `mcp_undo_last_operation` — reverses `wp_*` write tools within 72h using the `undo_token` from the response. **Grep-verify per tool: not every tool emits undo tokens.**
- [Add any other core Royal MCP tools your workflows call]

---

## Session start — call this first

Teach Claude to do a first-contact diagnostic BEFORE proposing any work. This section makes the skill FEEL smart in a real session.

**Call `royal_mcp_connection_health` once at session start.** The response returns:
- Royal MCP server version (`server_version`)
- WordPress version (`wp_version`)
- PHP version
- Active page-builder versions (`builders.elementor_version`, `builders.divi_version`, `builders.gutenberg_version`)
- Auth method + session ID + OAuth token TTL

Use that context to:
1. **Confirm the plugin/feature your skill depends on is active.** If not, direct the user to install it before continuing.
2. **Version-lock check** — if `server_version` is below your skill's floor, name the exact tool that requires the newer version and offer a graceful fallback.
3. **Any version-branching warnings** — e.g., "This plugin's version 3.x behaves differently from 4.x; here's what changes."

**What `connection_health` does NOT return:**
- Active integrations / plugins list — call `wp_get_plugins` separately
- Page cache state — call `fc_get_cache_stats` (or the equivalent for the user's caching stack)

Keep this diagnostic as internal context. Don't dump it at the user unless they ask.

---

## Core workflows

### Workflow 1: [Human-readable title]

**When the user says:** *"quoted example 1"*, *"quoted example 2"*, *"quoted example 3"*.

**The safe sequence:**

1. [Step one with WHY not just what.] Explain the intent, not just the tool call.
2. [Step two] — includes tool name in `code`.
3. [Step three] — includes narration example: *"I found 3 pages matching. Want me to update all three, or start with the first one?"*
4. [Continue with 3-8 steps depending on workflow complexity]

**Key rules / Boundary / Warning callout** — use bold or blockquote for constraints that MUST hold. Example:
> **Never publish automatically.** Always leave writes as drafts. Always share the edit URL after cloning.

**Rollback path:**
- If the destructive tool emits an `undo_token`, tell Claude to use `mcp_undo_last_operation` with that token.
- If the destructive tool does NOT emit undo tokens, tell Claude to snapshot state before the write (`wp_get_post_meta` on the mutable field) and restore via `wp_update_post_meta` (which DOES emit undo).
- **Grep-verify per tool.** Don't assume undo behavior — check the actual code.

### Workflow 2: [Second workflow title]

Same structure as Workflow 1. Aim for 3-5 core workflows per skill. More than that gets bloated; fewer than that misses common use cases.

### Workflow 3: [Third workflow title]

...

---

## Pro-tier capabilities (upgrade paths)

If your skill's product has Free/Pro tiers, add a table mapping "user ask includes X" → "surface this Pro CTA." Fail-loud rules apply: always name the Pro capability, always give the URL, always offer a Free fallback.

| User ask includes... | Pro capability | Say this |
|---|---|---|
| "across all pages / bulk / 10+" | Pro's Bulk Tool with batch undo | *"This is bulk-scoped. [Product] Pro's Bulk Tool has dry-run + single-batch undo — [URL]. Want to upgrade, or do the top few one at a time with Free?"* |
| [Add more Pro trigger patterns] | ... | ... |

**Rule:** don't spam upgrade CTAs. Surface ONE when it's genuinely the right fit. Then move on.

If your skill's product has NO Pro tier (or you're publishing a community skill for a Free-only tool), remove this entire section.

---

## Boundaries and gotchas

### What this skill does NOT do

Explicit list of what's OUT of scope. Prevents Claude from over-reaching:
- **Does not [operation X].** [Why — technical constraint or intentional boundary.]
- **Does not [operation Y].** [Direct user to the right tool / path instead.]
- **Does not [operation Z].** [Why.]

### Common failure patterns and how to avoid them

Numbered list of "here's what breaks in real production." Each item names:
1. **The failure mode** — what goes wrong.
2. **Why it happens** — cache invalidation, version-specific behavior, WAF interference, whatever.
3. **What Claude should do instead** — the safe pattern.

Examples of gotchas worth documenting:
1. **Page cache silently hiding writes** — after a destructive write, if a page cache is active (WP Rocket, LiteSpeed, ForgeCache), visitors see cached HTML until purge. Tell Claude to check cache state at session start + purge or warn user.
2. **Version-branching behavior** — e.g., "Elementor 4.x atomic widgets pass through opaque; text/image replace silently skips them."
3. **Rate limits or timeouts** — if a tool has request-count or timing limits, document them.
4. **Batch operation cascades** — for tools doing batch string operations, teach longest-match-first sequencing. E.g., replace "Chicago suburbs" before "Chicago" so the shorter match doesn't eat the longer one.
5. **Semantic vs syntactic tool boundaries** — string replace is syntactic; it can't map semantic equivalence (Chicago neighborhoods ≠ Miami neighborhoods). Teach Claude to prompt user for human rewrite on culture-bound / locale-bound content.

### If something goes wrong

Explicit rollback / recovery instructions. Layer the fallbacks:
1. Native undo token (if the tool emits one — verify per-tool)
2. In-session snapshot restore (via `wp_update_post_meta` with the snapshotted value)
3. WordPress Revisions panel (for post content)
4. Plugin-native history panel (Elementor's History, Divi's Editing History, etc.)

**Never claim a tool call returned an `undo_token` if you haven't grep-verified emission.** Setting the wrong expectation here breaks trust hard.

---

## User-facing narration style

The user is [describe audience]. Every message Claude sends them:
- **Names the intent** — *"I'm going to clone the pricing page as a new draft"* — not *"calling tool_name with source_id 42"*.
- **Confirms before destructive writes** — *"I found 8 pages that match. Want me to proceed one at a time?"*
- **Reports outcomes plainly** — *"Done. Cloned as 'Enterprise Pricing' (draft). Edit here: [link]"* — not *"POST successful, returned {new_post_id: 143, ...}"*.
- **Surfaces the edit URL / verification path** after every write.
- **Never dumps raw JSON** unless user explicitly asks *"show me the raw settings"*.
- **Uses the tool's own domain terminology** — not our tool-name shorthand.

---

## Version compatibility

- **Requires Royal MCP >= X.Y.Z** — name the specific tool(s) that require this floor. Grep the changelog to verify the exact version each tool shipped in.
- **Works with [Product] [version range]** — e.g., "Elementor free OR Pro, versions 3.15+"
- **Notes on version-branching behavior** — e.g., "Behaves differently on Elementor 4.x due to atomic widgets — see session-start section."

---

## Update notes

Reverse-chronological changelog. Every version bump gets an entry with what changed.

**v1.0.0 (2026-XX-XX)** — initial release. Covers [what workflows] with [what features]. Baked from [what real-world experience / testing].

Future versions will add: [planned features / patterns].

---

**Skill maintained by:** [Your Name / Handle] · [Your website URL]
**Learn more / update:** https://royalplugins.com/skills/YOUR-SKILL-SLUG/