claude-plugin-wordpress-manager 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/.claude-plugin/plugin.json +19 -0
  2. package/.mcp.json +19 -0
  3. package/CHANGELOG.md +62 -0
  4. package/LICENSE +69 -0
  5. package/README.md +213 -0
  6. package/agents/wp-content-strategist.md +148 -0
  7. package/agents/wp-deployment-engineer.md +93 -0
  8. package/agents/wp-performance-optimizer.md +198 -0
  9. package/agents/wp-security-auditor.md +161 -0
  10. package/agents/wp-site-manager.md +109 -0
  11. package/commands/wp-audit.md +37 -0
  12. package/commands/wp-backup.md +45 -0
  13. package/commands/wp-deploy.md +38 -0
  14. package/commands/wp-setup.md +64 -0
  15. package/commands/wp-status.md +53 -0
  16. package/docs/GUIDE.md +1190 -0
  17. package/hooks/hooks.json +57 -0
  18. package/hooks/scripts/backup-reminder.sh +29 -0
  19. package/hooks/scripts/pre-deploy-check.sh +49 -0
  20. package/package.json +46 -0
  21. package/scripts/health-check.sh +110 -0
  22. package/scripts/validate-wp-operation.sh +115 -0
  23. package/servers/wp-rest-bridge/build/server.d.ts +2 -0
  24. package/servers/wp-rest-bridge/build/server.js +74 -0
  25. package/servers/wp-rest-bridge/build/tools/comments.d.ts +227 -0
  26. package/servers/wp-rest-bridge/build/tools/comments.js +192 -0
  27. package/servers/wp-rest-bridge/build/tools/index.d.ts +919 -0
  28. package/servers/wp-rest-bridge/build/tools/index.js +30 -0
  29. package/servers/wp-rest-bridge/build/tools/media.d.ts +174 -0
  30. package/servers/wp-rest-bridge/build/tools/media.js +247 -0
  31. package/servers/wp-rest-bridge/build/tools/plugin-repository.d.ts +62 -0
  32. package/servers/wp-rest-bridge/build/tools/plugin-repository.js +149 -0
  33. package/servers/wp-rest-bridge/build/tools/plugins.d.ts +153 -0
  34. package/servers/wp-rest-bridge/build/tools/plugins.js +175 -0
  35. package/servers/wp-rest-bridge/build/tools/search.d.ts +44 -0
  36. package/servers/wp-rest-bridge/build/tools/search.js +44 -0
  37. package/servers/wp-rest-bridge/build/tools/unified-content.d.ts +328 -0
  38. package/servers/wp-rest-bridge/build/tools/unified-content.js +628 -0
  39. package/servers/wp-rest-bridge/build/tools/unified-taxonomies.d.ts +244 -0
  40. package/servers/wp-rest-bridge/build/tools/unified-taxonomies.js +492 -0
  41. package/servers/wp-rest-bridge/build/tools/users.d.ts +269 -0
  42. package/servers/wp-rest-bridge/build/tools/users.js +226 -0
  43. package/servers/wp-rest-bridge/build/types.d.ts +151 -0
  44. package/servers/wp-rest-bridge/build/types.js +2 -0
  45. package/servers/wp-rest-bridge/build/wordpress.d.ts +48 -0
  46. package/servers/wp-rest-bridge/build/wordpress.js +305 -0
  47. package/servers/wp-rest-bridge/package.json +27 -0
  48. package/skills/wordpress-router/SKILL.md +78 -0
  49. package/skills/wordpress-router/references/decision-tree.md +88 -0
  50. package/skills/wp-abilities-api/SKILL.md +97 -0
  51. package/skills/wp-abilities-api/references/php-registration.md +67 -0
  52. package/skills/wp-abilities-api/references/rest-api.md +13 -0
  53. package/skills/wp-audit/SKILL.md +114 -0
  54. package/skills/wp-audit/references/performance-checklist.md +113 -0
  55. package/skills/wp-audit/references/security-checklist.md +95 -0
  56. package/skills/wp-audit/references/seo-checklist.md +128 -0
  57. package/skills/wp-backup/SKILL.md +87 -0
  58. package/skills/wp-backup/references/backup-strategies.md +116 -0
  59. package/skills/wp-backup/references/restore-procedures.md +129 -0
  60. package/skills/wp-block-development/SKILL.md +176 -0
  61. package/skills/wp-block-development/references/attributes-and-serialization.md +22 -0
  62. package/skills/wp-block-development/references/block-json.md +49 -0
  63. package/skills/wp-block-development/references/creating-new-blocks.md +46 -0
  64. package/skills/wp-block-development/references/debugging.md +36 -0
  65. package/skills/wp-block-development/references/deprecations.md +24 -0
  66. package/skills/wp-block-development/references/dynamic-rendering.md +23 -0
  67. package/skills/wp-block-development/references/inner-blocks.md +25 -0
  68. package/skills/wp-block-development/references/registration.md +30 -0
  69. package/skills/wp-block-development/references/supports-and-wrappers.md +18 -0
  70. package/skills/wp-block-development/references/tooling-and-testing.md +21 -0
  71. package/skills/wp-block-development/scripts/list_blocks.mjs +121 -0
  72. package/skills/wp-block-themes/SKILL.md +118 -0
  73. package/skills/wp-block-themes/references/creating-new-block-theme.md +37 -0
  74. package/skills/wp-block-themes/references/debugging.md +24 -0
  75. package/skills/wp-block-themes/references/patterns.md +18 -0
  76. package/skills/wp-block-themes/references/style-variations.md +14 -0
  77. package/skills/wp-block-themes/references/templates-and-parts.md +16 -0
  78. package/skills/wp-block-themes/references/theme-json.md +59 -0
  79. package/skills/wp-block-themes/scripts/detect_block_themes.mjs +117 -0
  80. package/skills/wp-content/SKILL.md +103 -0
  81. package/skills/wp-content/references/content-templates.md +230 -0
  82. package/skills/wp-content/references/seo-optimization.md +169 -0
  83. package/skills/wp-deploy/SKILL.md +52 -0
  84. package/skills/wp-deploy/references/hostinger-deploy.md +51 -0
  85. package/skills/wp-deploy/references/ssh-deploy.md +63 -0
  86. package/skills/wp-interactivity-api/SKILL.md +181 -0
  87. package/skills/wp-interactivity-api/references/debugging.md +29 -0
  88. package/skills/wp-interactivity-api/references/directives-quickref.md +30 -0
  89. package/skills/wp-interactivity-api/references/server-side-rendering.md +310 -0
  90. package/skills/wp-migrate/SKILL.md +100 -0
  91. package/skills/wp-migrate/references/cross-platform.md +104 -0
  92. package/skills/wp-migrate/references/hostinger-migration.md +86 -0
  93. package/skills/wp-performance/SKILL.md +148 -0
  94. package/skills/wp-performance/references/autoload-options.md +24 -0
  95. package/skills/wp-performance/references/cron.md +20 -0
  96. package/skills/wp-performance/references/database.md +20 -0
  97. package/skills/wp-performance/references/http-api.md +15 -0
  98. package/skills/wp-performance/references/measurement.md +21 -0
  99. package/skills/wp-performance/references/object-cache.md +24 -0
  100. package/skills/wp-performance/references/query-monitor-headless.md +38 -0
  101. package/skills/wp-performance/references/server-timing.md +22 -0
  102. package/skills/wp-performance/references/wp-cli-doctor.md +24 -0
  103. package/skills/wp-performance/references/wp-cli-profile.md +32 -0
  104. package/skills/wp-performance/scripts/perf_inspect.mjs +128 -0
  105. package/skills/wp-phpstan/SKILL.md +99 -0
  106. package/skills/wp-phpstan/references/configuration.md +52 -0
  107. package/skills/wp-phpstan/references/third-party-classes.md +76 -0
  108. package/skills/wp-phpstan/references/wordpress-annotations.md +124 -0
  109. package/skills/wp-phpstan/scripts/phpstan_inspect.mjs +263 -0
  110. package/skills/wp-playground/SKILL.md +103 -0
  111. package/skills/wp-playground/references/blueprints.md +36 -0
  112. package/skills/wp-playground/references/cli-commands.md +39 -0
  113. package/skills/wp-playground/references/debugging.md +16 -0
  114. package/skills/wp-plugin-development/SKILL.md +114 -0
  115. package/skills/wp-plugin-development/references/data-and-cron.md +19 -0
  116. package/skills/wp-plugin-development/references/debugging.md +19 -0
  117. package/skills/wp-plugin-development/references/lifecycle.md +33 -0
  118. package/skills/wp-plugin-development/references/security.md +29 -0
  119. package/skills/wp-plugin-development/references/settings-api.md +22 -0
  120. package/skills/wp-plugin-development/references/structure.md +16 -0
  121. package/skills/wp-plugin-development/scripts/detect_plugins.mjs +122 -0
  122. package/skills/wp-project-triage/SKILL.md +40 -0
  123. package/skills/wp-project-triage/references/triage.schema.json +143 -0
  124. package/skills/wp-project-triage/scripts/detect_wp_project.mjs +592 -0
  125. package/skills/wp-rest-api/SKILL.md +116 -0
  126. package/skills/wp-rest-api/references/authentication.md +18 -0
  127. package/skills/wp-rest-api/references/custom-content-types.md +20 -0
  128. package/skills/wp-rest-api/references/discovery-and-params.md +20 -0
  129. package/skills/wp-rest-api/references/responses-and-fields.md +30 -0
  130. package/skills/wp-rest-api/references/routes-and-endpoints.md +36 -0
  131. package/skills/wp-rest-api/references/schema.md +22 -0
  132. package/skills/wp-wpcli-and-ops/SKILL.md +125 -0
  133. package/skills/wp-wpcli-and-ops/references/automation.md +30 -0
  134. package/skills/wp-wpcli-and-ops/references/cron-and-cache.md +23 -0
  135. package/skills/wp-wpcli-and-ops/references/debugging.md +17 -0
  136. package/skills/wp-wpcli-and-ops/references/multisite.md +22 -0
  137. package/skills/wp-wpcli-and-ops/references/packages-and-updates.md +22 -0
  138. package/skills/wp-wpcli-and-ops/references/safety.md +30 -0
  139. package/skills/wp-wpcli-and-ops/references/search-replace.md +40 -0
  140. package/skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs +90 -0
  141. package/skills/wpds/SKILL.md +60 -0
  142. package/skills/wpds/references/wpds-mcp-setup.md +59 -0
@@ -0,0 +1,18 @@
1
+ # Authentication (summary)
2
+
3
+ ## Cookie authentication (in-dashboard / same-site)
4
+
5
+ - Standard for wp-admin and theme/plugin JS.
6
+ - Requires a REST nonce (`wp_rest`) sent as `X-WP-Nonce` header or `_wpnonce` param.
7
+ - If the nonce is missing, the request is treated as unauthenticated even if cookies exist.
8
+
9
+ ## Application Passwords (external clients)
10
+
11
+ - Available in WordPress 5.6+.
12
+ - Use HTTPS + Basic Auth with the application password.
13
+ - Recommended over the legacy Basic Auth plugin.
14
+
15
+ ## Auth plugins
16
+
17
+ - OAuth 1.0a or JWT plugins are common for external apps.
18
+ - Use only if required; follow plugin docs and security guidance.
@@ -0,0 +1,20 @@
1
+ # Custom Content Types (summary)
2
+
3
+ ## Custom post types
4
+
5
+ - Set `show_in_rest => true` in `register_post_type()` to expose in `wp/v2`.
6
+ - Use `rest_base` to change the route slug.
7
+ - Optionally set `rest_controller_class` (must extend `WP_REST_Controller`).
8
+
9
+ ## Custom taxonomies
10
+
11
+ - Set `show_in_rest => true` in `register_taxonomy()`.
12
+ - Use `rest_base` and optional `rest_controller_class` (default `WP_REST_Terms_Controller`).
13
+
14
+ ## Adding REST support to existing types
15
+
16
+ - Use `register_post_type_args` or `register_taxonomy_args` filters to enable `show_in_rest` for types you do not control.
17
+
18
+ ## Discovery links for custom controllers
19
+
20
+ - If you use a custom controller class, use `rest_route_for_post` or `rest_route_for_term` filters to map objects to routes.
@@ -0,0 +1,20 @@
1
+ # Discovery and Global Parameters (summary)
2
+
3
+ ## API discovery
4
+
5
+ - REST API root is discovered via the `Link` header: `rel="https://api.w.org/"`.
6
+ - HTML pages also include a `<link rel="https://api.w.org/" href="...">` element.
7
+ - For non-pretty permalinks, use `?rest_route=/`.
8
+
9
+ ## Global parameters
10
+
11
+ - `_fields` limits response fields (supports nested meta keys).
12
+ - `_embed` includes linked resources in `_embedded`.
13
+ - `_method` or `X-HTTP-Method-Override` allows POST to simulate PUT/DELETE.
14
+ - `_envelope` puts headers/status in the response body.
15
+ - `_jsonp` enables JSONP for legacy clients.
16
+
17
+ ## Pagination
18
+
19
+ - Collections accept `page`, `per_page` (1-100), and `offset`.
20
+ - Pagination headers: `X-WP-Total` and `X-WP-TotalPages`.
@@ -0,0 +1,30 @@
1
+ # Responses and Fields (summary)
2
+
3
+ ## Do not remove core fields
4
+
5
+ - Removing or changing core fields breaks clients (including wp-admin).
6
+ - Prefer adding new fields or using `_fields` to limit response size.
7
+
8
+ ## register_rest_field
9
+
10
+ - Use for computed or custom fields.
11
+ - Provide `get_callback`, optional `update_callback`, and `schema`.
12
+ - Register on `rest_api_init`.
13
+
14
+ ## Raw vs rendered content
15
+
16
+ - For posts, `content.rendered` reflects filters (plugins like ToC inject HTML).
17
+ - Use `?context=edit` (authenticated) to access `content.raw`.
18
+ - Combine with `_fields=content.raw` when you only need the editable body.
19
+
20
+ ## register_meta / register_post_meta / register_term_meta
21
+
22
+ - Use when the data is stored as meta.
23
+ - Set `show_in_rest => true` to expose under `.meta`.
24
+ - For `object` or `array` types, provide a JSON schema in `show_in_rest.schema`.
25
+
26
+ ## Links and embedding
27
+
28
+ - Add links with `WP_REST_Response::add_link( $rel, $href, $attrs )`.
29
+ - Use `embeddable => true` to allow `_embed`.
30
+ - Use IANA rels or a custom URI relation; CURIEs can be registered via `rest_response_link_curies`.
@@ -0,0 +1,36 @@
1
+ # Routes and Endpoints (summary)
2
+
3
+ ## Registering routes
4
+
5
+ - Register routes on the `rest_api_init` hook with `register_rest_route( $namespace, $route, $args )`.
6
+ - A **route** is the URL pattern; an **endpoint** is the method + callback bound to that route.
7
+ - For non-pretty permalinks, the route is accessed via `?rest_route=/namespace/route`.
8
+
9
+ ## Namespacing
10
+
11
+ - Always namespace routes (`vendor/v1`).
12
+ - **Do not** use the `wp/*` namespace unless you are targeting core.
13
+
14
+ ## Methods
15
+
16
+ - Use `WP_REST_Server::READABLE` (GET), `CREATABLE` (POST), `EDITABLE` (PUT/PATCH), `DELETABLE` (DELETE).
17
+ - Multiple endpoints can share a route, one per method.
18
+
19
+ ## permission_callback (required)
20
+
21
+ - Always provide `permission_callback`.
22
+ - Public endpoints should use `__return_true`.
23
+ - For restricted endpoints, use capability checks (`current_user_can`) or object-level authorization.
24
+ - Missing `permission_callback` emits a `_doing_it_wrong` notice in modern WP.
25
+
26
+ ## Arguments
27
+
28
+ - Register `args` to validate and sanitize inputs.
29
+ - Use `type`, `required`, `default`, `validate_callback`, `sanitize_callback`.
30
+ - Access params via the `WP_REST_Request` object, not `$_GET`/`$_POST`.
31
+
32
+ ## Return values
33
+
34
+ - Return data via `rest_ensure_response()` or a `WP_REST_Response`.
35
+ - Return `WP_Error` with a `status` in `data` for error responses.
36
+ - Do not call `wp_send_json()` in REST callbacks.
@@ -0,0 +1,22 @@
1
+ # Schema and Argument Validation (summary)
2
+
3
+ ## JSON Schema in WordPress
4
+
5
+ - REST API uses JSON Schema (draft 4 subset) for resource and argument definitions.
6
+ - Provide schema via `get_item_schema()` on controllers or `schema` callbacks on routes.
7
+ - Schema enables discovery (`OPTIONS`) and validation.
8
+
9
+ ## Validation + sanitization
10
+
11
+ - Use `rest_validate_value_from_schema( $value, $schema )` then `rest_sanitize_value_from_schema( $value, $schema )`.
12
+ - If you override `sanitize_callback`, built-in schema validation will not run; use `rest_validate_request_arg` to keep it.
13
+ - `WP_REST_Controller::get_endpoint_args_for_item_schema()` wires validation automatically.
14
+
15
+ ## Schema caching
16
+
17
+ - Cache the generated schema on the controller instance (`$this->schema`) to avoid recomputation.
18
+
19
+ ## Formats and types
20
+
21
+ - Common formats: `date-time`, `uri`, `email`, `ip`, `uuid`, `hex-color`.
22
+ - For `array` and `object` types, you must define `items` or `properties` schemas.
@@ -0,0 +1,125 @@
1
+ ---
2
+ name: wp-wpcli-and-ops
3
+ description: "Use when working with WP-CLI (wp) for WordPress operations: safe search-replace, db export/import, plugin/theme/user/content management, cron, cache flushing, multisite, and scripting/automation with wp-cli.yml."
4
+ compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires WP-CLI in the execution environment."
5
+ version: 1.0.0
6
+ source: "WordPress/agent-skills (GPL-2.0-or-later)"
7
+ ---
8
+
9
+ # WP-CLI and Ops
10
+
11
+ ## When to use
12
+
13
+ Use this skill when the task involves WordPress operational work via WP-CLI, including:
14
+
15
+ - `wp search-replace` (URL changes, domain migrations, protocol switch)
16
+ - DB export/import, resets, and inspections (`wp db *`)
17
+ - plugin/theme install/activate/update, language packs
18
+ - cron event listing/running
19
+ - cache/rewrite flushing
20
+ - multisite operations (`wp site *`, `--url`, `--network`)
21
+ - building repeatable scripts (`wp-cli.yml`, shell scripts, CI jobs)
22
+
23
+ ## Inputs required
24
+
25
+ - Where WP-CLI will run (local dev, staging, production) and whether it’s safe to run.
26
+ - How to target the correct site root:
27
+ - `--path=<wordpress-root>` and (multisite) `--url=<site-url>`
28
+ - Whether this is multisite and whether commands should run network-wide.
29
+ - Any constraints (no downtime, no DB writes, maintenance window).
30
+
31
+ ## Procedure
32
+
33
+ ### 0) Guardrails: confirm environment and blast radius
34
+
35
+ WP-CLI commands can be destructive. Before running anything that writes:
36
+
37
+ 1. Confirm environment (dev/staging/prod).
38
+ 2. Confirm targeting (path/url) so you don’t hit the wrong site.
39
+ 3. Make a backup when performing risky operations.
40
+
41
+ Read:
42
+ - `references/safety.md`
43
+
44
+ ### 1) Inspect WP-CLI and site targeting (deterministic)
45
+
46
+ Run the inspector:
47
+
48
+ - `node skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs --path=<path> [--url=<url>]`
49
+
50
+ If WP-CLI isn’t available, fall back to installing it via the project’s documented tooling (Composer, container, or system package), or ask for the expected execution environment.
51
+
52
+ ### 2) Choose the right workflow
53
+
54
+ #### A) Safe URL/domain migration (`search-replace`)
55
+
56
+ Follow a safe sequence:
57
+
58
+ 1. `wp db export` (backup)
59
+ 2. `wp search-replace --dry-run` (review impact)
60
+ 3. Run the real replace with appropriate flags
61
+ 4. Flush caches/rewrite if needed
62
+
63
+ Read:
64
+ - `references/search-replace.md`
65
+
66
+ #### B) Plugin/theme operations
67
+
68
+ Use `wp plugin *` / `wp theme *` and confirm you’re acting on the intended site (and network) first.
69
+
70
+ Read:
71
+ - `references/packages-and-updates.md`
72
+
73
+ #### C) Cron and queues
74
+
75
+ Inspect cron state and run individual events for debugging rather than “run everything blindly”.
76
+
77
+ Read:
78
+ - `references/cron-and-cache.md`
79
+
80
+ #### D) Multisite operations
81
+
82
+ Multisite changes can affect many sites. Always decide whether you’re operating:
83
+
84
+ - on a single site (`--url=`), or
85
+ - network-wide (`--network` / iterating sites)
86
+
87
+ Read:
88
+ - `references/multisite.md`
89
+
90
+ ### 3) Automation patterns (scripts + wp-cli.yml)
91
+
92
+ For repeatable ops, prefer:
93
+
94
+ - `wp-cli.yml` for defaults (path/url, PHP memory limits)
95
+ - shell scripts that log commands and stop on error
96
+ - CI jobs that run read-only checks by default
97
+
98
+ Read:
99
+ - `references/automation.md`
100
+
101
+ ## Verification
102
+
103
+ - Re-run `wpcli_inspect` after changes that could affect targeting or config.
104
+ - Confirm intended side effects:
105
+ - correct URLs updated
106
+ - plugins/themes in expected state
107
+ - cron/caches flushed where needed
108
+ - If there’s a health check endpoint or smoke test suite, run it after ops changes.
109
+
110
+ ## Failure modes / debugging
111
+
112
+ - “Error: This does not seem to be a WordPress installation.”
113
+ - wrong `--path`, wrong container, or missing `wp-config.php`
114
+ - Multisite commands affecting the wrong site
115
+ - missing `--url` or wrong URL
116
+ - Search-replace causes unexpected serialization issues
117
+ - wrong flags or changing serialized data unsafely
118
+
119
+ See:
120
+ - `references/debugging.md`
121
+
122
+ ## Escalation
123
+
124
+ - If you cannot confirm environment safety, do not run write operations.
125
+ - If the repo uses containerized tooling (Docker/wp-env) but you can’t access it, ask for the intended command runner or CI job.
@@ -0,0 +1,30 @@
1
+ # Automation with WP-CLI
2
+
3
+ Use this file when turning an ops sequence into a repeatable script or CI job.
4
+
5
+ ## `wp-cli.yml`
6
+
7
+ If the repo uses `wp-cli.yml`, use it to standardize:
8
+
9
+ - `path:` (WordPress root)
10
+ - `url:` (default site)
11
+ - PHP settings (memory limits)
12
+
13
+ ## Shell scripting
14
+
15
+ Guardrails for scripts:
16
+
17
+ - `set -euo pipefail`
18
+ - print commands before running them
19
+ - make destructive operations require an explicit flag (e.g. `--apply`)
20
+
21
+ ## CI jobs
22
+
23
+ Prefer CI jobs that are read-only by default:
24
+
25
+ - `wp core version`
26
+ - `wp plugin list`
27
+ - `wp theme list`
28
+
29
+ Only enable write operations in dedicated deploy/maintenance workflows.
30
+
@@ -0,0 +1,23 @@
1
+ # Cron, caches, and rewrites
2
+
3
+ Use this file when debugging background jobs or “changes not visible”.
4
+
5
+ ## Cron
6
+
7
+ - List scheduled events:
8
+ - `wp cron event list`
9
+ - Run a specific event now:
10
+ - `wp cron event run <hook>`
11
+
12
+ ## Cache + rewrite
13
+
14
+ - Flush object cache:
15
+ - `wp cache flush`
16
+ - Flush rewrite rules:
17
+ - `wp rewrite flush`
18
+
19
+ ## Guardrails
20
+
21
+ - Don’t “run all cron events” on production without understanding impact.
22
+ - Cache flush can cause load spikes; coordinate if needed.
23
+
@@ -0,0 +1,17 @@
1
+ # Debugging WP-CLI
2
+
3
+ ## WP not found / wrong WP root
4
+
5
+ - Run `wp --info`.
6
+ - Provide `--path=<wordpress-root>` if WP is not in the current directory.
7
+ - Confirm `wp-config.php` exists in the expected root.
8
+
9
+ ## HTTP/URL targeting issues
10
+
11
+ - On multisite, include `--url=<site-url>` for site-specific actions.
12
+
13
+ ## Permission/file ownership issues
14
+
15
+ - If running in containers, ensure you’re using the same user/volume mapping as the app.
16
+ - Avoid `--allow-root` unless you understand the environment and have no alternative.
17
+
@@ -0,0 +1,22 @@
1
+ # Multisite targeting
2
+
3
+ Use this file any time you might be operating on multisite.
4
+
5
+ ## Key flags
6
+
7
+ - `--url=<site-url>` targets a specific site/blog context.
8
+ - `--network` applies to the network where supported.
9
+
10
+ ## Common commands
11
+
12
+ - List sites:
13
+ - `wp site list`
14
+ - Get site options for a specific site:
15
+ - `wp option get siteurl --url=<site-url>`
16
+
17
+ ## Guardrails
18
+
19
+ - Always include `--url` when you mean “one site” in a multisite install.
20
+ - If you need to run something across sites, prefer scripting:
21
+ - list sites → iterate → run a safe per-site command.
22
+
@@ -0,0 +1,22 @@
1
+ # Plugin/theme operations
2
+
3
+ Use this file for installs, activation, updates, and listing state.
4
+
5
+ ## Common commands
6
+
7
+ - Plugins:
8
+ - `wp plugin list`
9
+ - `wp plugin status <slug>`
10
+ - `wp plugin activate <slug>`
11
+ - `wp plugin deactivate <slug>`
12
+ - `wp plugin update --all`
13
+ - Themes:
14
+ - `wp theme list`
15
+ - `wp theme activate <slug>`
16
+ - `wp theme update --all`
17
+
18
+ ## Guardrails
19
+
20
+ - On production, avoid `update --all` without a maintenance window.
21
+ - On multisite, plugin activation may be per-site or network-wide; confirm intent.
22
+
@@ -0,0 +1,30 @@
1
+ # Safety rules (WP-CLI)
2
+
3
+ Use this file before running any write operations.
4
+
5
+ ## Golden rules
6
+
7
+ - Assume production is **unsafe** unless explicitly confirmed.
8
+ - Always confirm targeting:
9
+ - `--path` (WordPress root)
10
+ - `--url` (multisite / specific site targeting)
11
+ - Prefer a backup (`wp db export`) before risky operations.
12
+ - Prefer `--dry-run` where available (especially `search-replace`).
13
+
14
+ ## High-risk commands (require explicit confirmation)
15
+
16
+ - `wp db reset`
17
+ - `wp db import` (overwrites data)
18
+ - `wp search-replace` (can affect serialized data and URLs)
19
+ - bulk deletes (`wp post delete --force --all`, `wp user delete --reassign`, etc.)
20
+ - plugin/theme mass updates on production
21
+
22
+ ## Logging
23
+
24
+ For ops scripts, log:
25
+
26
+ - date/time
27
+ - environment (dev/staging/prod)
28
+ - exact WP-CLI commands
29
+ - exit codes
30
+
@@ -0,0 +1,40 @@
1
+ # Safe `wp search-replace`
2
+
3
+ Use this file when migrating domains, switching http→https, or changing paths.
4
+
5
+ ## Recommended workflow
6
+
7
+ 1. Backup:
8
+ - `wp db export`
9
+ 2. Dry run:
10
+ - `wp search-replace OLD NEW --dry-run`
11
+ 3. Run for real (carefully choose scope):
12
+ - consider `--all-tables-with-prefix` if you need to include non-core tables with the WP prefix
13
+ 4. Flush:
14
+ - `wp cache flush`
15
+ - `wp rewrite flush`
16
+
17
+ ## Multisite notes
18
+
19
+ For multisite, decide whether you’re replacing:
20
+
21
+ - a single site (`--url=...`), or
22
+ - across the network (`--network` or iterating `wp site list`).
23
+
24
+ Read:
25
+ - `references/multisite.md`
26
+
27
+ ## Common flags
28
+
29
+ - `--dry-run`
30
+ - `--precise` (slower but can be safer in complex cases)
31
+ - `--skip-columns=...` (avoid touching large/binary columns)
32
+ - `--report-changed-only`
33
+
34
+ ## Serialization caution
35
+
36
+ WP-CLI search-replace is designed to handle PHP serialized data, but you must still:
37
+
38
+ - avoid replacing within binary/blob columns
39
+ - validate results with application smoke tests
40
+
@@ -0,0 +1,90 @@
1
+ import { spawnSync } from "node:child_process";
2
+
3
+ const TOOL_VERSION = "0.1.0";
4
+
5
+ function parseArgs(argv) {
6
+ const args = { path: null, url: null, allowRoot: false };
7
+ for (const a of argv) {
8
+ if (a === "--allow-root") args.allowRoot = true;
9
+ if (a.startsWith("--path=")) args.path = a.slice("--path=".length);
10
+ if (a.startsWith("--url=")) args.url = a.slice("--url=".length);
11
+ }
12
+ return args;
13
+ }
14
+
15
+ function runWp(cmdArgs, { pathArg, urlArg, allowRoot }) {
16
+ const args = [];
17
+ if (allowRoot) args.push("--allow-root");
18
+ if (pathArg) args.push(`--path=${pathArg}`);
19
+ if (urlArg) args.push(`--url=${urlArg}`);
20
+ args.push(...cmdArgs);
21
+
22
+ const out = spawnSync("wp", args, { encoding: "utf8" });
23
+ return {
24
+ ok: out.status === 0,
25
+ status: out.status,
26
+ error: out.error ? { message: out.error.message, code: out.error.code } : null,
27
+ stdout: (out.stdout || "").trim(),
28
+ stderr: (out.stderr || "").trim(),
29
+ args,
30
+ };
31
+ }
32
+
33
+ function main() {
34
+ const opts = parseArgs(process.argv.slice(2));
35
+
36
+ const info = runWp(["--info"], { pathArg: null, urlArg: null, allowRoot: opts.allowRoot });
37
+ const report = {
38
+ tool: { name: "wpcli_inspect", version: TOOL_VERSION },
39
+ wpCli: {
40
+ available: info.ok,
41
+ info,
42
+ },
43
+ wordpress: {
44
+ path: opts.path,
45
+ url: opts.url,
46
+ isInstalled: null,
47
+ coreVersion: null,
48
+ isMultisite: null,
49
+ siteurl: null,
50
+ home: null,
51
+ },
52
+ notes: [],
53
+ };
54
+
55
+ if (!info.ok) {
56
+ report.notes.push("WP-CLI not available on PATH. Install WP-CLI or run inside the intended container/environment.");
57
+ process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
58
+ return;
59
+ }
60
+
61
+ const isInstalled = runWp(["core", "is-installed"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
62
+ report.wordpress.isInstalled = isInstalled.ok;
63
+
64
+ if (!isInstalled.ok) {
65
+ report.notes.push("WordPress not detected at the given path/url. Check --path/--url (multisite) and that wp-config.php is present.");
66
+ process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
67
+ return;
68
+ }
69
+
70
+ const coreVersion = runWp(["core", "version"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
71
+ report.wordpress.coreVersion = coreVersion.ok ? coreVersion.stdout : null;
72
+
73
+ const isMultisite = runWp(["core", "is-installed", "--network"], {
74
+ pathArg: opts.path,
75
+ urlArg: opts.url,
76
+ allowRoot: opts.allowRoot,
77
+ });
78
+ // If network check passes, we can assume multisite. If it fails, it might still be multisite depending on context.
79
+ report.wordpress.isMultisite = isMultisite.ok;
80
+
81
+ const siteurl = runWp(["option", "get", "siteurl"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
82
+ report.wordpress.siteurl = siteurl.ok ? siteurl.stdout : null;
83
+
84
+ const home = runWp(["option", "get", "home"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
85
+ report.wordpress.home = home.ok ? home.stdout : null;
86
+
87
+ process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
88
+ }
89
+
90
+ main();
@@ -0,0 +1,60 @@
1
+ ---
2
+ name: wpds
3
+ description: "Use when building UIs leveraging the WordPress Design System (WPDS) and its components, tokens, patterns, etc."
4
+ compatibility: "Requires WPDS MCP server configured and running. Targets WordPress 6.9+ (PHP 7.2.24+)."
5
+ version: 1.0.0
6
+ source: "WordPress/agent-skills (GPL-2.0-or-later)"
7
+ ---
8
+
9
+ # WordPress Design System (WPDS)
10
+
11
+ ## Prerequisites
12
+
13
+ This skill works best with the **WPDS MCP server** installed. The MCP provides access to WordPress Design System documentation and resources, such as components and DS token lists.
14
+
15
+ The following terms should be treated as synonyms:
16
+ - "WordPress" and "WP";
17
+ - "Design System" and "DS";
18
+ - "WordPress Design System" and "WPDS".
19
+
20
+ ## When to use
21
+
22
+ Use this skill when the user mentions:
23
+
24
+ - building and/or reviewing any UI in a WordPress-related context (for example, Gutenberg, WooCommerce, WordPress.com, Jetpack, etc etc);
25
+ - WordPress Design System, WPDS, Design System;
26
+ - UI components, Design tokens, color primitives, spacing scales, typography variables and presets;
27
+ - Specific component packages such as @wordpress/components or @wordpress/ui;
28
+
29
+ ## Rules
30
+
31
+ ### Use the WPDS MCP server to access WPDS-related documentation
32
+
33
+ - Use the WPDS MCP server to retrieve the canonical, authoritative documentation:
34
+ - reference site (`wpds://pages`)
35
+ - list of available components (`wpds://components`) and specific component information (`wpds://components/:name`)
36
+ - list of available tokens (`wpds://design-tokens`)
37
+ - DO NOT search the web for canonical documentation about the WordPress Design System. If asked by the user, push back and ask for confirmation, warning them that the MCP server is the best place to provide information
38
+
39
+ ### Required documentation
40
+
41
+ Before working on any WPDS-related tasks, make sure you read relevant documentation on the reference site. This documentation should take the absolute precedence when evaluating the best course of action for any given tasks.
42
+
43
+ ### Boundaries
44
+
45
+ - Skip non-UI related aspects of an answer (for example, fetching data from stores, or localizing strings of text).
46
+ - Focus on building UI that adheres as much as possible to the WPDS best practices, uses the most fitting WPDS components/tokens/patterns.
47
+
48
+ ### Tech stack
49
+
50
+ - Unless you are told otherwise (or gathered specific information from the local context of the request), assume the following tech stack: TypeScript, React, CSS.
51
+
52
+ ### Validation
53
+
54
+ - If the local context in which a task is running provide lint scripts, use them to validate the proposed code output when possible.
55
+
56
+ ## Output
57
+
58
+ - As a recap at the end of your response, provide a clear and concise explanation of what the solution does, and add context to why each decision was made.
59
+ - Be explicit about the boundaries, ie. what was explicitly left out of the task because not relevant (eg non-ui related).
60
+ - Provide working code snippets
@@ -0,0 +1,59 @@
1
+ # WPDS MCP Server Setup
2
+
3
+ The `wpds` skill depends on an external **WPDS MCP server** to access canonical WordPress Design System documentation (components, tokens, patterns).
4
+
5
+ ## What the WPDS MCP server provides
6
+
7
+ | Resource URI | Description |
8
+ |-------------|-------------|
9
+ | `wpds://pages` | Reference site pages (getting started, principles, guidelines) |
10
+ | `wpds://components` | List of all available WPDS components |
11
+ | `wpds://components/:name` | Detailed documentation for a specific component |
12
+ | `wpds://design-tokens` | Full list of design tokens (colors, spacing, typography) |
13
+
14
+ ## Setup
15
+
16
+ ### Option 1: Official WPDS MCP server (when available)
17
+
18
+ Check the [WordPress Design System](https://wordpress.github.io/gutenberg/?path=/docs/docs-introduction--page) for an official MCP server package.
19
+
20
+ ### Option 2: Custom MCP server
21
+
22
+ If no official server exists, you can build a lightweight MCP server that serves WPDS documentation from the Gutenberg repository:
23
+
24
+ ```json
25
+ {
26
+ "mcpServers": {
27
+ "wpds": {
28
+ "command": "node",
29
+ "args": ["path/to/wpds-mcp-server.js"]
30
+ }
31
+ }
32
+ }
33
+ ```
34
+
35
+ ### Option 3: Without MCP server (degraded mode)
36
+
37
+ The skill still works without the MCP server but with limitations:
38
+ - Cannot query live component documentation
39
+ - Cannot list design tokens programmatically
40
+ - Falls back to general knowledge of `@wordpress/components` and `@wordpress/ui`
41
+
42
+ ## Key WPDS packages
43
+
44
+ | Package | Purpose |
45
+ |---------|---------|
46
+ | `@wordpress/components` | Core UI component library (Button, Modal, TextControl, etc.) |
47
+ | `@wordpress/ui` | Next-gen component library (experimental) |
48
+ | `@wordpress/primitives` | SVG icons and primitive UI elements |
49
+ | `@wordpress/icons` | Icon set for WordPress admin UI |
50
+
51
+ ## Design tokens reference
52
+
53
+ When the MCP server is unavailable, use these canonical sources:
54
+
55
+ - **Color primitives**: `packages/components/src/utils/colors-values.js` in Gutenberg repo
56
+ - **Spacing scale**: Based on 4px grid (4, 8, 12, 16, 20, 24, 32, 40, 48, 56, 64)
57
+ - **Typography**: System font stack, sizes from 11px to 32px
58
+ - **Border radius**: 2px (default), 4px (cards), 50% (circular)
59
+ - **Elevation/shadows**: 3 levels (low, medium, high)