Open Graph Audit

Open Graph / Social Metadata Audit

Audit a website's Open Graph and Twitter Card tags and produce an actionable report on how the site's links render when shared.

When to use this skill

Use this skill when the user asks to:

• Audit, validate, or check Open Graph (og:*) or Twitter Card (twitter:*) tags
• Diagnose why links look wrong / have no image when shared on social or chat
• Find missing or broken share images, or og:url that points at the wrong URL
• Improve social click-through and link previews

Inputs to collect

1. Site URL or URL list — a live site root to crawl (auto-seeds from /sitemap.xml), or a text file with --url-list.
2. Scope — pages to crawl (default 500, --max-pages).
3. Image probing — whether to probe each og:image/twitter:image for status and content type (default on; --no-probe to skip).

Workflow

Step 1: Crawl and probe social tags

Use scripts/extract_social.py:

python3 scripts/extract_social.py https://example.com --max-pages 500 --output social_inventory.json
# already crawled once (e.g. in a full SEO audit)? skip the crawl and reuse the shared cache:
# python3 scripts/fetch_pages.py https://example.com --output page_cache.json
# python3 scripts/extract_social.py --from-cache page_cache.json --output social_inventory.json

It records each page's OG and Twitter Card tags, canonical, and meta robots, then probes each unique share image for HTTP status and content type.

Step 2: Run the audit checks

python3 scripts/audit_social.py social_inventory.json --output audit_report.json

Step 3: Evaluate the audit checks

Evaluate each check in references/audit-checks.md. Core checks:

Step 4: Produce the report

Write a report following references/report-template.md: summary by severity, broken/missing images first, then completeness gaps, then a prioritized action list.

Step 5: Recommend fixes

• Missing/broken image: add or repair an absolute https:// og:image (1200×630 recommended) that returns 200.
• Missing og:title/description: add them (page title and meta description are good sources).
• og:url missing/mismatched: set it to the canonical absolute URL.
• Relative/non-image og:image: use an absolute URL to a real image file.
• twitter:card: add summary_large_image for most content.
• Base every recommendation on observed data; never assume an image loads.

Optional: export the report

As a Word document (.docx)

If the user wants the report as a .docx (for example, to share with stakeholders or attach to a ticket), save the Markdown report to a file and convert it:

python3 scripts/md_to_docx.py report.md --output report.docx

scripts/md_to_docx.py uses only the Python standard library (no pip install) and renders headings, tables, lists, links, bold/italic, and code blocks. Offer this whenever a user asks for a Word doc, a .docx, or a shareable/downloadable report.

As a CSV of findings (.csv)

If the user wants the raw findings as a spreadsheet (for filtering, sorting, or triage in Sheets or Excel), convert the audit's audit_report.json directly:

python3 scripts/findings_to_csv.py audit_report.json --output findings.csv

scripts/findings_to_csv.py is also standard-library only. It writes one row per finding, with check and severity columns prepended and list fields (e.g. the pages sharing a duplicate value) joined with ; . Unlike the .docx, which reformats the written report, the CSV is a direct dump of the structured findings — offer it whenever a user wants the data itself, a spreadsheet, or to slice findings by check or severity.

Resources

• scripts/md_to_docx.py — convert the Markdown report into a Word (.docx) document (standard library only)
• scripts/findings_to_csv.py — flatten the audit findings JSON into a CSV, one row per finding (standard library only)
• references/audit-checks.md — full definitions, thresholds, and rationale
• references/report-template.md — report output structure
• scripts/extract_social.py — crawl pages and probe share images
• scripts/audit_social.py — run audit checks against the inventory