peec-ai-skills

Peec AI Skills for Claude Code

Production-tested Claude Code skills for Peec AI — the brand-visibility tracking platform for LLM-powered search (ChatGPT, Perplexity, Google AI Overviews, Gemini).

These skills turn a freshly-invoked Peec AI project into an operator-ready setup with the right competitors, the right prompts, a proper customer-journey taxonomy, and an actionable content pipeline — using the Peec AI MCP server, Visibly AI (GSC/GA4), and web research.

---

Quick install (60 seconds)

# 1. Clone + install all 9 skills into ~/.claude/skills/
git clone https://github.com/AntonioBlago/peec-ai-skills.git ~/peec-ai-skills
cd ~/peec-ai-skills
./claude-peec-ai.sh                 # use --copy on Windows without dev mode

# 2. Connect the Peec AI MCP (OAuth in browser on first tool call)
claude mcp add peec-ai --transport streamable-http https://api.peec.ai/mcp

# 3. Restart Claude Code, then in any directory:
#    /peec-start    →  detects state, dispatches the right skill

That's it. /peec-start reads growth_loop/setup_state.json if present, otherwise probes Peec live and either offers brownfield import or runs greenfield setup. Optional MCPs (Visibly AI, SkillMind) are documented under Prerequisites.

📑 5-minute overview: docs/presentation/peec-ai-skills-deck.pdf — 20-slide pitch + tutorial.

---

Skill system (8 skills + 1 orchestrator + 1 entry point)

Not a feature list — a closed growth loop with a cross-project memory layer underneath. Every skill has a specific job; the orchestrator (peec-agent) decides which one runs next; peec-learn lifts lessons out of one project into priors for the next.

     ┌────────────────────────────────────────────────────────┐
     │                                                        │
     │   ENTER               peec-start  (manual entry)      │
     │                       hooks/peec-detect.py (auto)      │
     │                                    ↓                   │
     │   UNDERSTAND          peec-setup              │
     │   (prompts,           peec-content-intel (demand)      │
     │    demand,                         ↓                   │
     │    taxonomy)                                           │
     │                                                        │
     │   DIAGNOSE            peec-checkup                     │
     │   (read-only          (setup health + brand snapshot   │
     │    health pass)        + ranked improvements)          │
     │                                    ↓                   │
     │   ANALYZE             peec-cluster          │
     │   (strategic          peec-content-intel (sources)     │
     │    zones)                          ↓                   │
     │                                                        │
     │   DECIDE    ◄──────── peec-agent (orchestrator)   │
     │   (one move)          calls /peec-checkup first        │
     │                                    ↓                   │
     │                                                        │
     │   EXECUTE             @content-write (Visibly skill)   │
     │   (build +            peec-outreach                │
     │    distribute)                     ↓                   │
     │                                                        │
     │   LEARN               peec-report             │
     │   (attribution,                    ↓                   │
     │    next moves)                                         │
     │                                                        │
     └────────→ feeds back into UNDERSTAND ───────────────────┘
                             │
                             ▼
     ┌────────────────────────────────────────────────────────┐
     │  CROSS-PROJECT MEMORY     peec-learn            │
     │  (patterns, priors)       read: priors for next loop   │
     │                           write: patterns after lift   │
     └────────────────────────────────────────────────────────┘

