DBAdmin/docs___/seo/seo_skill.md

Kompletny pakiet OpenClaw SKILL w układzie router + sub‑skills, gotowy do skopiowania jako katalogi z SKILL.md.

Oparłem format o to, że OpenClaw skill to katalog zawierający SKILL.md z YAML frontmatter + instrukcje, a skills są ładowane m.in. z <workspace>/skills oraz ~/.openclaw/skills (z priorytetem workspace > local > bundled).
W samym pliku frontmatter typowo występują pola jak name, description, opcjonalnie version, trigger, tools itd. [docs.openclaw.ai], [openclaws.io], [deepwiki.com] [clawdocs.org], [deepwiki.com]

Dodatkowo w QA uwzględniłem bramki SEO, które przewijają się w materiałach typu “SEO recommendations / requirements”: m.in. duplicate content, canonicalization, pagination, structured data, IA, on‑page, performance, mobile-first.

---

1) Struktura katalogów (wklej do <workspace>/skills/)

skills/
  seo-ai-router/
    SKILL.md
    artifacts/
      brief.schema.json
      research.schema.json
      outline.schema.json
      draft.schema.json
      qa.schema.json

  seo-research/
    SKILL.md

  seo-outline/
    SKILL.md

  seo-writer/
    SKILL.md

  seo-onpage/
    SKILL.md

  seo-schema/
    SKILL.md

  seo-qa-gates/
    SKILL.md

  seo-publish/
    SKILL.md

  seo-measure-refresh/
    SKILL.md

---

2) Router SKILL — skills/seo-ai-router/SKILL.md

---
name: seo-ai-router
version: 1.0.0
description: Router i orkiestrator procesu tworzenia tresci SEO per etap customer journey (Inicjacja->Badania->Porownywanie->Transakcja->Doswiadczenie) z artefaktami JSON i bramkami QA.
trigger: "seo pipeline|seo workflow|customer journey|inicjacja|badania|porownywanie|transakcja|doswiadczenie|checklista seo|seo machine"
tools: [filesystem, browser, http, shell]
---

# SEO AI Router (Customer Journey)

## Cel
Gdy uzytkownik prosi o tresc SEO, strategie, checklisty, artykul, landing, porownanie lub material pod dowolny etap sciezki zakupowej,
ten skill ma:
1) wykryc etap i intencje,
2) wygenerowac artefakty (Brief -> Research -> Outline -> Draft -> OnPage -> Schema -> QA -> Publish -> Measure),
3) wywolac (konceptualnie) sub-skills w odpowiedniej kolejnosci.

## Kiedy uzywac
Aktywuj, gdy prosba dotyczy:
- tworzenia/planowania tresci SEO,
- dopasowania do intencji/funnel/journey,
- przygotowania materialu “pod AI/agentow”,
- wdrozenia procesu content ops (research->publish->refresh).

## Detekcja etapu (reguly)
- Inicjacja: definicje, "co to jest", edukacja, problem
- Badania: rankingi, opinie, przewodniki zakupowe
- Porownywanie: "X vs Y", alternatywy, tabele, kalkulatory
- Transakcja: "kup", "cena", "gdzie kupic", landing/product/pricing
- Doswiadczenie: instrukcje, KB, troubleshooting, posprzedaz

Jesli niejasne: przyjmij Badania jako domysl i w brief oznacz `stage_confidence: low`.

## Kontrakt artefaktow (pliki lub bloki w odpowiedzi)
W kazdym kroku generuj JSON zgodny z prostym schematem:
- `brief.json`
- `research.json`
- `outline.json`
- `draft.md` (lub html)
- `onpage.json`
- `schema.jsonld`
- `qa.json`
- `publish.json`
- `measure.json`

## Orkiestracja (kolejnosc sub-skills)
1) Uruchom **seo-research**
2) Uruchom **seo-outline**
3) Uruchom **seo-writer**
4) Uruchom **seo-onpage**
5) Uruchom **seo-schema**
6) Uruchom **seo-qa-gates**
7) Uruchom **seo-publish**
8) Uruchom **seo-measure-refresh**

## Wyjscie finalne dla uzytkownika
Zawsze zwroc:
- gotowy artefakt docelowy (np. artykul/landing/KB),
- oraz komplet JSON-ow (albo “bundle” w jednej odpowiedzi),
- oraz liste decyzji: etap, intencja, target, CTA, linkowanie wewn.

