wp-project-triage

Overview of wp-project-triage skill

What wp-project-triage does

The wp-project-triage skill is a fast, deterministic first-pass inspector for WordPress repositories. It identifies the likely project type, detects tooling and tests, surfaces version hints, and returns a structured report so you can choose the right workflow without guessing. If you need wp-project-triage for Workflow Automation, this is the kind of skill that helps an agent decide what to do next before it edits anything.

Who should use it

Use the wp-project-triage skill when you are dropped into a WordPress codebase and need to know whether it is a plugin, theme, block theme, site, WP core, or Gutenberg-related repo. It is especially useful for agents and maintainers who want a repeatable triage step before implementation, review, or testing.

Why it is different

The main value of wp-project-triage is not prose summary; it is decision support. It reads the repository signals, applies guardrails, and outputs a JSON report you can trust more than a generic prompt. That makes it a better fit than asking an LLM to “figure out the repo” from a few filenames.

How to Use wp-project-triage skill

Install and point it at the repo root

For wp-project-triage install, add the skill to your agent workspace with the standard skills command, then run it from the repository root so the detector can inspect the actual project layout. The skill expects a filesystem-based environment with bash and Node available; some workflows also rely on WP-CLI.

Read these files first

Start with skills/wp-project-triage/SKILL.md, then check references/triage.schema.json to understand the report shape. The repo also includes scripts/detect_wp_project.mjs, which is the key file if you want to understand how classification and signal detection work. These three files tell you more than a shallow skim of the directory tree.

Turn a vague goal into a useful prompt

A strong wp-project-triage usage prompt says what you are trying to decide, not just that you want a scan. For example: “Run wp-project-triage on this repo and tell me whether it looks like a plugin or block theme, what tooling is present, and what guardrails I should follow before changing code.” That gives the skill enough intent to produce an actionable triage report.

Use the report to choose the next workflow

After the detector runs, use the output to decide whether to inspect build config, test setup, version constraints, or content structure. If the report says unknown, treat that as a signal to check whether you are in the right root, or whether the repo needs better detection rules rather than forcing a guess. Re-run the detector after structural changes such as adding theme.json, block.json, or build tooling.

wp-project-triage skill FAQ

Is wp-project-triage only for WordPress repos?

Yes, that is the intended fit. The wp-project-triage guide is designed for WordPress project shapes such as plugins, themes, block themes, site repos, core, and Gutenberg. If you are not working in that ecosystem, a generic filesystem scan or a different repo classifier is usually a better choice.

Do I need WP-CLI to use it?

Not always. The skill can still help in a filesystem-only environment, but some downstream workflows may expect WP-CLI or WordPress-adjacent tooling. The point of wp-project-triage is to tell you what is present so you know whether those later steps are realistic.

Is this better than asking an AI to inspect the repo directly?

Usually yes for the first pass. A normal prompt can miss version hints, ignore signals, or invent structure when the tree is ambiguous. wp-project-triage gives you a repeatable install-and-run path, a defined output contract, and a narrower task: classify first, then act.

When should I not use it?

Do not use it as a substitute for code review, security auditing, or deep architecture analysis. It is a triage layer, not a full diagnosis. If you already know the exact project type and need a targeted code task, you may not need this step.

How to Improve wp-project-triage skill

Give it cleaner starting conditions

The strongest way to improve wp-project-triage results is to run it from the true repo root and avoid partial checkouts or nested working directories. If the detector is scanning the wrong folder, the report becomes less useful immediately. This matters more than elaborate prompting.

Supply context that changes the decision

If you want better wp-project-triage usage, mention the specific outcome you need: plugin vs theme classification, build-tool detection, or test readiness. That helps you judge whether the report is complete enough for your next step. A good follow-up prompt might ask for “the minimal safe edit path” instead of “summarize everything.”

Watch for the common failure modes

The main failure mode is an unknown or under-specified classification caused by missing signals, unusual repository layout, or ignored directories. Another is over-trusting the first report when the repo has generated files but weak source hints. If that happens, improve the detector inputs or extend ignore rules instead of improvising.

Iterate after the first run

Use the first report to identify gaps, then re-run wp-project-triage after adding missing hints like theme.json, block.json, test config, or version metadata. The skill works best as an iterative guardrail: detect, verify, adjust, and detect again.