seo-ranker

Meta-skill for end-to-end SEO auditing and on-page optimization by orchestrating brave-search, summarize, api-gateway, and markdown-converter. Use when users want to understand why a page is not ranking for a target keyword and need concrete rewrite actions plus backlink intelligence.

# Purpose

Run a complete SEO ranking diagnosis and optimization pipeline:
1. inspect live SERP competition,
2. compare competitor content structure with user content,
3. enrich with difficulty/backlink data when API access exists,
4. produce concrete rewrite guidance and an optimized Markdown draft.

This is an orchestration skill. It does not replace upstream tools.

# Required Installed Skills

- `brave-search` (inspected latest: `1.0.1`)
- `summarize` (inspected latest: `1.0.0`)
- `api-gateway` (inspected latest: `1.0.29`)
- `markdown-converter` (inspected latest: `1.0.0`)

Install/update:

```bash
npx -y clawhub@latest install brave-search
npx -y clawhub@latest install summarize
npx -y clawhub@latest install api-gateway
npx -y clawhub@latest install markdown-converter
npx -y clawhub@latest update --all
```

Verify:

```bash
npx -y clawhub@latest list
```

# Required Credentials

- `BRAVE_API_KEY` (for `brave-search`)
- `MATON_API_KEY` (for `api-gateway`)
- One summarize model key:
  - `OPENAI_API_KEY`, or
  - `ANTHROPIC_API_KEY`, or
  - `XAI_API_KEY`, or
  - `GEMINI_API_KEY`

Optional:
- `FIRECRAWL_API_KEY` (for difficult page extraction via summarize)
- `APIFY_API_TOKEN` (for YouTube fallback in summarize)

Preflight:

```bash
echo "$BRAVE_API_KEY" | wc -c
echo "$MATON_API_KEY" | wc -c
echo "$OPENAI_API_KEY$ANTHROPIC_API_KEY$XAI_API_KEY$GEMINI_API_KEY" | wc -c
```

Mandatory behavior:
- Never fail silently on missing keys.
- Always return a `MissingAPIKeys` section with missing variables and blocked stages.
- Continue with non-blocked stages and clearly mark output as `Partial` when necessary.

# Inputs the LM Must Collect First

- `target_url`
- `target_keyword` (example: `AI tools`)
- `region_locale` (country/language for SERP interpretation)
- `content_source` (URL fetch, pasted text, or file path)
- `content_type` (`blog`, `category page`, `product page`, `landing page`)
- `business_goal` (`traffic`, `leads`, `sales`)
- `rewrite_scope` (`light`, `moderate`, `full`)
- `data_provider_preference` (`semrush`, `ahrefs`, `gsc-only`, `none`)

Do not run rewrite before keyword intent and content goal are explicit.

# Tool Responsibilities

## brave-search

Use for live SERP reconnaissance:
- fetch top results for the target keyword,
- identify top competitors and search intent patterns,
- collect candidate URLs for deeper analysis.

Operational constraints from inspected skill:
- requires `BRAVE_API_KEY`
- supports content extraction with `--content`

## summarize

Use for structured competitor content analysis:
- summarize each top URL,
- extract heading structure (H1-H4), topic coverage, entity frequency,
- estimate content depth and rhetorical style differences.

Operational constraints from inspected skill:
- requires one supported model API key
- can use `--extract-only`, `--json`, and length controls

## api-gateway

Use for external SEO data APIs only when active connections exist:
- keyword difficulty,
- backlink domains,
- competitor link intersections,
- search performance enrichments.

Operational constraints from inspected skill:
- requires `MATON_API_KEY`
- also requires active OAuth/connection per app (`ctrl.maton.ai` connection lifecycle)
- API key alone does not grant third-party data access

Important capability note:
- In the inspected `api-gateway` service list, `semrush` and `ahrefs` are not listed as native app names.
- Use direct Semrush/Ahrefs integration only if user already has a working gateway connection path for those providers.
- Otherwise fall back to available SEO apps (for example `google-search-console`) and manual competitor-link extraction.