## Notatka o snippetach (meta)
Pamietaj: snippet w wynikach wyszukiwania jest zwykle generowany z tresci strony, ale meta description moze zostac uzyte, gdy lepiej opisuje strone.
Uwzglednij to w kroku seo-onpage.

---

3) Sub-skill: Research — skills/seo-research/SKILL.md

---
name: seo-research
version: 1.0.0
description: Research SEO: intencja, pytania, katy, konkurencja, mapa slow kluczowych pod etap customer journey.
trigger: "seo research|intencja|paa|faq|konkurencja|serp"
tools: [browser, http]
---

# SEO Research Agent

## Wejscie
Oczekuj `brief.json`:
- stage, persona, intent, topic, geo/lang, KPI

## Kroki
1) Okresl primary intent: informational / commercial / transactional / navigational.
2) Zbierz liste pytan (FAQ/PAA style) + obiekcje + synonimy.
3) Zaproponuj 3-5 katow (angles) dopasowanych do etapu:
   - Inicjacja: edukacja, definicja, problem->rozwiazanie
   - Badania: metodologia, kryteria, ranking
   - Porownywanie: roznice, trade-offs, "dla kogo"
   - Transakcja: wartosc, oferta, dowody, CTA
   - Doswiadczenie: diagnoza, kroki naprawy, KB
4) Zbuduj mapowanie: query cluster -> sekcje strony (H2/H3).
5) Zapisz `research.json`.

## Output: research.json (minimal)
{
  "stage": "...",
  "intent": "...",
  "topic": "...",
  "keyword_clusters": [
    {"cluster":"...", "queries":["..."], "notes":"..."}
  ],
  "questions": ["..."],
  "objections": ["..."],
  "angles": ["..."],
  "internal_links_suggested": {
    "prev_stage": ["..."],
    "next_stage": ["..."]
  }
}

---

4) Sub-skill: Outline — skills/seo-outline/SKILL.md

---
name: seo-outline
version: 1.0.0
description: Buduje outline H1-H3 + FAQ + plan linkowania wewnetrznego na podstawie research.
trigger: "outline|struktura|h2|h3|plan tresci"
tools: [filesystem]
---

# SEO Outline Agent

## Wejscie
`research.json`

## Kroki
1) Stworz H1 zgodny z intencja.
2) Zaprojektuj H2/H3 tak, by:
   - w pierwszych sekcjach odpowiadac “wprost” na potrzebe,
   - pokrywac klastry slow kluczowych,
   - dodac FAQ (Q/A).
3) Dodaj sekcje “dla kogo”, “kiedy wybrac”, “alternatywy” jesli etap >= Badania.
4) Ustal CTA i linki do poprzedniego/nastepnego etapu.

## Output: outline.json
{
  "h1": "...",
  "sections": [
    {"h2":"...", "h3":["..."], "intent_note":"..."}
  ],
  "faq": [{"q":"...", "a_hint":"..."}],
  "cta": {"primary":"...", "secondary":"..."},
  "internal_links": [{"anchor":"...", "target":"..."}]
}

---

5) Sub-skill: Writer — skills/seo-writer/SKILL.md

---
name: seo-writer
version: 1.0.0
description: Pisze draft na podstawie outline; dodaje TLDR, przyklady, sekcje dopasowane do etapu.
trigger: "napisz|draft|artykul|landing|kb"
tools: [filesystem]
---

# SEO Writer Agent

## Wejscie
`outline.json`

## Kroki
1) Napisz wersje 1 w Markdown:
   - TLDR na gorze (2-5 zdan)
   - H2/H3 zgodnie z outline
2) Styl:
   - Inicjacja: edukacyjnie, bez sprzedazy
   - Badania: kryteria + metodologia + rekomendacje
   - Porownywanie: trade-offs, tabela roznic (tekstowo)
   - Transakcja: wartosc, dowody, CTA
   - Doswiadczenie: szybka diagnoza + kroki
3) Dodaj sekcje FAQ.
4) Dodaj placeholdery do linkow wewnetrznych.

## Output
- `draft.md`
- `draft.json` (opcjonalnie): streszczenie + kluczowe tezy

