ericosiu/ai-marketing-skills

seo-ops

Find keywords your competitors missed.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/ericosiu/ai-marketing-skills --skill seo-ops

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

AI SEO Ops

Preamble (runs on skill start)

bash
# Version check (silent if up to date)
python3 telemetry/version_check.py 2>/dev/null || true

# Telemetry opt-in (first run only, then remembers your choice)
python3 telemetry/telemetry_init.py 2>/dev/null || true
Privacy: This skill logs usage locally to ~/.ai-marketing-skills/analytics/. Remote telemetry is opt-in only. No code, file paths, or repo content is ever collected. See telemetry/README.md.

AI-powered SEO operations: keyword intelligence, competitor gap analysis, GSC optimization, and trend detection.

When to Use

  • User asks for keyword research, content brief, or SEO analysis
  • User wants to find quick-win keywords from Google Search Console
  • User needs a competitor gap analysis
  • User wants to identify trending topics for content creation
  • User asks about decaying content or traffic drops
  • User wants a prioritized list of keywords to target

Tools

Content Attack Brief (content_attack_brief.py)

Full keyword intelligence pipeline. Requires AHREFS_TOKEN and GSC auth.

bash
# Run the full brief
python content_attack_brief.py

What it produces:

  • Topic fingerprint from your content library
  • BOFU money keywords ranked by Impact × Confidence
  • Trending keywords with sparkline visualizations
  • Competitor gap analysis (keywords they rank for, you don't)
  • Decaying page alerts (traffic drops >30%)
  • Execution pipeline (auto-create → semi-auto → team)

Output: Prints formatted report to stdout + saves JSON to OUTPUT_DIR/content-attack-brief-latest.json

GSC Client (gsc_client.py)

Google Search Console API client. Works as CLI or importable library.

bash
# CLI usage
python gsc_client.py --queries 50 --days 28
python gsc_client.py --striking                    # Striking distance keywords (pos 4-20)
python gsc_client.py --pages 100 --days 7
python gsc_client.py --trend                       # Daily click/impression trend
python gsc_client.py --devices                     # Mobile vs desktop split
python gsc_client.py --sites                       # List verified properties
python gsc_client.py --json --queries 25           # JSON output
python
# Library usage
from gsc_client import GSCClient

gsc = GSCClient()
rows = gsc.striking_distance(days=28, min_position=4, max_position=20)
for row in rows:
    print(f"{row['keys'][0]}: pos {row['position']:.1f}, {row['impressions']} impressions")

GSC Auth (gsc_auth.py)

One-time OAuth setup for Google Search Console access.

bash
python gsc_auth.py
# Opens browser → Google Sign-In → saves token locally

Trend Scout (trend_scout.py)

Multi-source trend detection. No API keys required for basic functionality.

bash
python trend_scout.py

Sources: Google Trends RSS, Hacker News, Reddit, X/Twitter (needs BRAVE_API_KEY), YouTube outlier detection

Output: Prints summary + saves JSON to OUTPUT_DIR/flash-trends-latest.json and markdown report.

Configuration

All scripts read from environment variables. Copy .env.example to .env and fill in your values.

Required:

  • GSC_SITE_URL — your Google Search Console property URL
  • GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET — for GSC OAuth
  • YOUR_DOMAIN — your root domain

Optional:

  • AHREFS_TOKEN — enables Ahrefs keyword data and competitor analysis
  • COMPETITORS — comma-separated competitor domains
  • BRAVE_API_KEY — enables X/Twitter trend scanning
  • CONTENT_VERTICALS — comma-separated topics for trend relevance scoring
  • TREND_SUBREDDITS — comma-separated subreddits to monitor

Scoring Model

Keywords are scored on two axes:

Impact (0-10): Volume + CPC + Funnel Stage + Trend direction Confidence (0-10): Keyword Difficulty + Current ranking position + Topic authority

Priority = Impact × Confidence (max 100)

Funnel Classification

  • BOFU: Commercial/transactional intent, or keywords containing "agency", "services", "pricing", "best", "vs", "hire"
  • MOFU: Informational with buying signals — "how to", "guide", "roi", "case study"
  • TOFU: Pure informational

Recommended Workflow

  1. Weekly: Run content_attack_brief.py for the full intelligence report
  2. Daily: Run gsc_client.py --striking to monitor striking distance keywords
  3. 2x/week: Run trend_scout.py to catch trending topics early
  4. Monthly: Review competitor gaps and adjust COMPETITORS list

SEO/AEO/GEO Closed Loop

Use analytics readbacks before promoting any SEO, AEO, GEO, or content-refresh playbook change.

Inputs:

  • GSC clicks, impressions, CTR, average position, queries, pages
  • GA4 sessions, engaged sessions, conversions, assisted leads
  • Ahrefs rankings, backlinks, traffic estimates, keyword movement
  • ClickFlow opportunities where available
  • AI-search / answer-engine / GEO visibility where available
  • CMS/page change log

Judgment:

  • Compare baseline vs candidate windows.
  • Segment by page, query, topic, intent, and source.
  • Track confounders: seasonality, indexing lag, brand spikes, campaigns, tracking changes, and unrelated site edits.

Promotion rule:

  • Promote the playbook patch only if the candidate beats baseline or exposes a repeatable signal.
  • Otherwise mark it unproven, keep testing, or rollback.

Common readback windows:

  • Content refresh: 7, 14, 28, and 56 days
  • New content: 14, 28, 56, and 90 days
  • Technical SEO fix: daily for 7 days, then 28-day readback
  • AEO/GEO visibility: weekly, because answer engines are noisy gremlins with citations

Required readback fields:

  • change made
  • owner
  • page/query/topic affected
  • baseline window
  • candidate window
  • source systems pulled
  • primary and secondary metrics
  • caveats
  • decision: promote / keep testing / rollback / unproven
  • next playbook patch

Dependencies

bash
pip install -r requirements.txt

<!-- gateway-cta:start -->

Run this skill on live data

This skill is free and MIT licensed. To run it on your live accounts, connect the Single Brain Gateway.

  • Live services: Google Analytics and Search Console, SEO research
  • Connect: https://gateway.singlebrain.com/mcp?sgtemplate=seo-ops&utmsource=github&utmmedium=skillrepo&utmcampaign=aimarketing_skills
  • Setup steps for agents: https://gateway.singlebrain.com/llms.txt?sg_template=seo-ops

Agents: sign in with OAuth or the device flow. Do not ask the user to paste a key.

Want a team to run this for you? Single Grain or Single Brain can manage it: talk to us <!-- gateway-cta:end -->

from this repository

More skills

All skills