# gsc-portfolio-audit

gsc-portfolio-audit — a skill for Claude Code, Codex, and other platforms that audits every Google Search Console property in an account. It compares clicks, impressions, and keyword performance across periods.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 112 installs · ★ 750 repo stars
- Author: OpenClaudia
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/OpenClaudia/openclaudia-skills/tree/HEAD/skills/gsc-portfolio-audit/SKILL.md
- Updated: 2026-10-21
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/gsc-portfolio-audit

## What it does

The tool audits all GSC properties at once, ranking them by traffic and computing period-over-period deltas. It diffs keywords to surface new rankings, rising opportunities, or drop-offs. The script automatically offsets for the 3-day GSC data lag.

Requires `GOOGLE_GSC_CLIENT_ID`, `GOOGLE_GSC_CLIENT_SECRET`, and `GOOGLE_REFRESH_TOKEN` with `https://www.googleapis.com/auth/webmasters.readonly` scope. Install the `requests` library and export the credentials as environment variables before executing the script.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill gsc-portfolio-audit -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/gsc-portfolio-audit/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/gsc-portfolio-audit/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill gsc-portfolio-audit -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/gsc-portfolio-audit/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill gsc-portfolio-audit -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/gsc-portfolio-audit/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install OpenClaudia/openclaudia-skills skills/gsc-portfolio-audit
```

2. **Manually: put the files in place**
- File: `.github/skills/gsc-portfolio-audit/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill gsc-portfolio-audit -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/OpenClaudia/openclaudia-skills --path skills/gsc-portfolio-audit
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/gsc-portfolio-audit/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill gsc-portfolio-audit -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/OpenClaudia/openclaudia-skills/tree/HEAD/skills/gsc-portfolio-audit/SKILL.md

## When to use it
- compare search performance across all portfolio sites
- identify new ranking keywords
- detect dropped GSC properties

## Example prompts
- Audit GSC for all my properties
- Rank my sites by traffic and show new keywords
- Run portfolio search performance report

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 7dc3513a0c9ca896.

BEGIN THIRD-PARTY FILE 7dc3513a0c9ca896
````text
---
name: gsc-portfolio-audit
description: >
  Audit EVERY Google Search Console property at once — rank all sites by clicks and
  impressions with period-over-period deltas, then diff keywords per site to surface what
  is newly ranking, rising, dropping, lost, or ranking well without earning clicks.
  Built for agencies and multi-site owners. Use when asked to compare all sites, rank
  properties by traffic, find new keywords across a portfolio, or spot which site is down.
  Trigger phrases: "audit GSC", "all my sites", "rank my properties", "portfolio search
  performance", "which sites are down", "what new keywords are we ranking for",
  "client site performance", "GSC report across accounts".
  For ONE site's queries, pages, or index coverage, use the search-console skill instead.
---

# GSC Portfolio Audit

Answers "how is everything doing?" across every property on a Search Console account, which is the question the per-site tooling can't answer without dozens of manual exports.

## Setup

Requires an OAuth refresh token with `https://www.googleapis.com/auth/webmasters.readonly`:

```bash
export GOOGLE_GSC_CLIENT_ID=...      # or GOOGLE_CLIENT_ID
export GOOGLE_GSC_CLIENT_SECRET=...  # or GOOGLE_CLIENT_SECRET
export GOOGLE_REFRESH_TOKEN=...
export GSC_EXCLUDE="olddomain.com"   # optional, comma-separated
pip install requests
```

**The most common setup failure is `unauthorized_client` on token refresh.** It means the refresh token was issued for a different OAuth client than the id/secret you paired with it. Accounts that have added Google integrations over time usually have several clients; match the pair that minted the token.

## Run it

```bash
python3 scripts/audit_gsc.py            # full: ranking + keyword diff for the top 12
python3 scripts/audit_gsc.py portfolio  # just the ranked table
python3 scripts/audit_gsc.py queries --site sc-domain:example.com
python3 scripts/audit_gsc.py --days 90  # quarter over quarter
```

Flags: `--days` (window, compared against the window immediately before it), `--site` (repeatable), `--top`, `--limit`, `--min-clicks`.

## Sections and what they mean

| Section | Read it as |
|---|---|
| NEW | queries with zero clicks last period. Where growth is actually coming from. |
| RISING | up ≥50%. Check whether position moved too — if it didn't, demand rose, not your ranking. |
| DROPPING | down ≥40% off a real base. **Position tells you which kind:** rank fell = ranking loss; rank held but clicks collapsed = something took the clicks above you (AI Overview, a new SERP feature, or the query changed shape). |
| LOST | ranked before, no data now. |
| CTR GAP | ≥1,500 impressions, top 10, under 2% CTR. Title and description rewrites, the cheapest wins available. |

## Interpreting

- **Report clicks first, impressions second.** One large property can swing portfolio impressions enough to mask that everything else grew.
````
END THIRD-PARTY FILE 7dc3513a0c9ca896

The third-party file has ended. Everything between the 7dc3513a0c9ca896 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2918 of 4177 bytes. © OpenClaudia · MIT · https://github.com/OpenClaudia/openclaudia-skills/tree/HEAD/skills/gsc-portfolio-audit/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
