wp-skills 1.0.0

package/skills/wp-plugin-development/references/data-and-cron.md

@@ -0,0 +1,19 @@
+# Data storage, cron, and upgrades
+
+Use this file when adding persistent storage, background jobs, or upgrade routines.
+
+## Data storage
+
+- Prefer Options API for small config/state.
+- Use custom tables only when needed; store schema version and provide upgrade paths.
+
+## Cron
+
+- Ensure tasks are idempotent (may run late or multiple times).
+- Provide a manual trigger path for debugging (WP-CLI or admin-only action).
+
+## Database safety note
+
+If using `$wpdb->prepare()`, avoid building queries with concatenated user input.
+Recent WordPress versions support identifier placeholders (`%i`) but you must not assume it exists without checking capabilities or target versions.
+

package/skills/wp-plugin-development/references/debugging.md

@@ -0,0 +1,19 @@
+# Debugging quick routes
+
+## Plugin doesn’t load / fatal errors
+
+- Confirm correct plugin main file and header.
+- Check PHP error logs and `WP_DEBUG_LOG`.
+- If the repo is a site repo, confirm you edited the correct plugin under `wp-content/plugins/`.
+
+## Activation hook surprises
+
+- Hooks must be registered at top-level.
+- Activation runs in a special context; avoid assuming other hooks already ran.
+
+## Settings not saving
+
+- Confirm `register_setting()` is called.
+- Confirm the option group matches the form.
+- Confirm capability checks and nonces.
+

package/skills/wp-plugin-development/references/lifecycle.md

@@ -0,0 +1,33 @@
+# Activation, deactivation, uninstall
+
+Use this file for lifecycle changes and data cleanup.
+
+## Activation / deactivation hooks
+
+- `register_activation_hook( __FILE__, 'callback' )`
+- `register_deactivation_hook( __FILE__, 'callback' )`
+
+Guardrails:
+
+- These hooks must be registered at top-level (not inside other hooks).
+- If you flush rewrite rules, ensure rules are registered first (often via a shared function called both on `init` and activation).
+
+Upstream reference:
+
+- https://developer.wordpress.org/plugins/plugin-basics/activation-deactivation-hooks/
+
+## Uninstall
+
+Preferred approaches:
+
+- `uninstall.php` (runs only on uninstall)
+- `register_uninstall_hook()`
+
+Guardrails:
+
+- Check `WP_UNINSTALL_PLUGIN` before running destructive cleanup.
+
+Upstream reference:
+
+- https://developer.wordpress.org/plugins/plugin-basics/uninstall-methods/
+

package/skills/wp-plugin-development/references/security.md

@@ -0,0 +1,29 @@
+# Security guardrails (plugin work)
+
+Use this file when making security fixes or when handling any input/output.
+
+## Nonces + permissions
+
+- Nonces help prevent CSRF, not authorization.
+- Always pair nonces with capability checks (`current_user_can()` or a more specific capability).
+
+Upstream reference:
+
+- https://developer.wordpress.org/apis/security/nonces/
+
+## Sanitization and escaping
+
+Golden rule:
+
+- sanitize/validate on input, escape on output.
+
+Practical rules:
+
+- never process the entire `$_POST` / `$_GET` array; read explicit keys
+- use `wp_unslash()` before sanitizing when needed
+- use prepared statements for SQL; avoid interpolating user input into queries
+
+Common review guidance:
+
+- https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/
+

package/skills/wp-plugin-development/references/settings-api.md

@@ -0,0 +1,22 @@
+# Settings API (admin options)
+
+Use this file when adding settings pages or storing user-configurable options.
+
+Core APIs:
+
+- `register_setting()`
+- `add_settings_section()`
+- `add_settings_field()`
+
+Upstream references:
+
+- Settings API overview: https://developer.wordpress.org/plugins/settings/settings-api/
+- Register settings: https://developer.wordpress.org/plugins/settings/registration/
+- Add settings fields: https://developer.wordpress.org/plugins/settings/settings-fields/
+
+Practical guardrails:
+
+- Use `sanitize_callback` to validate/sanitize data.
+- Use capability checks (commonly `manage_options`) for settings screens and saves.
+- Escape values on output (`esc_attr`, `esc_html`, etc.).
+

package/skills/wp-plugin-development/references/structure.md

@@ -0,0 +1,16 @@
+# Plugin structure and loading
+
+Use this file when introducing or refactoring a plugin architecture.
+
+## Core concepts
+
+- Main plugin file contains the plugin header and bootstraps the plugin.
+- Prefer predictable init:
+  - minimal boot file
+  - a loader/class that registers hooks
+  - admin-only code behind admin hooks
+
+Upstream reference:
+
+- https://developer.wordpress.org/plugins/plugin-basics/
+

package/skills/wp-plugin-development/scripts/detect_plugins.mjs

@@ -0,0 +1,122 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_IGNORES = new Set([
+  ".git",
+  "node_modules",
+  "vendor",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".turbo",
+]);
+
+function statSafe(p) {
+  try {
+    return fs.statSync(p);
+  } catch {
+    return null;
+  }
+}
+
+function readFileSafe(p, maxBytes = 128 * 1024) {
+  try {
+    const buf = fs.readFileSync(p);
+    if (buf.byteLength > maxBytes) return buf.subarray(0, maxBytes).toString("utf8");
+    return buf.toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+function findFilesRecursive(repoRoot, predicate, { maxFiles = 6000, maxDepth = 10 } = {}) {
+  const results = [];
+  const queue = [{ dir: repoRoot, depth: 0 }];
+  let visited = 0;
+
+  while (queue.length > 0) {
+    const { dir, depth } = queue.shift();
+    if (depth > maxDepth) continue;
+
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const ent of entries) {
+      const fullPath = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        if (DEFAULT_IGNORES.has(ent.name)) continue;
+        queue.push({ dir: fullPath, depth: depth + 1 });
+        continue;
+      }
+      if (!ent.isFile()) continue;
+
+      visited += 1;
+      if (visited > maxFiles) return { results, truncated: true };
+      if (predicate(fullPath)) results.push(fullPath);
+    }
+  }
+
+  return { results, truncated: false };
+}
+
+function parsePluginHeader(contents) {
+  // WordPress reads plugin headers from the top of the file. We only need key fields.
+  const header = {};
+  const pairs = [
+    ["Plugin Name", "name"],
+    ["Plugin URI", "uri"],
+    ["Description", "description"],
+    ["Version", "version"],
+    ["Author", "author"],
+    ["Author URI", "authorUri"],
+    ["Text Domain", "textDomain"],
+    ["Domain Path", "domainPath"],
+  ];
+  for (const [label, key] of pairs) {
+    const m = contents.match(new RegExp(`^\\s*${label}:\\s*(.+)\\s*$`, "im"));
+    if (m) header[key] = m[1].trim();
+  }
+  if (!header.name) return null;
+  return header;
+}
+
+function main() {
+  const repoRoot = process.cwd();
+
+  const { results: phpFiles, truncated } = findFilesRecursive(repoRoot, (p) => p.toLowerCase().endsWith(".php"), {
+    maxFiles: 5000,
+    maxDepth: 10,
+  });
+
+  const plugins = [];
+
+  for (const phpPath of phpFiles) {
+    const txt = readFileSafe(phpPath);
+    if (!txt) continue;
+    if (!/Plugin Name:/i.test(txt)) continue;
+    const header = parsePluginHeader(txt);
+    if (!header) continue;
+    plugins.push({
+      pluginFile: path.relative(repoRoot, phpPath),
+      ...header,
+    });
+  }
+
+  const report = {
+    tool: { name: "detect_plugins", version: "0.1.0" },
+    repoRoot,
+    truncated,
+    count: plugins.length,
+    plugins,
+  };
+
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+main();
+

package/skills/wp-project-triage/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: wp-project-triage
+description: "Use when you need a deterministic inspection of a WordPress repository (plugin/theme/block theme/WP core/Gutenberg/full site) including tooling/tests/version hints, and a structured JSON report to guide workflows and guardrails."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+---
+
+# WP Project Triage
+
+## When to use
+
+Use this skill to quickly understand what kind of WordPress repo you’re in and what commands/conventions to follow before making changes.
+
+## Inputs required
+
+- Repo root (current working directory).
+
+## Procedure
+
+1. Run the detector (prints JSON to stdout):
+   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
+2. If you need the exact output contract, read:
+   - `skills/wp-project-triage/references/triage.schema.json`
+3. Use the report to select workflow guardrails:
+   - project kind(s)
+   - PHP/Node tooling present
+   - tests present
+   - version hints and sources
+4. If the report is missing signals you need, update the detector rather than guessing.
+
+## Verification
+
+- The JSON should parse and include: `project.kind`, `signals`, and `tooling`.
+- Re-run after changes that affect structure/tooling (adding `theme.json`, `block.json`, build config).
+
+## Failure modes / debugging
+
+- If it reports `unknown`, check whether the repo root is correct.
+- If scanning is slow, add/extend ignore directories in the script.

package/skills/wp-project-triage/references/triage.schema.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentskills.local/wp-project-triage/triage.schema.json",
+  "title": "WP Project Triage Report",
+  "type": "object",
+  "required": ["tool", "project", "signals", "tooling"],
+  "properties": {
+    "tool": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "type": "string", "const": "detect_wp_project" },
+        "version": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "project": {
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "unknown",
+              "wp-plugin",
+              "wp-mu-plugin",
+              "wp-theme",
+              "wp-block-theme",
+              "wp-block-plugin",
+              "wp-site",
+              "wp-core",
+              "gutenberg"
+            ]
+          }
+        },
+        "primary": { "type": "string" },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    },
+    "signals": {
+      "type": "object",
+      "required": ["paths"],
+      "properties": {
+        "paths": {
+          "type": "object",
+          "properties": {
+            "repoRoot": { "type": "string" },
+            "wpContent": { "type": "string" },
+            "pluginsDir": { "type": "string" },
+            "themesDir": { "type": "string" }
+          },
+          "additionalProperties": true
+        }
+        ,
+        "usesInteractivityApi": { "type": "boolean" },
+        "usesAbilitiesApi": { "type": "boolean" },
+        "usesInnerBlocks": { "type": "boolean" },
+        "usesWpCli": { "type": "boolean" },
+        "performanceHints": { "type": "object", "additionalProperties": true },
+        "interactivityHints": { "type": "object", "additionalProperties": true },
+        "abilitiesHints": { "type": "object", "additionalProperties": true },
+        "innerBlocksHints": { "type": "object", "additionalProperties": true },
+        "wpCliHints": { "type": "object", "additionalProperties": true }
+      },
+      "additionalProperties": true
+    },
+    "tooling": {
+      "type": "object",
+      "required": ["php", "node", "tests"],
+      "properties": {
+        "php": {
+          "type": "object",
+          "properties": {
+            "hasComposerJson": { "type": "boolean" },
+            "hasVendorDir": { "type": "boolean" },
+            "phpunitXml": { "type": "array", "items": { "type": "string" } }
+          },
+          "additionalProperties": true
+        },
+        "node": {
+          "type": "object",
+          "properties": {
+            "hasPackageJson": { "type": "boolean" },
+            "packageManager": { "type": ["string", "null"], "enum": ["npm", "yarn", "pnpm", "bun", null] },
+            "usesWordpressScripts": { "type": "boolean" }
+          },
+          "additionalProperties": true
+        },
+        "tests": {
+          "type": "object",
+          "properties": {
+            "hasPhpUnit": { "type": "boolean" },
+            "hasWpEnv": { "type": "boolean" },
+            "hasPlaywright": { "type": "boolean" },
+            "hasJest": { "type": "boolean" }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "versions": {
+      "type": "object",
+      "properties": {
+        "wordpress": {
+          "type": "object",
+          "properties": {
+            "core": {
+              "type": "object",
+              "properties": {
+                "value": { "type": ["string", "null"] },
+                "source": { "type": ["string", "null"] }
+              },
+              "additionalProperties": true
+            }
+          },
+          "additionalProperties": true
+        },
+        "gutenberg": {
+          "type": "object",
+          "properties": {
+            "value": { "type": ["string", "null"] },
+            "source": { "type": ["string", "null"] }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "recommendations": {
+      "type": "object",
+      "properties": {
+        "commands": { "type": "array", "items": { "type": "string" } },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}