Peec Checkup

Peec Checkup

Role

Single read-only pass over a Peec project that answers three questions:

1. Setup quality — is the project configured correctly, or are there structural problems holding back every measurement?
2. Brand performance now — where does the brand actually stand, snapshot today?
3. Top improvements — which 5–8 concrete moves would move the needle most, ranked?

No writes. No content production. No outreach. Pure diagnosis + recommendations.

Input

• project_id — Peec project (read from setup_state.json per pre-flight; fallback to mcp__peec-ai__list_projects if state missing)
• optional date_range — default last 28 days (falls back to whatever data exists if project is younger)
• optional top_n — number of improvements to surface, default 5, max 8

Output

One markdown report saved to /checkups/YYYY-MM-DD_checkup.md (schema in §6). Mirrored to stdout for the user. Never modifies setup_state.json or any Peec data.

When to use

• "Wo stehe ich bei Peec?" / "Wie ist mein Status?"
• "Mein Setup checken" / "Was läuft falsch bei meinem Peec-Projekt?"
• "Welche Verbesserungspotenziale gibt es?"
• Onboarding a project from another consultant — first pass to see what was set up
• Periodic ritual: monthly without 4 weeks of action history (use peec-report instead when history exists)
• After someone else changed the Peec project and you want to see what shifted

Do not use when:

• The user wants ONE next action — that is /peec-agent
• The user wants attribution of past actions — that is /peec-report
• The project is empty — that is /peec-setup (full mode)
• The user wants to mutate Peec — every other skill, not this one

---

Pipeline

0. Pre-flight — setup state required (lenient)

Per [_shared/SETUP_STATE.md](../shared/SETUPSTATE.md), this skill prefers a state file but does not hard-stop without one — checkup is itself the audit you'd run when state is missing. Logic:

Read /growth_loop/setup_state.json
If present:
  Use peec_project_id, target_country, prompt_language from state.
  Note the setup age in the report.
If missing:
  Resolve project via mcp__peec-ai__list_projects.
  Note in the report: "no setup_state.json — run /peec-setup
  (mode: import) after this checkup to persist findings."
  Default target_country=DE, prompt_language=de UNLESS the user said otherwise.

This is the only consumer skill allowed to run without a state file — because its whole job is to tell you whether you should run peec-setup next.

1. Setup-quality audit (read-only mirror of peec-setup Phase 1 + 2)

Parallel reads:

mcp__peec-ai__list_brands(project_id)
mcp__peec-ai__list_prompts(project_id, limit=200)
mcp__peec-ai__list_topics(project_id)
mcp__peec-ai__list_tags(project_id)

Score against this checklist (each item = +/− points; record per-finding evidence):

| Check | Red flag | |---|---| | Competitors are real buyer alternatives | SaaS tool brands present (SEMrush, Ahrefs, Sistrix, Moz, Ryte, Yoast, Frase, Surfer, ScreamingFrog) — distort SoV | | Competitors include AI-recommended ones | Compare list to brands appearing in list_chats sources but not tracked → "invisible competitors" | | Funnel coverage balanced | Counts per stage (Awareness/Consideration/Decision/Retention) — flag any stage 50% of total | | Prompts use buyer language | Quick scan: ≥3 prompts contain platform-vendor phrases ("empfiehl", "vergleich", "alternativ") | | Prompts under 200 chars | Peec hard limit — list any over | | Topics enable funnel slicing | Topics named after funnel stages OR by clear analytical axis (offer, audience). Flag topics that are pure themes ("AI", "SEO") with no slicing value | | Tags are richer than the default 4 | If only branded/non-branded/informational/transactional exist → no offer/persona slicing possible | | Brand aliases handle Umlauts | Any brand with Umlauts in name but no ASCII alias ("Stürkat" without "Stuerkat" alias) → matching fails on chats | | Hero prompt identified | setup_state.hero_prompt_id set OR clearly inferrable from getbrandreport; flag if not |

Output: a Setup Health Score = % of checks passing, plus the bulleted findings (severity P0/P1/P2).

2. Brand-performance snapshot (read-only mirror of Phase 9)

own_brand_id = first brand whose domain matches setup_state.domain
              (or whose name == own_domain root); if ambiguous, ASK once

# Per-stage visibility
mcp__peec-ai__get_brand_report(
  project_id, start_date, end_date,
  dimensions=["topic_id"],
  filters=[{field: "brand_id", operator: "in", values: [own_brand_id]}]
)

# Per-engine visibility
mcp__peec-ai__get_brand_report(
  project_id, start_date, end_date,
  dimensions=["model_id"],
  filters=[{field: "brand_id", operator: "in", values: [own_brand_id]}]
)

# Per-prompt — find winners + losers
mcp__peec-ai__get_brand_report(
  project_id, start_date, end_date,
  dimensions=["prompt_id"],
  filters=[{field: "brand_id", operator: "in", values: [own_brand_id]}]
)

# Source diversity (how many distinct sources is the brand cited from)
mcp__peec-ai__get_url_report(
  project_id, start_date, end_date,
  dimensions=["url"],
  filters=[{field: "brand_id", operator: "in", values: [own_brand_id]}],
  limit=50
)

# Competitor delta — strongest opposition per topic
mcp__peec-ai__get_brand_report(
  project_id, start_date, end_date,
  dimensions=["topic_id", "brand_id"]
)

Compute:

• Visibility now — overall % + per stage + per engine
• Hero prompts winning — prompts where own_brand visibility > 50% (top 5)
• Hero prompts losing — prompts where own_brand visibility = 0 AND a competitor visibility > 30% (top 5)
• Funnel weakness — the stage with the lowest visibility (and which competitor dominates it)
• Engine weakness — the engine where the brand is invisible (chatgpt vs perplexity vs google-ai-overview)
• Source diversity — count of distinct domains the brand is cited from; 15 = healthy

If the project has 4 weeks) | | strategic_fit (0–3) | 3 = fixes funnel weakness from §2 OR aligns to user's prior setup_state.notes / SkillMind priors; 1 = generic |

Multiplicative — anything with a 0 in any dimension is dropped (those are noise).

Take top top_n (default 5). For each, output:

• One-sentence action
• Which signal in §1 / §2 caused it (causal trace, not just "Peec said so")
• Suggested handoff skill (/peec-content-intel, /peec-outreach, /peec-setup partial:)
• Estimated effort (S/M/L)
• Estimated 4-week metric impact (visibility delta on which prompt or zone)

Always include at least one structural improvement (from §1) if the Setup Health Score is /checkups/YYYY-MM-DD_checkup.md` (create dir if missing) and stream to user. See §6 schema.

End with one decisive sentence: "Empfohlene nächste Aktion: " — the single most leveraged item from §4.

---

6. Output schema

# Peec Checkup —  · 

## TL;DR
- Visibility now: **** (was % N days ago — only if prior checkup exists)
- Setup health: **** ( P0 issues,  P1)
- Strongest funnel:  () · Weakest:  ()
- Top competitor on weak stage: 
- Recommended next action: 

## 0. Inventory (counts as of )

| Bucket | Count | Notes |
|---|---|---|
| Brands tracked |  | own=1 · competitors= · invisible candidates= |
| Prompts total |  | active= · paused= |
| · Awareness |  |  |
| · Consideration |  |  |
| · Decision |  |  |
| · Retention |  |  |
| · Unclassified |  | flag if >0 — funnel-stage missing |
| Topics |  | named:  |
| Tags |  | non-default:  |
| Chats analysed in window |  | per engine: chatgpt= · perplexity= · gao= |
| Window |  | days_with_data= |

If `days_with_data )

### P0 — must fix (block valid measurement)
-  — evidence: 

### P1 — should fix (skews insights)
-  — evidence: 

### P2 — nice to have
- 

## 2. Brand performance now (window: )

### Visibility per funnel stage
| Stage | Visibility | Top competitor (delta) |
|---|---|---|
| Awareness | X% | comp.de (-Y%) |
| Consideration | … | … |
| Decision | … | … |
| Retention | … | … |

### Visibility per engine
| Engine | Visibility |
|---|---|
| chatgpt-scraper | X% |
| perplexity-scraper | … |
| google-ai-overview-scraper | … |

### Hero prompts — winning (top 5)
1. **** — Y% visibility, mostly via  · sources: 

### Hero prompts — losing (top 5)
1. **** — 0% visibility · top competitor:  at  · cited URL type: 

### Source diversity
 distinct source URLs · top sources:  · health: 

## 3. Top  improvements (priority-ranked)

### #1 — 
- **Why now:** 
- **Handoff:** 
- **Effort:** 
- **4-week metric:** 

### #2 …

## Recommended next action
**** — because .

---
*Read-only checkup. No Peec data was modified. State file: .*

---

Guardrails

• Never call mcp__peec-ai__create_* or delete_* or update_*. Pure read.
• Never write setup_state.json. Only peec-setup writes it. If state was missing, the report tells the user to run /peec-setup partial:import to persist findings.
• Never invent insights from 8 improvements. If 50 candidates score similarly, the scoring is wrong — re-tighten thresholds, don't widen output.

Relationship to other skills

/peec-checkup
   │ (read-only diagnosis)
   ↓
   reports → user decides
   │
   ├── if structural P0 → /peec-setup (partial / audit)
   ├── if specific prompt to win → /peec-content-intel
   ├── if outreach gaps → /peec-outreach
   ├── if you want ONE decisive next move → /peec-agent
   └── if you want time-series + attribution → /peec-report (needs 4+ weeks)

/peec-start may route to /peec-checkup when the user's intent is observational ("how am I doing?") rather than action-driven ("what should I do?"). The two are complementary, not redundant: checkup is the lens, growth-agent is the trigger.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AntonioBlago
• Source: AntonioBlago/peec-ai-skills
• License: MIT
• Homepage: https://antonioblago.de

Install and usage instructions live in the source repository linked above.