Reading your audit with an AI agent
Search & Social Appearance Audit has an agent interface. An AI agent working on your site, such as Claude, can read what each scan found, page by page, in the same words the Dashboard uses. It can also read and change your settings, the pages left out of scans and the issues you ignore, and save them as one file to apply again later. It works through two doors WordPress already has: WP-CLI, and on WordPress 6.9 or later the Abilities API.
The interface is part of the plugin. Nothing on your pages or your screens changes until an agent applies a change.
What an agent can and cannot do
| An agent can | An agent cannot |
|---|---|
| Read every finding with its page, severity, area, the label you see on the Dashboard and its evidence | Edit a page, its title or its meta tags |
| Read one page's stored values and its search and social previews | Change the log level, how long log entries are kept or the Share settings usage switch |
| Read the site-wide checks: search visibility, robots.txt, AI crawler access, the favicon | Overwrite a change you made in the admin since its file was saved, unless told to |
| Change settings, exclude pages, ignore issues | Remove an excluded page or an ignored issue that its file leaves out, unless told to |
| Scan one page or a few pages | Scan every page at once without being told yes |
What to do about a finding is your decision. The interface tells the agent what each finding means. It never tells the agent what to change.
One page's findings
An agent can narrow the finding list to one page. A post or a page is named
by its path, such as wp ssaa finding list --page=/about/. An archive page
or the Site row is named by its path or its address with page_url, such as
wp ssaa finding list --page-url=/category/news/. Until 1.10.0 that filter
was called url. WP-CLI keeps --url for itself, so the filter never
reached the plugin. The old name is now refused.
Scans run only when asked
Applying settings, exclusions or ignores never starts a scan. A change that
shows in findings only after the next scan says so in the agent's report.
An agent can scan one page or a few (wp ssaa scan run /about/). A scan of
every page replaces every stored result, so it is refused until the agent
says yes (wp ssaa scan run --all --yes).
Who may use it
Every ability and command needs the capability ssaa_agent. The plugin
gives it to administrators, and to the shared plugupp_agent role when your
site has one.
The site file
The file holds your settings, the pages left out of scans and the issues
you ignore. Pages are named by their address, such as /about/, so the file
works on another copy of the same site. It never holds the log level, how
long log entries are kept or the Share settings usage switch.
wp ssaa site export --file=audit.json
wp ssaa site diff --file=audit.json
wp ssaa site apply --file=audit.json --dry-run
wp ssaa site apply --file=audit.json
A second apply of the same file reports every item unchanged and writes
nothing. A setting the file leaves out keeps its value. An excluded page or
an ignored issue the file leaves out stays as it is, unless the agent passes
--prune. A file the plugin exported says prune itself, because it holds
the whole list.
The agent sees only what your site has. A setting your site does not have is refused with its name, such as "enhanced_scan is not a setting on this site." The agent's schema lists everything your site does have.
With a paid plan the file also holds your exclusion rules and saved rule
sets. Report recipients and the logins of flagged authors are personal data,
so the agent sees them only when it asks for them (--with-personal-data).
Changes you make in the admin
When you save the Settings screen or the Logs tab, ignore or un-ignore an
issue, exclude or include a page, or save your exclusion rules, the plugin
records that you edited it. If you did that after the agent's file was
saved, the agent's next apply is refused, so your change is not lost. The
agent can save the file again and carry your change over, or apply with
--force to replace it.
Which pages say more
- Reviewing your results - the findings and what they mean.
- Excluding content from the audit - exclusions and rules.
- AI readiness - the site-wide AI crawler checks.