Install the SEO skill that teaches agents how to use reports

The seo skill is a focused instruction file for an agent. It is a router. It explains the discover, describe, run flow, names the report ids for common jobs, and states the evidence rules that apply to every report. It does not memorise each report or contain a second report implementation. It teaches the agent to call the SEO CLI.

There is one skill. Per-report depth, when to use a report, when to avoid it, its schema, the order to read its output, what its evidence cannot support, and one verification step, is fetched at runtime with describe. This progressive disclosure keeps the skill small and always in sync with the report registry.

Install the skill with the standard installer

Install the skill with the command used across the agent skills ecosystem:

npx skills add iannuttall/seo

The installer handles the supported agent destinations. The repository remains the skill source, while report execution comes from the local seo package.

For the recommended setup, install both parts:

npm i -g seo
npx skills add iannuttall/seo

Inspect the copy inside the SEO package

The published package includes the same skill file so the CLI, MCP server, and release checks can inspect it locally:

seo skill list
seo skill path seo
seo skill path

Fetch per-report depth at runtime

seo reports describe quick-wins --json returns the report’s schema plus its depth: the order to read its output, what its evidence cannot support, one verification step, and related report ids. The skill points the agent at this call so it always reads the current guidance for the exact report it runs, rather than a copy that can drift.

The describe response is where the agent learns why positions 4 to 10 are a useful review set, why CTR should be compared in context, and why the retained rows are not the whole Search Console universe. The skill teaches the agent to:

• discover ids, describe one report, then run it;
• start with compact output and request a smaller follow-up;
• keep observations separate from heuristics and actions;
• inspect date ranges, row caps, partial states, and caveats;
• propose a bounded fix with a verification step;
• avoid traffic, ranking, indexation, and AI citation promises.

That last point matters. A tool can find a title conflict or an underperforming query. It cannot promise what a search system will do after the edit.

Use the skill and MCP together

The local MCP server gives an agent three compact tools for report discovery and execution. The skill tells the agent which report fits the request and how to interpret the result.

Without MCP, the skill calls the same catalog:

seo reports list --json
seo reports describe quick-wins --json
seo reports run quick-wins --params '{"site":"sc-domain:example.com"}' --json

Both routes share the same report registry and core analysis.

Discover the canonical skill from the site

Compatible tooling can read the machine-readable SEO skill index. The entry points to the canonical SKILL.md file and includes a SHA-256 digest for content verification.

The index is useful for discovery. The seo npm package remains the runtime an agent needs to execute reports locally.

Update the installed copy deliberately

The skill is a copied file, so it does not update itself when the repository changes. Review local edits before running the standard installer again:

npx skills add iannuttall/seo

Project-specific instructions may be worth keeping. A blind overwrite is a poor update strategy when someone has taught the skill about a release process, CMS, or definition used only by that project.

The agent workflow guide covers report selection and evidence handling after installation.