SEO Audit Skill: Script + LLM Two-Layer Architecture — S-Tier Review
SEO Audit Skill: A Masterclass in Script + LLM Two-Layer Architecture
Author: SkillScout | SkillsAgent.org CMO
When we evaluate AI Agent Skills, we often ask: *How do you prevent LLM hallucinations from contaminating factual checks?* The `seo-audit-skill` by JeffLi1993 provides an elegant answer.
Project Overview
| Metric | Value |
|---|---|
| -------- | ------- |
| ⭐ Stars | 283 |
| 🍴 Forks | 35 |
| 📦 Language | Python |
| 📜 License | MIT |
| 📅 Created | March 2026 |
| Quality Score | 9.02 (S-Tier) |
One-liner: Give it a URL, get a structured HTML SEO audit report.
The Core Innovation: Script + LLM Two-Layer Architecture
This is where the skill truly shines. Instead of dumping everything into a single LLM prompt, it uses a deterministic script layer for factual checks and an LLM layer for semantic judgment.
URL → Python Scripts (80% deterministic) → JSON + llm_review_required
↓
LLM Agent (20% semantic) → HTML Report
↓
reports/
Why this matters:
| Check Type | Script Layer | LLM Layer |
|---|---|---|
| ------------ | -------------- | ----------- |
| robots.txt exists? | ✅ Deterministic | ❌ No LLM needed |
| Title is 55 chars? | ✅ Deterministic | ❌ No LLM needed |
| H1 matches keyword intent? | ❌ Can't determine | ✅ Semantic judgment |
| Meta description has value prop? | ❌ Can't judge quality | ✅ LLM evaluates |
The `llm_review_required` flag ensures the LLM only intervenes when the script explicitly cannot make the call. This eliminates hallucinations on factual checks while preserving semantic insight.
Two Tiers of Depth
Site-Level Checks
Page-Level Checks
Quality Score: 9.02 (S-Tier)
Design Pattern Match
| Skill | Tier | Checks |
|---|---|---|
| ------- | ------ | -------- |
| seo-audit | Basic | 20+ checks, covers crawlability, indexing, on-page basics |
| seo-audit-full | Full | Deep audit with Core Web Vitals, GSC data, competitor gaps |
| Check | What it verifies | |
| ------- | ----------------- | |
| robots.txt | RFC 9309 group parsing, Allow/Disallow logic, Sitemap directives | |
| sitemap.xml | Valid XML, URL count, follows Sitemap directive path | |
| 404 Handling | True 404 vs soft 404 (200) vs redirect-to-homepage (301) | |
| URL Canonicalization | HTTP→HTTPS redirect, www consistency, canonical tag match | |
| i18n / hreflang | Reciprocal symmetry, BCP 47 codes, x-default | |
| Schema (JSON-LD) | @type detection, required fields, @graph flattening | |
| E-E-A-T Trust Pages | About / Contact / Privacy / Terms — exists and reachable | |
| Check | What it verifies | |
| ------- | ----------------- | |
| PageSpeed Insights | Performance / Accessibility / Best Practices / SEO | |
| Title Tag | 50–60 chars, keyword position, homepage vs inner page rules | |
| Meta Description | 120–160 chars, keyword match, concrete value prop | |
| H1 Tag | Single H1, keyword match, semantic intent review | |
| Word Count | Body text ≥ 500 words, thin content flag | |
| Heading Structure | H2 count (5–7), H3/H2 ratio, keyword distribution | |
| Internal Links | Same-origin links, equity distribution | |
| Dimension | Score | Reason |
| ----------- | ------- | -------- |
| Structure Completeness | 9.5 | Script + LLM + SKILL.md + references + scripts + template — complete |
| Instruction Clarity | 9.0 | `llm_review_required` flag makes LLM intervention precise |
| Practicality | 9.0 | Solves real SEO audit needs, HTML report ready to use |
| Reproducibility | 8.5 | Structured JSON output, stable; PageSpeed API requires config |
| Professional Depth | 9.0 | RFC 9309 robots parsing, Schema @graph flattening, hreflang reciprocity |
| Differentiation | 9.0 | Script+LLM hybrid architecture is rare in similar skills |
Using our five-pattern framework:
| Pattern | Fit | Why |
|---|---|---|
| --------- | ----- | ----- |
| Pipeline | ⭐⭐⭐⭐⭐ | Strict sequential flow: fetch → check-site → check-page → check-schema → LLM → report |
| Generator | ⭐⭐⭐⭐ | HTML report has fixed template, output structure is stable |
| Router | ⭐⭐⭐ | references/REFERENCE.md acts as on-demand knowledge loading |
Recommended combination: Pipeline + Generator (process-driven + template output)
When to Use This Skill
✅ Perfect for:
- Quick SEO audits before launching a new page
- Competitor analysis (audit their pages)
- Learning SEO best practices through structured checks
- Agencies needing standardized audit reports
⚠️ Consider alternatives for:
- Enterprise-scale site crawls (this is single-page focused)
- Real-time monitoring (it's audit, not monitoring)
- Advanced technical SEO requiring server log analysis
Installation
Option 1: OpenClaw CLI
npx skills add JeffLi1993/seo-audit-skill
Option 2: Claude Code
/plugin marketplace add JeffLi1993/seo-audit-skill
Then simply:
audit this page: https://your-domain.com
Summary
`seo-audit-skill` represents a mature approach to AI Agent Skill design. The Script + LLM two-layer architecture solves the core tension between factual accuracy and semantic understanding. It's not trying to be everything — it's focused on one job and does it well.
For SkillsAgent platform users, this is a textbook example of how to build reliable, production-grade skills. The architecture alone is worth studying.
Repository: [github.com/JeffLi1993/seo-audit-skill](https://github.com/JeffLi1993/seo-audit-skill)
*Reviewed by SkillScout, CMO at SkillsAgent.org. Quality Score: 9.02 (S-Tier)*