Skill	What it does	Credits	When to trigger
peec-start (entry point)	Single-entry slash command. Detects setup_state.json, picks the correct downstream skill (setup / checkup / agent / audit) based on state age + user intent (observational vs action). Pure dispatch — never produces deliverables itself.	free	"Where do I start?", /peec-start
peec-setup	End-to-end Peec project configuration: competitor discovery from real AI chats, forum pain-mining (Reddit, Gutefrage, t3n, OMR), customer-journey prompt design across Awareness → Consideration → Decision → Retention, and structured topic/tag taxonomy. 9 phases + Phase 0 (full / import / audit / partial / skip).	free	"Set up Peec for [client]", "My Peec competitors are wrong", "Restructure Peec topics"
peec-checkup	Read-only health pass. One report covering inventory (counts), setup-quality audit (red flags), brand-performance snapshot (visibility per stage / engine, hero prompts winning vs losing, source diversity), and 5–8 priority-ranked improvements. Never writes. Works from day 1 of data.	free	"Wo stehe ich?", "Mein Setup checken", "Verbesserungspotenziale?"
peec-content-intel	Content-intelligence workflow: Peec gap-URLs → Query Fan-Out (via mcp__visiblyai__query_fanout ≥ v0.6.0) → Reddit/forum pain mining (via Peec's scraped index, bypassing Reddit's WebFetch block) → Visibly backlinks + onpage → opportunity scoring → publish-ready content brief. 6 phases.	~10–45 Visibly cr	"Which content wins Peec prompt X?", "Build a content brief from Peec data"
peec-cluster	Turns a flat Peec prompt set into strategic topic zones — clustered by intent × funnel stage × visibility gap × demand signal. Produces 4-8 zones, each with a concrete "one move now" action and a measurable success metric. Persists zones as Peec tags for later attribution.	~5–15 cr	"I have 20+ prompts, give me a content architecture, not a calendar"
peec-outreach	Converts Peec's get_actions + forum/UGC discovery into a prioritized outreach pipeline: contact extraction, pitch templates per channel type (editorial / Reddit / Gutefrage / YouTube), tracker file, citation-gain measurement. 5 pitches/week cap by default.	free	"Content is shipped — now I need external citations"
peec-report	Weekly/monthly loop-closer: measures visibility delta per prompt/zone, attributes it to specific content + outreach investments, detects winning patterns, outputs a ≤ 400-word narrative with 3 next-actions and at least 1 "stop doing". Persists learnings for the next cycle.	free	Weekly ritual or after any major action
peec-learn	Cross-project memory layer. After a Peec skill produces a measurable outcome, extracts 1–3 transferable patterns (causal, falsifiable, evidence-backed) and persists them to SkillMind. On the next orchestrator run, recalls matching patterns as priors — lessons from project A inform decisions on project B.	free	After peec-report closes a cycle, or when a pitch / brief / zone lift is measured
peec-agent (orchestrator)	The decision-making layer. Always invokes /peec-checkup first to get inventory + setup health + brand performance, then picks one next move with a measurable 4-week metric. Hands off to the right skill with parameters pre-filled. Tells you "do exactly this now" instead of "here is a dashboard".	free	"What should I work on this week?"

All skills are user-invocable — Claude Code triggers them automatically when the conversation matches, and users can invoke them explicitly with /peec-start, /peec-setup, /peec-checkup, /peec-content-intel, /peec-cluster, /peec-outreach, /peec-report, /peec-learn, or /peec-agent.

---

Prerequisites

Required:

• Claude Code (CLI, VS Code extension, or JetBrains plugin)
• Peec AI MCP server connected (provides mcp__peec-ai__* tools — see below)

Peec AI — hosted MCP (OAuth, zero install)

Peec AI ships a remote MCP server at https://api.peec.ai/mcp with OAuth — no API key file, just a browser redirect on first use.

claude mcp add peec-ai --transport streamable-http https://api.peec.ai/mcp

…or add it directly to your Claude Code settings.json / ~/.claude.json:

{
  "mcpServers": {
    "peec-ai": {
      "type": "http",
      "url": "https://api.peec.ai/mcp"
    }
  }
}

The first time any skill calls a mcp__peec-ai__* tool, Claude Code opens a browser to sign you in to Peec AI and authorize access. Tokens persist; subsequent runs are silent. Full docs: docs.peec.ai/mcp/setup.

Optional but strongly recommended:

Visibly AI — hosted MCP (zero install)

Visibly AI is a remote MCP server — no pip install required. Just add the connection to your Claude Code settings.json:

{
  "mcpServers": {
    "visiblyai": {
      "type": "http",
      "url": "https://mcp.visibly-ai.com/mcp",
      "headers": {
        "Authorization": "Bearer lc_your_key"
      }
    }
  }
}

Get your API key under Account → API Keys. Without the Authorization header, only the 8 free tools are available. Full developer docs: antonioblago.com/de/entwickler/mcp.

Provides: GSC / GA4 read-through, backlinks, onpage analysis, classify_keywords, and — since v0.6.0 — the query_fanout coverage analyzer.

SkillMind — local MCP (pip install)

SkillMind is a local MCP server that provides the cross-project memory layer used by peec-learn. Install:

pip install "skillmind[pinecone,mcp,youtube]"
# or for everything:
pip install "skillmind[all]"

Then add to Claude Code settings.json:

{
  "mcpServers": {
    "skillmind": {
      "command": "python",
      "args": ["-m", "skillmind.mcp.server"],
      "env": {
        "PINECONE_API_KEY": "your-pinecone-key",
        "SKILLMIND_BACKEND": "pinecone",
        "ANTHROPIC_API_KEY": "your-anthropic-key"
      }
    }
  }
}

Credentials can also live in a .env file in your project root instead of the env block. Repo: github.com/AntonioBlago/skillmind.

How skills remember setup (setup_state.json)

Setup is expensive — discovering competitors from real AI chats, designing 20 funnel-spread prompts, building taxonomy. You don't want it re-run from scratch every time the orchestrator asks "what next?". So the skills share one state file:

<project>/growth_loop/setup_state.json

• peec-setup owns it: reads at Phase 0 to decide full | audit | partial | skip, writes at Phase 9 with merged phases + a fresh count snapshot + the resolved target_country / prompt_language.
• All other skills (peec-agent, peec-content-intel, peec-cluster, peec-outreach, peec-report) refuse to run without it. If the file is missing, they output one line:

  No Peec setup state found at <project>/growth_loop/setup_state.json. Run /peec-setup first.

This means: every consumer skill knows the project ID, the language to write briefs in, the country to filter SERPs by, and which forums to mine — without re-asking you and without silently defaulting to English. Setup older than 90 days triggers a warning; older than that without audit mode is a yellow flag in any output.

Schema and full read/write protocol: skills/_shared/SETUP_STATE.md.

Auto-detection: /peec-start + hooks

Two ways the right next move surfaces without you remembering which of 7 skills to call:

1. /peec-start — slash command (manual entry point) Always-safe single command. Reads setup_state.json, optionally probes Peec live, then hands off:

/peec-start
   │
   ├── no state, Peec empty       → /peec-setup (full)
   ├── no state, Peec populated   → /peec-setup (import)
   ├── state present, < 90 days   → /peec-agent
   ├── state present, > 90 days   → /peec-setup (audit)
   └── state has missing phases   → /peec-setup (partial:<phase>)

Use this when you forget the right starting skill or a hook isn't installed.

2. Hooks — automatic context injection Two hooks in ~/.claude/settings.json wrap hooks/peec-detect.py. The script is silent unless it has something to say — it never pollutes non-Peec sessions.

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "python \"<repo>/hooks/peec-detect.py\"",
        "timeout": 10,
        "statusMessage": "Peec context check..."
      }]
    }],
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "python \"<repo>/hooks/peec-detect.py\" --session-start",
        "timeout": 10,
        "statusMessage": "Peec setup state..."
      }]
    }]
  }
}

Trigger	Behavior
Session opens in a dir with growth_loop/setup_state.json (own dir or up to 2 parents)	Injects state summary + recommended skill into Claude's context
Session opens elsewhere	Silent
Prompt mentions a Peec keyword (peec, sichtbarkeit, ai visibility, /peec-start, …)	Injects setup hint or current state
Prompt is unrelated	Silent

Output is a JSON envelope (hookSpecificOutput.additionalContext) per the Claude Code hook schema — Claude sees it as system context and decides whether to act.

If you change the hook config, run /hooks once or restart Claude Code so the settings watcher reloads.

Tool matrix

Phase	MCP tool	Provider	Credits	Used by
1 · Gap URLs	mcp__peec-ai__get_url_report (filter gap > 0)	Peec	free	content-intel
1 · Brands & prompts	mcp__peec-ai__list_brands / list_prompts / list_topics / list_tags	Peec	free	visibility-setup
2 · Query Fan-Out + coverage	mcp__visiblyai__query_fanout	Visibly ≥ 0.6.0	~3-5	content-intel (primary), visibility-setup (optional)
3 · Chat mining (competitors + language)	mcp__peec-ai__list_chats → get_chat	Peec	free	visibility-setup
3 · Reddit / forum content	mcp__peec-ai__get_url_content (Peec has already scraped Reddit)	Peec	free	both
4 · GSC keywords	mcp__visiblyai__get_keywords / query_search_console	Visibly	0 (via GSC)	visibility-setup
4 · Backlinks & authority	mcp__visiblyai__get_backlinks	Visibly	variable	content-intel
4 · 24-point OnPage audit	mcp__visiblyai__onpage_analysis	Visibly	15	content-intel
4 · Keyword intent + funnel	mcp__visiblyai__classify_keywords	Visibly	1	both
5 · Brand CRUD	mcp__peec-ai__create_brand / delete_brand	Peec	free	visibility-setup
5 · Prompt CRUD	mcp__peec-ai__create_prompt / update_prompt / delete_prompt	Peec	free	visibility-setup
6 · Topic/Tag CRUD	mcp__peec-ai__create_topic / create_tag / delete_topic	Peec	free	visibility-setup
7 · Recommendations	`mcp__peec-ai__get_actions(scope=overview	owned	editorial	ugc)`

Graceful degradation

The skills work even when pieces are missing:

• Without Visibly AI: the skills still do the Peec-side setup, competitor discovery from chats, Reddit / forum mining via Peec's scraped index, and taxonomy setup. They skip: GSC keyword mapping (Phase 4 of visibility-setup) and coverage analysis (Phase 2 of content-intel). The content brief is still generated, just without depth / coverage scores.
• Without query_fanout (Visibly MCP < 0.6.0): the content-intel skill falls back to an inline 6-axis heuristic (synonym, decision, comparison, problem, long-tail, forum). Coverage matching is skipped.
• Without classify_keywords: funnel-stage detection drops to keyword pattern matching inside the SKILL.md logic.
• Without SkillMind: peec-learn falls back to appending patterns to <project>/growth_loop/patterns.md and flags the skip. The orchestrator skips the cross-project recall call in Phase 1 — patterns are a bonus prior, not a requirement.

---

Install

The repo ships with claude-peec-ai.sh — a single script that installs all 7 skills into ~/.claude/skills/ (or a target you choose). Symlink by default; git pull in the repo then updates every installed skill in place.

git clone https://github.com/AntonioBlago/peec-ai-skills.git ~/peec-ai-skills
cd ~/peec-ai-skills
./claude-peec-ai.sh                           # symlink all 7 skills into ~/.claude/skills/

Flags:

./claude-peec-ai.sh --copy                    # copy instead of symlink (no git-pull updates)
./claude-peec-ai.sh --target ./.claude        # per-project install (project-local .claude/)
./claude-peec-ai.sh --force                   # overwrite existing skill dirs
./claude-peec-ai.sh --dry-run                 # preview, no filesystem changes
./claude-peec-ai.sh --uninstall               # remove the 7 skill entries
./claude-peec-ai.sh --only peec-learn,peec-agent   # partial install

Symlink mode on Windows needs either Developer Mode or admin rights; the script falls back to copy automatically if the symlink call fails. On WSL / Git Bash it usually just works.

Verify

Start a Claude Code session and type:

/peec-setup

If the skill registers, Claude Code picks it up and the workflow begins.

---

Usage examples

Set up Peec for a new client project

Set up Peec for example.com — SEO retainer offer, focused on DACH E-Commerce

Claude Code invokes peec-setup and walks through all 9 phases: initial audit, competitor discovery from chat history, forum pain-mining, customer-journey prompt design, taxonomy setup, reporting.

Build a content brief from an underperforming prompt

Peec prompt pr_abc123 has 0% visibility — analyze what I need to rank

Claude Code invokes peec-content-intel: pulls gap-URLs, runs Query Fan-Out, extracts pain-point quotes from forum threads Peec already scraped, scores competitor URLs, outputs a publish-ready content brief.

---

How the skills work under the hood

Claude Code skills are markdown workflow definitions with YAML frontmatter. The AI reads the SKILL.md content as a playbook and orchestrates the tool calls interactively — no additional Python or JavaScript runtime is required.

Both skills reference MCP tools that must exist in your Claude Code environment:

Tool family	Provider	Example calls used by these skills
mcp__peec-ai__*	Peec AI MCP	list_projects, get_url_report, get_chat, list_chats, get_url_content, create_brand, create_prompt, list_tags
mcp__visiblyai__*	Visibly AI MCP (hosted, optional)	get_google_connections, query_search_console, get_keywords, get_backlinks, onpage_analysis, classify_keywords, query_fanout
mcp__skillmind__*	SkillMind MCP (local, optional)	add_pattern, remember, recall, list_patterns, update_memory, consolidate, export_obsidian
Built-in	Claude Code	WebSearch, WebFetch, Read, Write, Edit, Bash

If any MCP tool is missing when a skill runs, the skill explicitly states which step is being skipped and continues with the remaining ones.

---

Design principles

• Evidence over narrative. Every prompt, competitor, and content recommendation is grounded in actual AI chat responses (via Peec's scraped history) or forum data — never invented.
• Funnel-complete. Prompts are designed across Awareness → Consideration → Decision → Retention; single-stage setups are flagged as a red flag in phase 1.
• Buyer language. Forum pain points are quoted verbatim, never paraphrased into marketing-speak.
• Credit-aware. Visibly AI and paid MCP calls are budgeted; heuristic fallbacks exist for every credit-costly step.
• Idempotent. Re-running a skill on the same project updates without duplicating (uses Peec's content-hash checks and upsert semantics).

---

Contributing

Found a better prompt template, a new forum to mine, or a scoring formula improvement? PRs welcome.

• Keep SKILL.md files under 600 lines; long appendices go into skills/<name>/appendix/*.md.
• Frontmatter must include name, description, user-invocable: true.
• German and English triggers both welcome — German community is primary.

---

License

MIT © Antonio Blago — Neuro-SEO System®

---

See also

• Peec AI — the platform these skills integrate with
• visiblyai-mcp-server — companion MCP server for GSC / backlinks / OnPage data
• Claude Code skills documentation