Key Takeaways
- A “skill” is not a prompt. It's a packaged, validated, reusable agent capability — instructions, tools, memory, templates, and a review layer — that runs consistently across runs.
- Most failures aren't model failures; they're architecture failures. Drift on ambiguous input, fabricated findings, and output-format inconsistency all trace to missing scaffolding, not to the LLM itself.
- A useful mental model is four layers: one-off prompts → reusable skill specs → multi-step workflows → autonomous agents. Time savings typically show up at layer two and three, not layer four.
- Build the reviewer first. Without a review/validation layer, you can't measure quality, and the rest of the architecture has nothing to optimize against.
- The skills that survive in production solve one narrowly defined task, not “do my SEO.”
What is a “skill” — and what isn't it?
The word skill has been doing too much work in AI tooling for the last 18 months. Almost every vendor uses it slightly differently, and the loosest version — “a prompt template” — is the one that causes most of the production failures we see. Itay Malinski's recent piece in Search Engine Land on building SEO agent skills that actually work takes the question seriously and lands on a usable definition: a skill is “a workspace,” not a string. Concretely, it contains an instruction file, a personality/quality-standard file, executable scripts or tools, reference documentation, an execution memory log, and an output template.
A single prompt, in his framing, is “a coin flip.” The skill turns the coin flip into a process. The difference matters because it's where the production reliability comes from. Malinski reports building “10+ SEO agent skills in 34 days,” of which “six worked on the first try” — which sounds high until you read about the other four and what it took to fix them.
For Button Block, the distinction is practical. We've shipped a number of agent-driven workflows for clients — paid search, content briefing, audit pipelines — and the recurring lesson is that the prompt is rarely the bottleneck. The bottleneck is the surrounding scaffolding. Our companion post on Claude Skills for PPC walked through the paid-search side. This post extends the architecture pattern to SEO, where the failure modes are different and the validation layer matters even more.
Two things up front. First, “skill” here means specifically the kind of packaged agent capability described in the Anthropic Skills documentation and equivalent platforms — not a vague “AI ability.” Second, this post deliberately avoids performance metrics. Anyone telling you their SEO agent “saves 70% of audit time” is reporting a specific situation, not a portable benchmark. We'll talk about where the time savings actually show up qualitatively, and where they don't.
The four architectural layers
Most SEO teams adopting AI tooling jump from layer 1 to layer 4 — from a one-off ChatGPT prompt to “let's build an autonomous SEO agent.” That gap is where projects die. The four-layer ladder is more boring and more reliable.
Layer 1: One-off prompts. Free-form chat with an LLM, no scaffolding. Useful for exploration. Useless for repeatable work. Output drifts run-to-run; nothing is versioned; quality depends entirely on the operator's prompt-engineering instinct that day.
Layer 2: Reusable skill specs. A packaged capability: instruction file, output template, tools the agent is allowed to call, validation rules. The skill answers a narrowly defined question — audit this URL for on-page SEO issues against our criteria — and returns a structured output the rest of the system can use. Same input, same shape of output.
Layer 3: Multi-step workflows. Multiple skills chained together with orchestration logic. A workflow might run a crawler skill, a structure-extraction skill, an information-gain analysis skill, and a reporting skill in sequence, with branching based on what the earlier steps found. Tools like n8n, Airflow, or Anthropic's workflow primitives sit at this layer; we cover one orchestration pattern in our n8n workflow automation guide.
Layer 4: Autonomous agents. A system that decides on its own which workflows to run, when, and against which inputs. This is where most of the marketing claims sit. In our experience, the reliability falls off a cliff at this layer for SEO work specifically — partly because SEO is full of ambiguous inputs and partly because the cost of being wrong is concrete (Google can demote a real site for hallucinated structured data or broken canonicals).
The honest version: most teams get more value from layer 2 and 3 than from layer 4. Skill specs make individual tasks consistent. Workflows make pipelines repeatable. Autonomous decision-making sounds impressive in a demo and rarely survives the third client engagement. Lisane Andrade's semantic programmatic SEO blueprint hits the same point from the content side: the value comes from “an infrastructure that answers thousands of specific search intents” — infrastructure, not autonomy.
A worked example: an on-page SEO audit skill
Picking one task and decomposing it makes the architecture concrete. We'll use on-page SEO auditing — a task that's well-bounded, repeatable, and has a clear definition of “good output.” It's also one of the example tasks Malinski works through in detail.
The audit goal: given a URL, return a list of on-page issues that a developer can ticket and fix, with each finding evidence-backed, severity-rated, and specific enough that no follow-up question is needed. Here's how the four layers map to that task.
Layer 1: The bad version
Drop the URL into ChatGPT and say “Audit this page for SEO issues.” You'll get back a plausible-looking list. Some of the findings will be real. Some will be hallucinated (the page has H1 issues that aren't actually there). The format will vary every time you run it. The severity ratings will be inconsistent. The output won't include enough detail for a developer to act on without follow-up.
This is what Malinski refers to when he describes “false positives with total confidence.” In his sandbox testing, an early version of the same skill returned “20 findings. Eight didn't exist.”
Layer 2: The skill spec
The skill spec for on-page auditing looks like a directory, not a prompt. At minimum:
| File | Purpose |
|---|---|
instructions.md | Step-by-step methodology — what to check, in what order, against which criteria |
quality_standards.md | What “good” looks like; specificity requirements for findings |
tools/crawler.js | The actual crawler (handles JS rendering, rate limits, user-agent headers) |
references/criteria.md | Severity definitions, common gotchas, edge cases |
templates/output.json | Strict output format with locked field names |
memory/runs.log | Execution history; what previous runs found and missed |
The crawler tool is the part most early implementations get wrong. Malinski's piece walks through five iterations of his own crawler: V1 used raw curl requests (“blocked everywhere”); V2 used Playwright but “crashed on large sites” (no rate limiting); V3 added throttling but “failed on sites that require JavaScript rendering”; V4 added browser rendering but had inconsistent output; V5 added templates and memory and was finally “stable, consistent, reliable.” If you skip the crawler engineering and pipe raw HTTP responses into the LLM, you'll discover what every modern CDN does to bare requests.
The skill should also have an explicit tool whitelist. Malinski names this as a specific failure mode: “The research agent tried to call an API we never set up.” Skills given unrestricted tool access tend to invent integrations. Locking the toolbox is part of the skill, not separate from it.
Layer 3: The audit workflow
An audit isn't a single step. A typical SEO audit workflow looks like:
- Crawler skill → extracts structured page data
- On-page audit skill → identifies issues against criteria
- Reviewer skill → checks each finding against quality standards (does the evidence support the severity? is this a real issue or a false positive?)
- Reporter skill → packages the surviving findings into a developer-ready ticket format
The reviewer skill is the one Malinski calls out as the most underweighted: “Build the reviewer first. Without a review layer, you have no way to measure quality.” We've found the same pattern in our own work — without an explicit review step, you can't even tell whether you're getting better.
This is also where the Model Context Protocol becomes useful in practice. MCP lets an agent call defined tools — your crawler, your audit checker, your reporter — through a stable interface rather than improvising. Our MCP servers and AI tool integration piece walks through the integration layer that makes the workflow possible.
Layer 4: Autonomous what?
For audits, layer 4 would mean: “the agent decides which URLs to audit, when, against which criteria, and how to interpret the results.” This is the layer we usually advise clients not to ship in production yet. Auditing is full of context the model doesn't have — we already filed a ticket for that issue last quarter; this site is mid-redesign; the canonical setup looks wrong but is intentional. Without that context, layer 4 generates a lot of noise.
Where agent skills fail (in detail)
This section is the one that should change how you scope your first skill. Naming the failure modes ahead of time saves the three weeks of debugging that come from discovering each one in production.
Failure mode 1: Drift on ambiguous inputs. The same skill, given two slightly different inputs, produces two structurally different outputs. Malinski names this directly: “If your agent output looks different every run, you need a template file, not a better prompt. I cannot stress this enough.” The fix isn't a longer prompt. It's a strict output template with locked field names and a schema check on the output before downstream systems consume it.
Failure mode 2: Confident hallucinations. An audit reports “missing H1 tag on /pricing” when the H1 is in fact present. A research agent reports “12 backlinks from a domain” when the actual count is zero. Malinski's vivid example: “I asked the research agent to find law firms and count their attorneys. It made every number up.” The fix is the review layer — every claim needs to be verifiable against the source data the agent actually pulled, not against what it remembers. We covered the broader pattern in our piece on AI agents beyond chatbots.
Failure mode 3: Brittleness when site structure changes. A skill that depended on specific HTML selectors or sitemap structures breaks the moment the target site ships a redesign. Skills written against well-named entities (Schema.org types, canonical link relationships) survive better than skills written against CSS classes. The Schema.org Article documentation and Google's structured data reference are usefully stable surfaces to build against.
Failure mode 4: Validation cost exceeds the gain. A skill that takes 30 seconds to run and 90 seconds to validate is rarely worth it, even when both work. The break-even is harsh for one-off tasks and only improves at scale. We've seen client teams build elegant audit skills that, in honest accounting, cost more analyst-time per audit than the human version they replaced. The first question we ask before building a skill is: how many times will this run before it pays back the setup cost?
Failure mode 5: Knowledge that doesn't transfer between agents. Skills typically don't share lessons. If you learn that a particular CDN blocks your crawler unless you set a specific user-agent string, that knowledge has to be explicitly written into every skill that touches that CDN. Malinski: “A brand new agent hit the exact same problem” the previous agent had already solved. The fix is a shared references directory — gotchas, edge cases, environment notes — that every skill in the workspace can read.
What changes when you build at this level
A few things shift once a team has its first three skills running reliably.
The role of the SEO practitioner changes from doing the work to encoding the methodology. Andrade's semantic programmatic SEO blueprint describes the same shift in the content world: “SEO team transitioned from manual tasks to strategic oversight.” The work that's left is the high-judgment work — deciding what to audit, what counts as a finding worth ticketing, what the priorities should be.
Time savings show up at layer 2 and 3, not 4. In our experience, the audit pipeline above doesn't save time on the first ten audits — the setup cost is real. Around audit fifteen, the curve crosses. By audit fifty, the per-audit cost is a fraction of what it was, and the outputs are more consistent than what a rotating set of analysts would produce.
You start hitting the visibility limits of the platforms you're querying. A crawler skill that hits 200 pages in parallel will get rate-limited. Skills that read Google Search Console data hit GSC's API quotas. This isn't a model problem; it's a system-design problem, and it tends to show up around the fourth or fifth production skill.
The reviewer becomes the most important file in the workspace. Malinski says it cleanly: “The reviewer defines quality. Build it first. Everything else gets measured against it.” We've watched teams rewrite the reviewer four times before they touched the audit logic. That's usually the right ratio.
When should you skip the agent layer entirely?
A discipline of building agent skills is, at minimum, asking the question should this even be an agent? before building. Several SEO tasks that vendors are now packaging as “AI agents” are better served by deterministic scripts:
- Canonical tag audits — a Python script with
requestsandlxmldoes this in 30 lines and never hallucinates. - Robots.txt validation — pure parsing problem; no LLM needed.
- Internal link inventory — a crawler plus a graph database is more reliable than an LLM-driven version.
- Schema validation — Google's Rich Results Test and a script wrapper covers the vast majority of cases.
Where the LLM earns its keep is the interpretive layer: deciding which finding is most important, drafting the developer-readable explanation, prioritizing across categories, or comparing the page against a competitor's. We covered the framework angle on this in our AI-driven SEO frameworks for small business piece. The pattern: deterministic data gathering at the bottom, LLM-driven interpretation and reporting at the top.
Anthropic's recent announcements around Skills push roughly in this direction — packaged capabilities you compose, rather than autonomous agents that do everything. The same architectural pull shows up in Google's content playbook for agents, where the structure-for-machines mindset gets defined more formally on the publishing side.
A minimum viable skill: what to build first
If you're a small SEO team or a single-shop technical SEO, the first skill we recommend building is not a crawler and not an audit. It's a findings reviewer. Given a list of findings produced by any tool — a paid SEO platform, a script, another agent — the reviewer checks each finding against your team's quality criteria and rejects the ones that don't pass.
The reviewer is the right first skill for three reasons. First, it has a clean input (a structured list) and a clean output (a filtered structured list). Second, it forces you to write down your quality criteria, which is the work most teams skip. Third, once you have it, every other skill you build can be measured against it.
The setup is small enough to fit in a single afternoon: an instructions file describing what “good” means, a criteria reference, and a strict output template with locked field names. The first ten findings it processes will reveal more about your team's actual quality standards than a quarter of meetings would.
From there, the natural next step is a crawler — but only if the data sources you already have aren't enough. In our experience, most SEO teams already have more data than they're using; the bottleneck is interpretation, not collection.
What we don't claim
We don't claim a measurable productivity gain. The honest answer is that gains depend on what you're replacing, how often the skill runs, how stable your target sites are, and how good your reviewer is. We've shipped skills that saved analyst-hours; we've also shipped skills that, in honest accounting, cost more to maintain than the human version they replaced. The architecture above is the pattern that gave us the highest hit rate, not a guarantee.
We don't claim that autonomous agents will replace SEO teams in the near term. The layer-4 work is interesting and useful in narrow contexts; the broad version is mostly demo material.
We don't claim that any specific vendor's skill platform is the right one. Anthropic, OpenAI, and various open-source frameworks all have viable implementations. The architecture is portable; the vendor choice is downstream.
Ready to build something specific?
Our AI Solutions service builds custom skill-based workflows for clients across SEO, content, paid media, and reporting. We typically start with a single narrowly defined task — an audit, a brief generator, a reporting compilation — build the reviewer first, and ship the surrounding scaffolding once the quality criteria are stable. The engagements that work are the ones with a clear definition of done; the ones that struggle are the ones that start with “use AI to improve our SEO.”
Frequently Asked Questions
- What's the difference between an AI prompt and an agent skill?
- A prompt is a single instruction sent to a model, with output that varies run-to-run. A skill is a packaged workspace — instructions, tools, references, output templates, and an execution log — that turns the same input into the same shape of output every time. Itay Malinski's Search Engine Land piece frames the difference as "a coin flip" vs. "a workspace," which we've found accurate in practice.
- Which SEO tasks are good candidates for agent skills?
- Tasks that are well-bounded, repeatable, and have a clear definition of "good output." On-page audits, internal-link suggestion, content briefing, schema markup generation, and findings review all fit. Tasks that are exploratory ("figure out why traffic dropped"), highly context-dependent, or have ambiguous success criteria are usually worse fits — at least for layer 2 skills.
- Do I need Claude Skills specifically, or can I use other platforms?
- The architecture is portable. Anthropic's Skills documentation describes one implementation; OpenAI's Assistants and various open-source frameworks (LangChain, LangGraph, AutoGen) implement similar patterns. The choice usually comes down to which model you prefer, which platform your engineering team already uses, and how strict your data-residency requirements are.
- What's the biggest mistake teams make when building their first skill?
- Skipping the reviewer. Without an explicit review/validation step, you have no way to measure whether the skill is getting better or worse over time. The Malinski piece is clear on this — "Build the reviewer first" — and in our own work it's the file we rewrite the most often. The second biggest mistake is letting the agent call any tool it wants. Lock the toolbox.
- How long before an SEO agent skill pays back its setup cost?
- In our experience, audit-style skills break even somewhere around 10–20 runs, depending on the depth of the audit and how well-engineered the crawler is. Higher-volume skills (content briefing, internal link suggestion) pay back faster. One-off skills usually don't pay back at all — if you're only going to run the skill twice, write it once by hand.
- Can autonomous SEO agents do my work for me?
- Not yet, for most production SEO use cases. The autonomous layer (layer 4 in the architecture above) sounds appealing in demos but tends to fail on the kind of contextual judgment SEO work depends on. We've found that layer 2 (skills) and layer 3 (workflows) provide most of the practical value while keeping a human in the loop on what to ship.
- Where does MCP fit into this architecture?
- The Model Context Protocol is the integration layer that lets skills call your tools — a crawler, an audit script, a reporting endpoint — through a stable interface rather than improvising HTTP calls. For SEO skills specifically, MCP servers tend to live at the boundary between the skill workspace and your existing analytics, GSC, and crawler infrastructure.
Sources & Further Reading
- Search Engine Land: searchengineland.com/build-seo-agent-skills-476252 — Itay Malinski on how to build SEO agent skills that actually work (the load-bearing piece for this post).
- Search Engine Land: searchengineland.com/semantic-programmatic-seo-blueprint-476262 — Lisane Andrade on semantic programmatic SEO.
- Anthropic: anthropic.com/news — Anthropic news and announcements on Skills and Claude updates.
- Anthropic: docs.anthropic.com/en/docs/build-with-claude — Build with Claude documentation, including Skills primitives.
- Model Context Protocol: modelcontextprotocol.io — MCP specification (the stable tool-interface layer).
- Google: search.google.com/search-console/about — Google Search Console (free SEO data source).
- Google Search Central: developers.google.com/search/docs/appearance/structured-data/article — Article structured data documentation.
- Schema.org: schema.org/Article — Schema.org Article documentation.