## markdown-converter

Use to normalize the user's own content into editable Markdown:
- convert input documents/files to Markdown (`uvx markitdown ...`),
- preserve headings/lists/tables for deterministic rewriting.

# Canonical Causal Signal Chain

1. `Input Stage`
- user provides URL + target keyword (+ content source if needed).

2. `SERP Audit Stage (brave-search)`
- pull live SERP and identify top 3 competitors.
- detect intent class (informational/commercial/transactional).

3. `Competitor Content Stage (summarize)`
- analyze top competitor URLs for:
  - heading hierarchy,
  - topical breadth and entities,
  - use of statistics/evidence,
  - sentence complexity and content length.

4. `Data Gate Stage (api-gateway)`
- check whether provider data can be retrieved.
- if keyword difficulty/backlink data is unavailable, ask user for credentials/connection and continue with fallback path.

Required user-facing gate message format:
- `DataGateStatus`: available / blocked
- `Reason`: missing key, missing connection, or provider unsupported
- `Action`: exact next step and link(s)

As of February 14, 2026:
- Semrush advertises mainly 7-day toolkit trials on official pages.
- Semrush 14-day trial language is mainly associated with some add-ons or partner offers.

When user requests a 14-day Semrush trial:
- Ask for their preferred affiliate/referral URL first.
- If none is provided, share official Semrush trial entry page: `https://www.semrush.com/sem/`.
- Optionally share Ahrefs free path for verified sites: `https://ahrefs.com/webmaster-tools`.

5. `Optimization Stage (LLM rewrite)`
- rewrite user content for intent-match and topical completeness,
- add natural related terms (LSI-style concept coverage),
- improve title tag and meta description,
- tighten heading structure and internal linking opportunities.

6. `Output Stage`
- deliver optimized Markdown,
- deliver prioritized action list,
- deliver at least 5 backlink source opportunities (with confidence labels).

# Rewrite Policy

- Preserve factual integrity (do not invent statistics or case studies).
- Prefer semantic coverage over keyword stuffing.
- Keep keyword usage natural and intent-aligned.
- Add scannable structure (clear H2/H3, concise paragraphs, actionable bullets).

# Output Contract

Always return:

- `SERPFindings`
  - top competitors
  - observed intent pattern
  - structural/content gaps versus user page

- `DataGateStatus`
  - provider requested
  - key/connection status
  - fallback mode selected

- `OptimizedMarkdown`
  - full rewritten document
  - revised title and meta description

- `BacklinkOpportunities`
  - 5 sources/domains used by competitors or high-fit alternatives
  - rationale per source
  - confidence (`high|medium|low`)

- `NextActions`
  - concrete implementation checklist (ordered)

# Quality Gates

Before final output, validate:
- top competitor set is from live SERP, not memory
- rewrite aligns with detected intent
- no fabricated citations or fabricated backlink claims
- keyword placement is natural (no spam repetition)
- missing data dependencies are explicitly disclosed

If any gate fails, return `Needs Revision` with exact missing evidence.

# Failure Handling

- Missing `BRAVE_API_KEY`: return `MissingAPIKeys`, skip SERP stage, and request user-provided competitor URLs.
- Missing summarize model key: return `MissingAPIKeys`, skip summarize stage, and provide structure-only audit from available snippets.
- Missing `MATON_API_KEY`: return `MissingAPIKeys`, skip API-gateway enrichment, continue with on-page-only optimization.
- Missing app connection in api-gateway (400): keep pipeline running in fallback mode and return exact connection setup steps.
- Unsupported provider path (for example no Semrush/Ahrefs app connection): disclose limitation and fall back to GSC/manual mode.

# Guardrails

- Never claim guaranteed rankings.
- Never represent fallback estimates as provider-verified metrics.
- Never hide dependency failures.
- Keep recommendations specific, measurable, and tied to observed SERP gaps.