---

6) Sub-skill: On-page — skills/seo-onpage/SKILL.md

---
name: seo-onpage
version: 1.0.0
description: On-page SEO: title, meta description, naglowki, link text, IA, canonical/pagination checklist.
trigger: "meta title|meta description|onpage|optymalizacja"
tools: [filesystem]
---

# SEO On-page Agent

## Wejscie
`draft.md` + `research.json`

## Kroki
1) Uloz Title i Meta Description:
   - unikalne,
   - zgodne z intencja,
   - streszczaja i zachecaja (meta moze byc uzyte jako snippet, gdy lepiej opisuje strone niz fragment tresci). 
2) Sprawdz zgodnosc H1/H2/H3 z klastrami.
3) Popraw linki wewnetrzne:
   - anchor text opisowy,
   - logiczny flow prev/next stage.
4) Zapisz `onpage.json`:
   - title, description,
   - link plan,
   - uwagi do IA.
5) Dodaj tech-checklist:
   - duplicate content / canonical / pagination / indexing. 

## Output: onpage.json
{
  "title": "...",
  "meta_description": "...",
  "internal_links": [{"anchor":"...", "target":"..."}],
  "tech_notes": ["duplicate content", "canonical", "pagination", "indexing"]
}

---

7) Sub-skill: Structured Data — skills/seo-schema/SKILL.md

---
name: seo-schema
version: 1.0.0
description: Dobiera i generuje JSON-LD (FAQ/HowTo/Product/Offer/Breadcrumb) na podstawie typu strony.
trigger: "schema|json-ld|structured data|faq schema|howto schema"
tools: [filesystem]
---

# SEO Schema Agent

## Wejscie
`draft.md` + `onpage.json` + stage

## Kroki
1) Dobierz typ:
   - FAQPage: gdy masz realne Q/A
   - HowTo: gdy masz kroki
   - Product/Offer: gdy to strona produktu/oferty
   - BreadcrumbList: gdy to strona w hierarchii
2) Wygeneruj `schema.jsonld` jako JSON-LD.
3) Dodaj notatke: structured data wspiera rich results i “zrozumienie” tresci przez wyszukiwarki. 

## Output
- `schema.jsonld`

---

8) Sub-skill: QA Gates — skills/seo-qa-gates/SKILL.md

---
name: seo-qa-gates
version: 1.0.0
description: Bramki jakosci SEO: intencja, duplikacja/canonical/pagination, structured data, linki, mobile-first, performance.
trigger: "qa seo|bramki|quality gates|audit"
tools: [filesystem]
---

# SEO QA Gates Agent

## Wejscie
`draft.md` + `onpage.json` + `schema.jsonld`

## Bramki (PASS/FAIL + fixlist)
1) Intent match: czy tresc odpowiada na intencje etapu?
2) Meta: Title/Description unikalne i zgodne z trescia. 
3) Tech: duplicate content, canonicalization, pagination, indexing. 
4) Structured data: czy pasuje do strony i jest sensowne. 
5) Linki: opisowy anchor text + crawlable (typowy problem w audytach). 
6) Mobile-first + performance (traktuj jako release gate). 

## Output: qa.json
{
  "status": "pass|fail",
  "checks": [
    {"name":"intent", "status":"pass|fail", "notes":"..."},
    {"name":"meta", "status":"pass|fail", "notes":"..."},
    {"name":"tech", "status":"pass|fail", "notes":"..."},
    {"name":"schema", "status":"pass|fail", "notes":"..."},
    {"name":"links", "status":"pass|fail", "notes":"..."},
    {"name":"mobile_perf", "status":"pass|fail", "notes":"..."}
  ],
  "fixlist": ["..."]
}

---

9) Sub-skill: Publish — skills/seo-publish/SKILL.md

---
name: seo-publish
version: 1.0.0
description: Przygotowanie do publikacji: URL, breadcrumbs, mapowanie do kategorii, plan indeksacji, checklist pre-publish.
trigger: "publish|publikuj|wdroz|deploy content"
tools: [filesystem]
---

# SEO Publish Agent

## Wejscie
`qa.json` + `draft.md` + `onpage.json` + `schema.jsonld`

