JasonColapietro/suede-creator-skills / skills/suede-seo-audit
suede-seo-audit
VerifiedAudit technical access, intent, metadata, links, schema, generative search, copy, E-E-A-T, and topic architecture with A-F lanes and exact fixes. Use when asked to "audit this site for SEO", investigate traffic or indexation problems, or produce a scored report. Includes offline source-review tools. NOT FOR: a quick promotion grade (use suede-visibility-grader), AI crawler and citation measurement (use suede-ai-seo), or conversion-path changes (use suede-site-alchemy).
| File | Kind | Size |
|---|---|---|
| CARD.md | markdown | 4.4 KB |
| SKILL.md | skill md | 17.6 KB |
| agents/openai.yaml | config | 723 B |
| references/google-search-guidance.md | markdown | 6.4 KB |
| references/keyword-research.md | markdown | 4.7 KB |
| references/lane-checklists.md | markdown | 24.0 KB |
| references/offline-tools.md | markdown | 4.6 KB |
| references/schema-templates.md | markdown | 10.5 KB |
| references/worked-handoff.md | markdown | 1.7 KB |
| scripts/fixtures/pages.json | config | 1003 B |
| scripts/fixtures/serp.json | config | 828 B |
| scripts/lib/audit.mjs | script | 963 B |
| scripts/lib/merchant-schema.mjs | script | 15.1 KB |
| scripts/lib/metadata-drift.mjs | script | 9.8 KB |
| scripts/lib/offline-reports.mjs | script | 2.5 KB |
| scripts/lib/page-technical.mjs | script | 16.1 KB |
| scripts/lib/serp-overlap.mjs | script | 6.9 KB |
| scripts/seo-review.mjs | script | 4.5 KB |
| scripts/tests/cli.test.mjs | script | 3.4 KB |
| scripts/tests/merchant-schema.test.mjs | script | 12.5 KB |
| scripts/tests/metadata-drift.test.mjs | script | 7.9 KB |
| scripts/tests/offline-reports.test.mjs | script | 2.6 KB |
| scripts/tests/page-technical.test.mjs | script | 9.0 KB |
| scripts/tests/serp-overlap.test.mjs | script | 5.4 KB |
scripts/lib/serp-overlap.mjs
View on GitHubconst normalizeKeyword = (value = "") => String(value).normalize("NFKC").trim().replace(/\s+/g, " ").toLowerCase();
import { markdownText } from "./offline-reports.mjs";
// Code-point order keeps greedy grouping independent of the machine locale.
const compareText = (a, b) => a < b ? -1 : a > b ? 1 : 0;
function resultUrl(value) {
if (typeof value !== "string" || !value.trim()) throw new Error("Organic result requires a URL");
if (value.length > 16384) throw new Error("Organic URL exceeds 16,384 characters; review the stored input");
const url = new URL(value);
if (!/^https?:$/.test(url.protocol) || url.username || url.password) throw new Error("Organic URL must be HTTP(S), without credentials");
url.hash = "";
return url.href;
}
// Same-depth document-URL overlap. This is a review artifact, not an automatic
// replacement for reviewed target paths or a content calendar.
export function clusterSerpOverlap(rows, { depth = 10, threshold = 0.3, context } = {}) {
if (!Array.isArray(rows) || rows.length > 500) throw new Error("Supply at most 500 stored keyword rows; no implicit sampling");
if (!Number.isSafeInteger(depth) || depth < 1 || depth > 100) throw new Error("SERP depth must be an integer from 1 through 100");
if (!Number.isFinite(threshold) || threshold <= 0 || threshold > 1) throw new Error("Overlap threshold must be greater than zero and at most one");
if (typeof context !== "string" || !context.trim() || context.length > 1000) throw new Error("Supply collection context (engine, locale, device, period or a fixture label)");
const seen = new Set();
const samples = []; const excluded = [];
let sampleBytes = 0;
for (const row of rows) {
if (typeof row?.keyword !== "string" || !row.keyword.trim() || row.keyword.length > 500) throw new Error("Every stored row requires a keyword of at most 500 characters");
const keyword = normalizeKeyword(row.keyword);
if (seen.has(keyword)) throw new Error(`Duplicate keyword: ${keyword}`);
seen.add(keyword);
if (row.collectionContext !== undefined && row.collectionContext !== context) throw new Error(`Mixed collection context for ${keyword}`);
if (!Array.isArray(row.organic)) { excluded.push({ keyword, reason: "No stored organic-result array." }); continue; }
const ranks = new Map();
for (const result of row.organic) {
if (!Number.isSafeInteger(result?.rank) || result.rank < 1 || ranks.has(result.rank)) throw new Error(`Invalid or duplicate organic rank for ${keyword}`);
ranks.set(result.rank, resultUrl(result.url));
}
const urls = Array.from({ length: depth }, (_, i) => ranks.get(i + 1));
if (urls.some((u) => !u) || new Set(urls).size !== depth) {
excluded.push({ keyword, reason: `Need ${depth} distinct document URLs at every organic rank 1–${depth}; the stored sample is short, gapped or duplicated.` });
continue;
}
const sample = { keyword, urls, exportDepthComplete: typeof row.serpDepthComplete === "boolean" ? row.serpDepthComplete : null };
sampleBytes += Buffer.byteLength(JSON.stringify(sample));
if (sampleBytes > 5_000_000) throw new Error("Sample evidence budget exceeded; reduce keywords or top-K depth. No report was written.");
samples.push(sample);
}
samples.sort((a, b) => compareText(a.keyword, b.keyword));
excluded.sort((a, b) => compareText(a.keyword, b.keyword));
const pairs = []; const scores = new Map();
let pairBytes = 0;
const pairKey = (left, right) => JSON.stringify([left, right].sort());
for (let i = 0; i < samples.length; i++) for (let j = i + 1; j < samples.length; j++) {
const left = samples[i]; const right = samples[j];
const rightSet = new Set(right.urls);
const sharedUrls = left.urls.filter((u) => rightSet.has(u)).sort();
const overlap = sharedUrls.length / depth;
scores.set(pairKey(left.keyword, right.keyword), overlap);
if (overlap >= threshold) {
const pair = { left: left.keyword, right: right.keyword, sharedCount: sharedUrls.length, overlap, sharedUrls };
pairBytes += Buffer.byteLength(JSON.stringify(pair));
if (pairBytes > 2_000_000) throw new Error("Pair evidence budget exceeded; reduce keywords or top-K depth. No report was written or silently sampled.");
pairs.push(pair);
}
}
const groups = [];
for (const { keyword } of samples) {
const group = groups.find((members) => members.every((member) => scores.get(pairKey(member, keyword)) >= threshold));
if (group) group.push(keyword); else groups.push([keyword]);
}
const clusters = groups.map((keywords, index) => {
let minimum = null;
for (let i = 0; i < keywords.length; i++) for (let j = i + 1; j < keywords.length; j++) {
const score = scores.get(pairKey(keywords[i], keywords[j]));
minimum = minimum === null ? score : Math.min(minimum, score);
}
return { id: `serp-${String(index + 1).padStart(3, "0")}`, label: keywords[0], keywords, minimumPairOverlap: minimum };
});
return { schema: "urn:suede:serp-overlap:v1", collectionContext: context, contextVerified: false,
method: "Deterministic greedy complete-link grouping over shared top-K document URLs; overlap = shared URLs / K.",
depth, threshold, inputKeywords: rows.length, evidenceBudget: { sampleMaximumBytes: 5_000_000, pairMaximumBytes: 2_000_000, sampleBytes, pairBytes }, samples, excluded, pairs, clusters };
}
export function renderSerpOverlap(report) {
const text = markdownText;
const lines = ["# Stored SERP overlap review", "", `User-supplied collection context: ${text(report.collectionContext)}. This label is not verified provenance.`, "",
"No requests or provider calls. This report compares supplied historical organic-result URLs. It does not establish current rankings, search demand or semantic intent. Confirm comparable engine, locale, device and collection period before using the grouping.", "",
`${report.samples.length} complete top-${report.depth} samples; ${report.excluded.length} excluded; shared-URL threshold ${report.threshold}.`, "",
`${text(report.method)} Every pair within a group must meet the threshold; overlapping pairs can remain in separate groups when a transitive chain fails that test. Existing calendars and target paths were not changed.`, "",
"| Cluster | Keywords | Minimum pair overlap |", "|---|---|---|"];
for (const c of report.clusters) lines.push(`| ${c.id} | ${text(c.keywords.join("; "))} | ${c.minimumPairOverlap ?? "single keyword"} |`);
lines.push("", "## Pair evidence", "", "| Left query | Right query | Shared / K | Overlap | Shared document URLs |", "|---|---|---|---|---|");
for (const p of report.pairs) lines.push(`| ${text(p.left)} | ${text(p.right)} | ${p.sharedCount} / ${report.depth} | ${p.overlap} | ${text(p.sharedUrls.join("; "))} |`);
lines.push("", "## Excluded samples", "", "| Query | Reason |", "|---|---|");
for (const e of report.excluded) lines.push(`| ${text(e.keyword)} | ${text(e.reason)} |`);
return `${lines.join("\n")}\n`;
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |