seo-platform-detect

The profile decides three things no module can decide on its own: which platform-conditional check ids fire, which findings are

not_applicable

because the platform owns the thing, and which fix adapter

fix

will reach for. Run it once per audit, right after the snapshot, before dispatch.

Detection is orthogonal to the vertical:

seo-vertical-detect

answers what kind of site is this, this skill answers what is it built on. Both feed one

profile.json

When to run

In the normal

/audit

and

/geo

flow you do not run this yourself:

audit.mjs

already calls the same

detect()

over the run's homepage snapshot and persists the result as

<run_dir>/profile.json

. Read that file first. Run the script directly only when you need a signal the headless pass could not use —

--path <project>

for repo/package signals,

--probe

for the WordPress plugin verdict — or when you are working outside the runner. Either way it is one run per audit, before the dispatch envelopes are built; every subagent reads the same profile.

How to run

bash

node "${CLAUDE_PLUGIN_ROOT}/scripts/detect-platform.mjs" --snapshot "<run_dir>/pages/<home-slug>.json"

Add flags when they apply, and only then:

```
--path <project>
```
when the user gave a local project (
```
--project
```
). This is the only way repo and package signals are consulted; without it, Payload is undetectable and Next.js router detection falls back to DOM markers. It is also what turns
```
capabilities.local_files
```
on, which is what makes local file fixes possible at all.
```
--probe
```
when the target is reachable and a WordPress plugin verdict matters. It requests
```
/wp-json/
```
,
```
/.well-known/ucp
```
,
```
/products.json
```
and
```
/wp-sitemap.xml
```
— four GETs, no more. The REST namespace list is the only reliable way to tell Yoast from Rank Math from AIOSEO; HTML comments name a plugin that printed a comment, not one that is active.
```
--out "<run_dir>/profile.platform.json"
```
to persist it instead of piping the stdout JSON.

Offline / fixture mode (used by the tests, and by you when there is no network):

--html <file> [--headers <json>] [--cookies <json>] [--probes <json>] [--url <u>]

Exit codes: 0 ok · 1 bad invocation or unreadable input · 2 fetch failure.

What comes back

{ version: "detect-platform/1", target, platform, framework, cms_plugins[], hosting, environment, capabilities, write_targets[], candidates, vertical_hints[], cards[], sources, notes[] }

Each of

platform

framework

cms_plugins[]

hosting

carries its own

confidence

(

high

≥ 8 with ≥ 2 signal kinds,

medium

≥ 5,

low

≥ 2) and the

signals

that produced it. A layer with less evidence than that is

null

— an unresolved platform is a result, not a gap. Report it as unresolved and let the run continue on

instructions

; never round a

low

up in prose.

Four layers are scored independently, so headless setups resolve correctly: a WordPress backend with a Next.js front end yields

platform: wordpress

and

framework: nextjs

, and

capabilities.head_owner

becomes

framework

. Follow

head_owner

whenever the cards disagree.

Merging into profile.json

<run_dir>/profile.json

is the union of this output and

seo-vertical-detect

's.

audit.mjs

writes it: it refreshes every key

detect()

owns and preserves the ones you added, so a

vertical

block already in the file survives a re-run (a

--vertical

flag overrides it). Shape:

json

{ "version": "detect-platform/1", "platform": {…}, "framework": {…}, "cms_plugins": [],
  "hosting": {…}, "environment": {…}, "capabilities": {…}, "write_targets": [],
  "candidates": {…}, "vertical_hints": [], "cards": [], "sources": {…}, "notes": [],
  "vertical": { "primary": "ecommerce", "also": [], "multilingual": false, "locales": [] } }

Pass

vertical_hints[]

seo-vertical-detect

as signals, never as verdicts — it must still cite its own evidence. Pass

environment.kind

to the scorer (

score.mjs --environment preview|staging|local

), which suppresses noindex-type severity-5 caps on a non-production host and reports them as expected instead.

Which card goes to which subagent

profile.cards[]

already lists the paths (

references/platforms/<id>.md

). Put them in every dispatch envelope as

platform_cards

, alongside the

platform

field (the absolute

profile.json

path) and a one-line summary (

"shopify (high) · theme head · staging theme available · environment production"

), with these two instructions verbatim:

emit the card's §10 check ids when the rule matches;
card §4 items ⇒
not_applicable
naming the owner in
```
evidence.observed
```
— never a silent pass, never a
```
fail
```
for something the platform will not let anyone change.

Hand out the platform card, the framework card and any plugin card together; a headless site legibly needs all three. When

capabilities.instructions_only

is true, also tell the agents that every fix they propose will be delivered as a click-path, so

fix_preview

must be human-readable prose rather than a diff.

Honesty

```
needs
```
in
```
write_targets
```
lists credential key names. Presence is checked for
```
CLAUDE_PLUGIN_OPTION_<KEY>
```
/
```
<KEY>
```
— values are never read, printed or logged.
```
ready: false
```
means "not configured", never "wrong key".
Cookie names are evidence; cookie values are never recorded.
Repo signals are absent without
```
--path
```
, probe signals absent without
```
--probe
```
, and the profile's
```
notes[]
```
says so. Repeat that in the report rather than presenting a partial profile as complete.
A signal marked
```
UNVERIFIED
```
in a card's §12 may support a detection verdict but must never support a write. When a fix depends on an unverified API detail, the answer is
```
needs_api
```
.

seo-platform-detect

NPX Install

Tags

SKILL.md Content

seo-platform-detect

When to run

How to run

What comes back

Merging into profile.json

Which card goes to which subagent

Honesty