## Reguly
- Jesli QA fail: nie publikuj, zwroc fixlist.
- Jesli QA pass:
  1) Zaproponuj slug URL (ASCII, krotki).
  2) Zapisz paczke: content + schema + meta.
  3) Zapisz `publish.json` z polami:
     - url_slug
     - breadcrumbs
     - next_refresh_hint

## Output: publish.json
{
  "url_slug": "...",
  "breadcrumbs": ["...","..."],
  "publish_notes": ["..."],
  "next_refresh_hint": "..."
}

---

10) Sub-skill: Measure & Refresh — skills/seo-measure-refresh/SKILL.md

---
name: seo-measure-refresh
version: 1.0.0
description: Pomiar i refresh: sygnaly z ruchu, CTR, nowe pytania, plan aktualizacji, retarget do kolejnego etapu.
trigger: "measure|refresh|aktualizacja|performance review seo"
tools: [filesystem]
---

# SEO Measure & Refresh Agent

## Wejscie
`publish.json` + KPI z brief

## Kroki
1) Zdefiniuj “refresh triggers”:
   - spadek CTR,
   - zmiana intencji,
   - nowe pytania,
   - nowy konkurent/format SERP.
2) Zaproponuj plan refresh:
   - update meta,
   - rozbudowa FAQ,
   - dodanie sekcji porownawczej lub CTA do kolejnego etapu.
3) Output `measure.json`.

## Output: measure.json
{
  "signals": ["..."],
  "hypotheses": ["..."],
  "refresh_actions": ["..."],
  "next_review_window": "..."
}

---

11) (Opcjonalnie) Minimalne schematy JSON (router artifacts)

Jeśli chcesz walidować artefakty, wrzuć te pliki do skills/seo-ai-router/artifacts/. To są ultra-proste schematy (bez zależności).

brief.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["stage", "topic", "intent"],
  "properties": {
    "stage": {"type": "string"},
    "topic": {"type": "string"},
    "intent": {"type": "string"},
    "persona": {"type": "string"},
    "kpi": {"type": "array", "items": {"type": "string"}},
    "stage_confidence": {"type": "string"}
  }
}

(Pozostałe schematy mogę Ci dopisać analogicznie, ale już teraz masz “działający” pakiet — OpenClaw nie wymaga schematów, to tylko Twoje QA/porządek.)

---

Jak tego używać (praktycznie, bez filozofii)

1. Skopiuj katalogi do <workspace>/skills/ (to ma najwyższy priorytet ładowania skills). [docs.openclaw.ai], [openclaws.io]
2. W rozmowie piszesz np.:
   • „Zrob mi content pod etap Porownywanie dla [temat]”
   • „Przygotuj landing pod Transakcja dla [produkt]”
   • „Zrob KB pod Doswiadczenie: jak naprawic [problem]”

Router ma wtedy poprowadzić agentową sekwencję i zwrócić paczkę artefaktów.

---

Mała uwaga techniczna: w Mermaid nie używaj słowa end jako tekstu w węźle flowchart (potrafi „wywalić” parser) — lepiej END albo [END].
Dla sequenceDiagram alt/else/loop są wspierane wprost. [mermaid.ai], [emersonbot....github.io] [docs.merma...viewer.com], [mermaid.ai], [emersonbot....github.io]

---

1) Diagram (Flowchart): Router + artefakty + QA gates + retry loop

flowchart TD

  %% =========================
  %% ENTRY
  %% =========================
  U[User request: temat + cel] --> R0[Router: detect stage + intent]
  R0 --> D1{Stage detected?}
  D1 -->|yes| BR[brief.json]
  D1 -->|no| BR_LOW[brief.json + stage_confidence=low]

  %% =========================
  %% STAGE MAP (customer journey)
  %% =========================
  subgraph ST["Stage map"]
    S1[Inicjacja]
    S2[Badania]
    S3[Porownywanie]
    S4[Transakcja]
    S5[Doswiadczenie]
    S1 --> S2 --> S3 --> S4 --> S5
  end

  BR --> ST
  BR_LOW --> ST

  %% =========================
  %% PIPELINE
  %% =========================
  subgraph PL["AI Pipeline (artefakty)"]
    direction TB
    P1[seo-research] --> A1[research.json]
    A1 --> P2[seo-outline] --> A2[outline.json]
    A2 --> P3[seo-writer] --> A3[draft.md]
    A3 --> P4[seo-onpage] --> A4[onpage.json]
    A4 --> P5[seo-schema] --> A5[schema.jsonld]
    A5 --> P6[seo-qa-gates] --> A6[qa.json]
    A6 --> DEC_QA{QA status?}
  end

  BR --> P1
  BR_LOW --> P1

  %% =========================
  %% QA BRANCHING + FIX LOOP
  %% =========================
  DEC_QA -->|pass| P7[seo-publish] --> A7[publish.json]
  DEC_QA -->|fail| FIX[Fixlist: what to change]
  FIX --> P3

  %% =========================
  %% PUBLISH + MEASURE
  %% =========================
  A7 --> P8[seo-measure-refresh] --> A8[measure.json]
  A8 --> DEC_REFRESH{Refresh needed?}
  DEC_REFRESH -->|yes| P1
  DEC_REFRESH -->|no| OUT[Output bundle: content + JSON artifacts]

  %% =========================
  %% QA GATES DETAILS (what QA checks)
  %% =========================
  subgraph QA["QA Gates (co sprawdzamy)"]
    direction TB
    Q1[Intent match: etap vs tresc]
    Q2[Meta: title + description unique]
    Q3[Tech: duplicate/canonical/pagination/indexing]
    Q4[Structured data: FAQ/HowTo/Product when fits]
    Q5[Links: opisowe + crawlable]
    Q6[Mobile-first + performance]
  end

  P6 --> QA

Dlaczego to jest „bardziej szczegółowe”:

• Masz artefakty jako węzły (brief.json, research.json, outline.json, draft.md, onpage.json, schema.jsonld, qa.json, publish.json, measure.json)
• Jest gałąź QA pass/fail oraz pętla naprawcza (wracasz do seo-writer i przechodzisz dalej)
• Jest pętla refresh po pomiarach (wraca do research, jeśli trzeba)
• Jest osobny subgraph „QA Gates” opisujący co sprawdzasz (zgodne z tym, co przewija się w checklistach SEO: duplicate/canonical/pagination/structured data/perf/mobile etc.).

2) Diagram (Sequence): Router + sub‑skills + alt/loop/opt + artefakty

Ten wariant jest „bardziej operacyjny” — pokazuje kto (który agent) co produkuje i kiedy następuje retry.

sequenceDiagram
  autonumber

  participant U as User
  participant HQ as Orchestrator
  participant R as seo-research
  participant O as seo-outline
  participant W as seo-writer
  participant S as seo-onpage
  participant SC as seo-schema
  participant Q as seo-qa-gates
  participant PB as seo-publish
  participant M as seo-measure-refresh

  U->>HQ: Request (topic, goal, stage optional)
  HQ->>HQ: Detect stage + intent
  HQ-->>U: Plan preview (stage, intent, artifacts list)

  HQ->>R: brief.json
  R-->>HQ: research.json

  HQ->>O: research.json
  O-->>HQ: outline.json

  HQ->>W: outline.json
  W-->>HQ: draft.md

  HQ->>S: draft.md + research.json
  S-->>HQ: onpage.json (title, meta, links)

  HQ->>SC: draft.md + onpage.json
  SC-->>HQ: schema.jsonld

  loop QA until pass
    HQ->>Q: draft.md + onpage.json + schema.jsonld
    Q-->>HQ: qa.json (pass/fail + fixlist)

    alt QA fail
      HQ->>W: fixlist + outline.json
      W-->>HQ: draft.md (revised)
      HQ->>S: draft.md update
      S-->>HQ: onpage.json update
      HQ->>SC: schema update if needed
      SC-->>HQ: schema.jsonld
    else QA pass
      HQ->>PB: content bundle
      PB-->>HQ: publish.json (slug, notes)
    end
  end

  opt Measure and refresh
    HQ->>M: publish.json + KPI
    M-->>HQ: measure.json (signals + refresh plan)
  end

  HQ-->>U: Final bundle (content + JSON artifacts)

loop, alt/else, opt są natywnie wspierane w Mermaid sequenceDiagram (to standardowy sposób na pokazanie retry i warunków). [docs.merma...viewer.com], [mermaid.ai], [emersonbot....github.io]

---