# Peec Checkup

> Read-only health check for an existing Peec AI project. In one pass produces (1) a setup-quality audit (red flags from the structural setup — wrong competitors, funnel gaps, taxonomy issues), (2) a brand-performance snapshot (visibility per stage / engine, hero prompts winning vs losing, source diversity, competitor delta), and (3) a priority-ranked list of 5–8 concrete improvements drawn from Pe…

- **Type:** Skill
- **Install:** `agentstack add skill-antonioblago-peec-ai-skills-peec-checkup`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AntonioBlago](https://agentstack.voostack.com/s/antonioblago)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AntonioBlago](https://github.com/AntonioBlago)
- **Source:** https://github.com/AntonioBlago/peec-ai-skills/tree/main/skills/peec-checkup
- **Website:** https://antonioblago.de

## Install

```sh
agentstack add skill-antonioblago-peec-ai-skills-peec-checkup
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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/SETUP_STATE.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 get_brand_report; 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

```markdown
# 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](https://github.com/AntonioBlago)
- **Source:** [AntonioBlago/peec-ai-skills](https://github.com/AntonioBlago/peec-ai-skills)
- **License:** MIT
- **Homepage:** https://antonioblago.de

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-antonioblago-peec-ai-skills-peec-checkup
- Seller: https://agentstack.voostack.com/s/antonioblago
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.