The-AI-Directory-Company/agents-and-skills / skills/on-page-sgeo
on-page-sgeo
VerifiedOptimize individual pages for both search engine ranking and AI citation — covering title tags, meta descriptions, heading hierarchy, URL structure, internal linking, image optimization, structured data, direct-answer formatting, and knowledge block structure.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 25.2 KB |
| references/geo-formatting.md | markdown | 10.4 KB |
| references/heading-and-structure.md | markdown | 5.8 KB |
| references/image-and-media.md | markdown | 5.7 KB |
| references/internal-linking.md | markdown | 6.3 KB |
| references/meta-optimization.md | markdown | 5.6 KB |
| scripts/analyze-headings.pyexecutable | script | 5.9 KB |
| scripts/audit-page.pyexecutable | script | 14.6 KB |
| scripts/check-direct-answer.pyexecutable | script | 9.1 KB |
| scripts/check-freshness.pyexecutable | script | 12.1 KB |
| scripts/check-images.pyexecutable | script | 7.3 KB |
| scripts/check-internal-links.pyexecutable | script | 7.6 KB |
| scripts/extract-meta-tags.pyexecutable | script | 7.1 KB |
| scripts/extract-structured-data.pyexecutable | script | 8.1 KB |
scripts/analyze-headings.py
View on GitHub#!/usr/bin/env python3
"""Analyze heading hierarchy and GEO heading quality for a URL.
Extracts all headings (H1-H6), validates the hierarchy, classifies H2s
as question-format or declarative, and scores GEO heading quality.
Usage:
python analyze-headings.py --url https://example.com/page
python analyze-headings.py --url https://example.com/page --tools tools.json
Output: JSON with heading tree, hierarchy validation, and GEO score.
"""
import argparse
import json
import re
import sys
from html.parser import HTMLParser
from typing import Optional
# ---------------------------------------------------------------------------
# HTML Parser
# ---------------------------------------------------------------------------
class HeadingParser(HTMLParser):
"""Extract headings and title from HTML."""
def __init__(self):
super().__init__()
self.headings: list[dict] = []
self.title = ""
self._current_tag: Optional[str] = None
self._current_text = ""
self._in_title = False
def handle_starttag(self, tag: str, attrs):
if tag in ("h1", "h2", "h3", "h4", "h5", "h6"):
self._current_tag = tag
self._current_text = ""
if tag == "title":
self._in_title = True
def handle_data(self, data: str):
if self._current_tag:
self._current_text += data
if self._in_title:
self.title += data
def handle_endtag(self, tag: str):
if tag == self._current_tag:
level = int(tag[1])
text = self._current_text.strip()
text = re.sub(r"\s+", " ", text)
if text:
self.headings.append({"level": level, "text": text})
self._current_tag = None
self._current_text = ""
if tag == "title":
self._in_title = False
# ---------------------------------------------------------------------------
# Analysis
# ---------------------------------------------------------------------------
QUESTION_STARTERS = re.compile(
r"^(what|how|why|when|where|who|which|is|are|can|does|do|should|will|could)\b",
re.IGNORECASE,
)
def is_question_heading(text: str) -> bool:
"""Check if a heading is phrased as a question."""
return bool(QUESTION_STARTERS.match(text.strip())) or text.strip().endswith("?")
def check_hierarchy(headings: list[dict]) -> tuple[bool, list[str]]:
"""Validate heading hierarchy. Return (valid, list of issues)."""
issues: list[str] = []
prev_level = 0
for h in headings:
level = h["level"]
if prev_level > 0 and level > prev_level + 1:
issues.append(f"Skipped level: H{prev_level} -> H{level} (before \"{h['text'][:50]}\")")
prev_level = level
return len(issues) == 0, issues
def analyze_headings(headings: list[dict], title: str) -> dict:
h1s = [h for h in headings if h["level"] == 1]
h2s = [h for h in headings if h["level"] == 2]
issues: list[str] = []
# H1 count
h1_count = len(h1s)
if h1_count == 0:
issues.append("No H1 tag found")
elif h1_count > 1:
issues.append(f"Multiple H1 tags found ({h1_count}) — should be exactly 1")
h1_text = h1s[0]["text"] if h1s else ""
# Hierarchy validation
hierarchy_valid, hierarchy_issues = check_hierarchy(headings)
issues.extend(hierarchy_issues)
# Question-format analysis for H2s
question_h2s = 0
heading_details = []
for h in headings:
detail = {
"level": h["level"],
"text": h["text"],
}
if h["level"] == 2:
q = is_question_heading(h["text"])
detail["is_question"] = q
if q:
question_h2s += 1
heading_details.append(detail)
question_ratio = question_h2s / len(h2s) if h2s else 0
# GEO heading score
if not h2s:
geo_score = "no_h2s"
elif question_ratio >= 0.4:
geo_score = "good"
elif question_ratio >= 0.2:
geo_score = "fair"
else:
geo_score = "poor"
# Empty headings
empty = [h for h in headings if not h["text"].strip()]
if empty:
issues.append(f"{len(empty)} empty heading(s) found")
return {
"h1_count": h1_count,
"h1_text": h1_text,
"title_tag": title.strip(),
"headings": heading_details,
"total_headings": len(headings),
"h2_count": len(h2s),
"question_h2_count": question_h2s,
"question_heading_ratio": round(question_ratio, 2),
"geo_heading_score": geo_score,
"hierarchy_valid": hierarchy_valid,
"skipped_levels": hierarchy_issues,
"issues": issues,
}
# ---------------------------------------------------------------------------
# Fetch
# ---------------------------------------------------------------------------
def fetch_html(url: str) -> str:
from urllib.request import Request, urlopen
req = Request(url, headers={"User-Agent": "Mozilla/5.0 (compatible; on-page-sgeo-audit/1.0)"})
with urlopen(req, timeout=15) as resp:
return resp.read().decode("utf-8", errors="replace")
# ---------------------------------------------------------------------------
# Main
# ---------------------------------------------------------------------------
def main():
ap = argparse.ArgumentParser(description="Analyze heading hierarchy and GEO heading quality")
ap.add_argument("--url", required=True, help="Page URL to analyze")
ap.add_argument("--tools", default=None, help="Path to tools.json inventory file")
args = ap.parse_args()
try:
html = fetch_html(args.url)
except Exception as e:
print(json.dumps({"error": f"Failed to fetch URL: {e}", "url": args.url}), file=sys.stderr)
sys.exit(1)
parser = HeadingParser()
parser.feed(html)
result = analyze_headings(parser.headings, parser.title)
result["url"] = args.url
print(json.dumps(result, indent=2))
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |