opencode-skills-collection 4.0.64 → 4.0.65

package/bundled-skills/seo-aeo-content-quality-auditor/SKILL.md

@@ -1,98 +1,255 @@
 ---
 name: seo-aeo-content-quality-auditor
-description: "Audits content for SEO and AEO performance with scored reports, severity-ranked fix lists, and projected scores after fixes. Activate when the user wants to audit, review, or score content for SEO or AEO compliance."
+description: "Audits a website, codebase, page, or content set for technical SEO, search intent, AEO, conversion paths, and publishing readiness, then produces prioritised fixes that can be implemented and verified."
 risk: safe
 source: community
 date_added: "2026-04-01"
 ---
 
-# SEO-AEO Content Quality Auditor
 
-## Overview
+# Content Quality Auditor Skill
 
-Runs a dual SEO + AEO audit on any landing page or blog post. Produces an overall score, SEO score, AEO score, and readability score — each out of 100 — with severity-ranked issue lists (Critical / Warning / Polish), exact fix instructions for every issue, and projected scores after all fixes are applied.
+## Description
+Activate this skill when the user wants to audit, review, or score
+a website, codebase, URL, page, or content set for SEO and AEO performance. Trigger phrases include:
+"audit this content", "SEO review", "AEO audit", "check this page",
+"score this article", "content auditor", "what's wrong with this content",
+"review this landing page", "analyze content quality".
 
-Part of the [SEO-AEO Engine](https://github.com/mrprewsh/seo-aeo-engine).
+---
 
-## When to Use This Skill
+## Input Format
+```json
+{
+  "content": "string — paste raw content, provide a URL, or provide a project path",
+  "input_type": "text | url | website | codebase",
+  "primary_keyword": "string — the main keyword this content should rank for",
+  "secondary_keywords": ["string"],
+  "content_type": "landing-page | blog-post | pillar-page | product-page",
+  "word_count_target": "integer — expected word count, default 1500",
+  "business_context": "string — optional description of the business and conversion goal",
+  "existing_content": ["string — optional URLs or titles already published"]
+}
+```
 
-- Use when auditing a landing page or blog post before publishing
-- Use after the blog-writer or landing-page-writer skill outputs content
-- Use when diagnosing why existing content is underperforming in search
-- Use when you need a scored, actionable SEO and AEO report
+For a new project, default to a full website/codebase audit before recommending new content. If the user has not supplied target keywords, identify candidate keywords from the site and ask which ones matter before finalizing the content strategy. If the user does not know, continue with a clearly labelled fallback strategy based on observed search intent.
 
-## How It Works
+Read [references/seo-audit-checklist.md](references/seo-audit-checklist.md) for the audit dimensions, evidence rules, and audit-to-implementation loop.
 
-### Step 1: Run SEO Checks
-Verify keyword density, H1/H2/H3 structure, meta elements, word count, sentence length, and paragraph density. Flag every issue with its severity.
+---
 
-### Step 2: Run AEO Checks
-Check for TL;DR block, definition sentence, FAQ section (minimum 4 entries), bullet and numbered lists, comparison table, and extractable direct answers. Score each signal as found or missing.
+## Scoring System
 
-### Step 3: Run Readability Checks
-Check passive voice ratio, transition word presence, wall-of-text paragraphs, subheading frequency, and reading level.
+All scores are out of 100. Use these thresholds consistently:
 
-### Step 4: Score and Prioritise
-Calculate three scores out of 100. Sort all issues into Critical (fix before publishing), Important (fix soon), and Polish (optional improvements). Generate projected scores after all fixes are applied.
+| Score     | Status   | Label                        |
+|-----------|----------|------------------------------|
+| 85–100    | ✅ Pass   | Strong — minor polish needed |
+| 70–84     | ⚠️ Warn  | Acceptable — fixes recommended |
+| 50–69     | 🔶 Weak  | Needs work before publishing |
+| 0–49      | ❌ Fail   | Do not publish as-is         |
 
-## Scoring System
+---
+
+## Output Structure
+
+The skill must always produce output in this exact format:
+```markdown
+# Content Quality Audit Report
+
+## Summary
+
+| Metric              | Score     | Status  |
+|---------------------|-----------|---------|
+| Overall Score       | [X/100]   | [label] |
+| SEO Score           | [X/100]   | [label] |
+| AEO Score           | [X/100]   | [label] |
+| Readability Score   | [X/100]   | [label] |
+
+**Verdict:** [One sentence summary of the content's current state
+and the single most important fix needed.]
+
+---
+
+## SEO Report
+
+### Score: [X/100] — [Status Label]
 
-| Score | Status | Label |
-|-------|--------|-------|
-| 85–100 | ✅ Pass | Strong |
-| 70–84 | ⚠️ Warn | Acceptable |
-| 50–69 | 🔶 Weak | Needs work |
-| 0–49 | ❌ Fail | Do not publish |
+#### ✅ Passing Checks
+- [Check name]: [what was found]
+- [Check name]: [what was found]
 
-## Examples
+#### ❌ Critical Issues — Fix Before Publishing
 
-### Example: Audit Summary
-Overall Score:    84/100  ⚠️ Acceptable
-SEO Score:        88/100  ✅ Pass
-AEO Score:        74/100  ⚠️ Acceptable
-Readability:      91/100  ✅ Pass
-Verdict: Strong SEO foundation. AEO needs a TL;DR block
-and one more FAQ entry before publishing.
-🔴 Critical (fix before publishing):
+**Issue:** [Specific problem, e.g. "Primary keyword missing from H1"]
+**Severity:** Critical
+**Fix:** [Exact instruction, e.g. "Rewrite H1 to include '[keyword]'
+naturally within the first 6 words"]
+
+**Issue:** [Specific problem]
+**Severity:** Critical
+**Fix:** [Exact instruction]
+
+#### ⚠️ Warnings — Fix Soon
+
+**Issue:** [Specific problem]
+**Severity:** Medium
+**Fix:** [Exact instruction]
+
+#### Keyword Analysis
+
+| Keyword              | Found | Occurrences | Density | Target   | Status  |
+|----------------------|-------|-------------|---------|----------|---------|
+| [primary keyword]    | Yes/No| [n]         | [x.x%]  | Natural use | ✅ / ❌ |
+| [secondary keyword]  | Yes/No| [n]         | [x.x%]  | Natural use | ✅ / ❌ |
+
+#### Heading Structure
+
+| Heading | Text                        | Contains Keyword | Status  |
+|---------|-----------------------------|------------------|---------|
+| H1      | [heading text]              | Yes/No           | ✅ / ❌ |
+| H2 #1   | [heading text]              | Yes/No           | ✅ / ❌ |
+| H2 #2   | [heading text]              | Yes/No           | ✅ / ❌ |
+
+H1 count: [n] — must be exactly 1
+H2 count: [n] — recommended 4–6 for blog posts
+H3 count: [n] — should only appear inside H2 sections
+
+#### Meta Elements
+
+| Element          | Found    | Content                          | Status  |
+|------------------|----------|----------------------------------|---------|
+| Title Tag        | Yes/No   | [content or "missing"]           | ✅ / ❌ |
+| Meta Description | Yes/No   | [content or "missing"]           | ✅ / ❌ |
+| Title Length     | [n] chars| Target: 50–60 characters         | ✅ / ❌ |
+| Meta Length      | [n] chars| Target: 140–160 characters       | ✅ / ❌ |
+| Keyword in Title | Yes/No   | —                                | ✅ / ❌ |
+
+#### Word Count
+
+| Metric             | Actual     | Target               | Status  |
+|--------------------|------------|----------------------|---------|
+| Word Count         | [n] words  | [word_count_target]  | ✅ / ❌ |
+| Avg Sentence Length| [n] words  | Target: under 20     | ✅ / ❌ |
+| Avg Paragraph Length| [n] lines | Target: 3–5 lines    | ✅ / ❌ |
+
+---
 
-AEO: No TL;DR block found
-Fix: Add a 2–3 sentence direct-answer block in a
-blockquote immediately after the H1.
+## AEO Report
 
-🟡 Important (fix soon):
-2. AEO: FAQ has 3 entries — minimum is 4
-Fix: Add one more FAQ entry using a secondary keyword
-as the question.
-Projected score after fixes: 93/100 ✅
+### Score: [X/100] — [Status Label]
 
-## Best Practices
+#### ✅ Passing Checks
+- [Check name]: [what was found]
 
-- ✅ **Do:** Fix all Critical issues before publishing — they block AEO extraction
-- ✅ **Do:** Use the projected score to prioritise which fixes to make first
-- ✅ **Do:** Run the audit on both the landing page and blog post in the same session
-- ❌ **Don't:** Publish content scoring below 50/100 overall
-- ❌ **Don't:** Ignore AEO warnings — they directly affect AI engine citation probability
+#### ❌ Critical Issues — Fix Before Publishing
 
-## Common Pitfalls
+**Issue:** [Specific AEO problem,
+e.g. "No TL;DR or direct-answer block found"]
+**Severity:** Critical
+**Fix:** [Exact instruction, e.g. "Add a TL;DR block immediately
+after the H1 — 2–3 sentences that directly answer the article's
+core question. This is the block AI engines extract first."]
 
-- **Problem:** SEO score is high but AEO score is low
-  **Solution:** Traditional SEO tools miss AEO signals entirely. Run the AEO checklist separately and treat it as equally important.
+#### ⚠️ Warnings — Fix Soon
 
-- **Problem:** Fix list is long and overwhelming
-  **Solution:** Work through Critical issues only first, re-run the audit, then tackle Important issues.
+**Issue:** [Specific problem]
+**Severity:** Medium
+**Fix:** [Exact instruction]
 
-## Related Skills
+#### AEO Signal Checklist
 
-- `@seo-aeo-blog-writer` — produces the content this skill audits
-- `@seo-aeo-landing-page-writer` — produces landing pages this skill audits
-- `@seo-aeo-schema-generator` — uses audit output to determine schema priorities
+| Signal                              | Found    | Count    | Target       | Status  |
+|-------------------------------------|----------|----------|--------------|---------|
+| TL;DR / Direct Answer Block         | Yes/No   | —        | Required     | ✅ / ❌ |
+| Definition Sentence ("X is...")     | Yes/No   | [n]      | Min 1        | ✅ / ❌ |
+| FAQ Section                         | Yes/No   | [n] Qs   | Min 4        | ✅ / ❌ |
+| Numbered or Bullet Lists            | Yes/No   | [n]      | Min 2        | ✅ / ❌ |
+| Comparison Table                    | Yes/No   | [n]      | Recommended  | ✅ / ❌ |
+| Primary Keyword in First 100 Words  | Yes/No   | —        | Required     | ✅ / ❌ |
+| Concise Answers Under 50 Words      | Yes/No   | [n]      | Min 2        | ✅ / ❌ |
+| Schema Markup Detected              | Yes/No   | —        | Recommended  | ✅ / ❌ |
 
-## Additional Resources
+#### Extractability Assessment
 
-- [SEO-AEO Engine Repository](https://github.com/mrprewsh/seo-aeo-engine)
-- [Full Content Quality Auditor SKILL.md](https://github.com/mrprewsh/seo-aeo-engine/blob/main/.agent/skills/content-quality-auditor/SKILL.md)
+Rate how likely AI engines are to extract answers from this content:
+
+| Question Type               | Extractable | Confidence | Notes              |
+|-----------------------------|-------------|------------|--------------------|
+| "What is [topic]?"          | Yes/No      | High/Med/Low| [brief reason]    |
+| "How does [topic] work?"    | Yes/No      | High/Med/Low| [brief reason]    |
+| "How much does [topic] cost?"| Yes/No     | High/Med/Low| [brief reason]    |
+| "What are the benefits?"    | Yes/No      | High/Med/Low| [brief reason]    |
+
+---
+
+## Readability Report
+
+### Score: [X/100] — [Status Label]
+
+| Check                        | Result         | Target             | Status  |
+|------------------------------|----------------|--------------------|---------|
+| Passive Voice Usage          | [x%]           | Under 10%          | ✅ / ❌ |
+| Transition Words Present     | Yes/No         | Required           | ✅ / ❌ |
+| Wall-of-Text Paragraphs      | [n found]      | 0                  | ✅ / ❌ |
+| Subheading Frequency         | Every [n] words| Every 300 words    | ✅ / ❌ |
+| Reading Level                | [Grade level]  | Grade 7–9          | ✅ / ❌ |
+
+---
+
+## Prioritised Fix List
+
+Work through these in order:
+
+### 🔴 Do First (Critical — blocks publishing)
+1. [Fix instruction]
+2. [Fix instruction]
+
+### 🟡 Do Second (Important — affects ranking)
+3. [Fix instruction]
+4. [Fix instruction]
+
+### 🟢 Do Last (Polish — improves performance)
+5. [Fix instruction]
+6. [Fix instruction]
+
+---
+
+## Estimated Score After Fixes
+
+| Metric            | Current Score | Projected Score |
+|-------------------|---------------|-----------------|
+| SEO Score         | [X/100]       | [X/100]         |
+| AEO Score         | [X/100]       | [X/100]         |
+| Readability Score | [X/100]       | [X/100]         |
+| Overall Score     | [X/100]       | [X/100]         |
+```
+
+---
+
+## Execution Steps
+
+1. Detect `input_type` — inspect the project structure for a codebase, fetch a URL when allowed, or analyze supplied text.
+2. Establish the business, audience, conversion goal, existing content, and known target keywords. If keywords are missing, produce candidate keywords but ask for confirmation before treating them as final.
+3. Check technical SEO: crawlability, indexability, robots.txt, sitemap, canonical URLs, redirects, status codes, metadata, structured data, mobile/performance signals, image text alternatives, and broken links.
+4. Check information architecture and content: page purpose, search intent, H1/H2 hierarchy, topical coverage, duplication, cannibalization, thin pages, internal links, orphan pages, and conversion paths.
+5. Run keyword analysis using natural placement and intent alignment. Report counts as evidence, never as a mandatory density target.
+6. Run the AEO signal checklist and extractability assessment for direct answers, definitions, steps, FAQs, comparisons, and visible supporting evidence.
+7. Score SEO, AEO, readability, and conversion readiness against the rubric, including confidence and evidence for each major finding.
+8. Build a prioritized fix plan with exact files/pages affected, implementation notes, dependencies, and verification criteria.
+9. If implementation is authorized, apply the fixes in priority order, re-run the audit, and report before/after results. Never publish or mutate external accounts without explicit authorization.
+10. Verify the findings against the supplied content or project files. If a repository already provides an audit helper, use it as a supplementary check; never replace evidence-based review with a hard-coded demo or an unsupported density score.
+
+---
+
+## Connected Skills
+- Receives output from: `seo-aeo-blog-writer`, `seo-aeo-landing-page-writer`
+- Feeds output to: `seo-aeo-internal-linking`, `seo-aeo-schema-generator`
+
+## When to Use
+
+Use before implementing SEO/AEO changes on a website, codebase, URL, page, or content set, and again when verifying the fixes.
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
-- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
-- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
+
+- An audit cannot prove indexing, ranking, conversion, or third-party platform state without current observable evidence.

package/bundled-skills/seo-aeo-content-quality-auditor/references/seo-audit-checklist.md

@@ -0,0 +1,63 @@
+# SEO/AEO Website Audit Checklist
+
+Use this reference for a new project or a request to audit a live site. The audit is evidence-first: distinguish what was observed, what is inferred, and what still needs access or verification.
+
+## Audit modes
+
+### Codebase audit
+
+Inspect the framework, routes, page components, content files, metadata helpers, sitemap and robots generation, canonical handling, redirects, image handling, structured-data code, internal links, and deployment configuration. Identify the exact file and route affected by every implementation recommendation.
+
+### Live-site audit
+
+Inspect the supplied URL and representative pages. Check rendered HTML where possible, status codes, titles, descriptions, headings, canonical tags, robots directives, sitemap availability, structured data, links, visible answer content, conversion paths, and mobile/performance symptoms. Use browser inspection or a permitted search/API source when available.
+
+### Content-only audit
+
+Assess the supplied text for intent match, topical completeness, direct answers, readability, metadata, headings, internal-link opportunities, conversion clarity, and unsupported claims. Do not imply that technical checks passed when no site or codebase was available.
+
+## Dimensions to inspect
+
+| Dimension | Look for | Critical failure examples |
+|---|---|---|
+| Crawlability | robots.txt, sitemap, status codes, redirects, canonical URLs | Important pages blocked or unreachable |
+| Indexability | noindex rules, canonical consistency, duplicate routes | Target page cannot be indexed |
+| Metadata | unique title, description, canonical, Open Graph, Twitter data | Missing or duplicated metadata across important pages |
+| Information architecture | clear page purpose, URL structure, navigation, breadcrumbs | Important content is orphaned or buried |
+| Content and intent | query-to-page match, problem solved, topical coverage, proof | Page targets a query but does not answer it |
+| AEO | direct-answer block, definitions, lists, steps, FAQs, visible evidence | No concise answer to the page’s main question |
+| Internal links | relevant contextual links, descriptive anchors, product path | Foundational content does not lead to the product |
+| Structured data | schema matches visible content and page type | Invalid, misleading, or unsupported schema |
+| Conversion | CTA clarity, signup path, objections, trust evidence | Content attracts visits but gives no next step |
+| Quality and trust | accuracy, originality, authorship, dates, claim support | Invented proof or unverifiable claims |
+
+## Finding format
+
+Every finding should include:
+
+1. Severity: Blocker, High, Medium, or Low.
+2. Evidence: URL, route, file, selector, snippet, or command output.
+3. Impact: ranking, indexation, answer extraction, conversion, or maintenance.
+4. Fix: the smallest practical change that resolves the issue.
+5. Verification: the observable check that proves the fix worked.
+6. Dependency: credentials, deployment, content input, or user decision required.
+
+Do not assign a score without evidence. Mark checks as `Not assessed` when the required site, code, credential, or live data is unavailable.
+
+## Audit-to-implementation loop
+
+1. Run the audit and group findings by page, route, and system.
+2. Ask for target keywords and business priorities. If the user does not know them, offer candidate keywords derived from the site and label them as provisional.
+3. Convert findings into an ordered implementation checklist.
+4. Apply code/content changes only after the user has authorized implementation.
+5. Re-run the relevant audit checks and compare before/after evidence.
+6. Verify build, routes, metadata, sitemap, robots, links, schema, and deployment status.
+7. Report unresolved findings and the next decision, rather than declaring success from a code diff alone.
+
+## Safety and evidence rules
+
+- Never fabricate search volume, rankings, impressions, clicks, customers, backlinks, reviews, or performance claims.
+- Never claim Google Search Console or Bing Webmaster setup is complete without verified access and a successful property/sitemap check.
+- Treat search-result observations as time- and location-dependent. Record the source, date, market, and device when available.
+- Do not add FAQ or review schema for content that is not visible and truthful on the page.
+- Avoid arbitrary keyword-density targets. Intent coverage, natural language, and helpfulness matter more than a percentage.