seo-report

SEO Report Generator — File-Persisted Reports

Generates complete, AI-analyzed SEO reports and saves them to disk as markdown files. Supports four report types: monthly, weekly, audit, and competitor. This is the first sub-skill in the project that uses the Write tool for file persistence.

References

@skills/seo/references/mcp-degradation.md @skills/seo/references/ahrefs-api-reference.md @skills/seo/references/gsc-api-reference.md

Inputs

• type: Report type — one of: monthly, weekly, audit, competitor (required)
• domain: The domain to report on, bare domain e.g. example.com (required). Strip https://, http://, and trailing slashes.
• site (optional): GSC property URL for including Google Search Console data. Format: https://example.com/ or sc-domain:example.com
• competitor (optional, required for competitor type): Competitor domain to compare against, e.g. competitor.com
• output_dir (optional): Directory path to save the report file. Default: current working directory (pwd).

MCP Check

Before proceeding, check MCP availability:

1. Ahrefs (required for all report types): Use ToolSearch with query +ahrefs

   • If tools returned → Ahrefs available, proceed
   • If no tools returned → display Ahrefs error template from mcp-degradation.md and stop

2. GSC (optional — only if site parameter is provided): Use ToolSearch with query +google-search-console

   • If tools returned → GSC available, include GSC data in report
   • If no tools returned → continue with Ahrefs-only, note missing GSC data in report

Execution

Step 0 — Generate Filename and Resolve Output Path

Use Bash to generate the absolute file path:

echo "$(pwd)/seo-report-$(date +%Y-%m-%d)-{domain}-{type}.md"

If output_dir is provided, replace $(pwd) with the provided directory path. Store this absolute path — it is used in Step 4 (Write) and Step 5 (confirmation).

Filename convention: seo-report-YYYY-MM-DD-domain-type.md Example: seo-report-2026-03-02-example.com-monthly.md