playbooks

home / skills / automattic / agent-skills / wp-project-triage

wp-project-triage skill

/skills/wp-project-triage

This skill quickly detects WordPress project type from the repository and outputs a structured JSON report to guide workflows.

npx playbooks add skill automattic/agent-skills --skill wp-project-triage

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.5 KB
---
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.

Overview

This skill performs a deterministic inspection of a WordPress repository and emits a structured JSON report to guide safe workflows and automation. It detects project kind (plugin, theme, block theme, WP core, Gutenberg, full site), tooling, tests, and version hints so agents and developers can choose appropriate guardrails before making changes.

How this skill works

Run the detector from the repository root to produce a JSON report describing project.kind, discovered signals, and tooling. The detector scans common WordPress indicators (file names, manifests, build configs, test folders, PHP/Node files) and synthesizes version hints and runnable commands. If signals are missing, update the detector rather than guessing.

When to use it

  • Before automated edits or PRs to determine correct workflows and constraints
  • When onboarding to an unknown WordPress repo to quickly assess structure and tooling
  • To decide whether to run PHP or Node tests and which commands to invoke
  • When creating CI jobs that must adapt to plugin vs theme vs block theme layouts
  • To capture version hints for compatibility checks and release automation

Best practices

  • Run the detector from the project root to avoid false unknown results
  • Re-run after adding or changing build config or manifest files (theme.json, package.json, etc.)
  • Treat the JSON report as authoritative for automation decisions; extend the detector if you need new signals
  • Add ignore rules in the script to speed scanning on large repos
  • Verify that the output contains project.kind, signals, and tooling before trusting downstream actions

Example use cases

  • A CI pipeline selects test steps dynamically based on detected tooling (PHPUnit vs Jest)
  • An agent decides whether to modify theme.json or plugin PHP based on detected project kind
  • Release tooling extracts version hints to build accurate changelogs and compatibility metadata
  • A developer triages an unknown repo to determine whether Gutenberg or core patches are needed
  • Automation prevents unsafe edits by enforcing guardrails derived from the report

FAQ

What do I do if the report says unknown?

Confirm you ran the detector from the repo root and then add detection for missing indicators if the layout is custom.

How do I ensure the detector is fast on large repos?

Add or extend ignore directories inside the script so scanning skips large vendor or node_modules trees.