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\]](https://docs.openclaw.ai/tools/skills), [\[openclaws.io\]](https://openclaws.io/docs/tools/skills/), [\[deepwiki.com\]](https://deepwiki.com/lekt9/openclaw-foundry/5.1-skill-format-and-structure) [\[clawdocs.org\]](https://clawdocs.org/guides/skill-development/), [\[deepwiki.com\]](https://deepwiki.com/lekt9/openclaw-foundry/5.1-skill-format-and-structure)

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`

```markdown
---
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`

```markdown
---
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`

```markdown
---
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`

```markdown
---
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`

```markdown
---
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`

```markdown
---
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`

```markdown
---
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`

```markdown
---
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`

```markdown
---
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`

```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\]](https://docs.openclaw.ai/tools/skills), [\[openclaws.io\]](https://openclaws.io/docs/tools/skills/)
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\]](https://mermaid.ai/open-source/syntax/flowchart.html), [\[emersonbot....github.io\]](https://emersonbottero.github.io/mermaid-docs/syntax/flowchart.html) [\[docs.merma...viewer.com\]](https://docs.mermaidviewer.com/diagrams/sequence.html), [\[mermaid.ai\]](https://mermaid.ai/open-source/syntax/examples.html), [\[emersonbot....github.io\]](https://emersonbottero.github.io/mermaid-docs/syntax/sequenceDiagram.html)

***

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

```mermaid
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.

``` mermaid
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\]](https://docs.mermaidviewer.com/diagrams/sequence.html), [\[mermaid.ai\]](https://mermaid.ai/open-source/syntax/examples.html), [\[emersonbot....github.io\]](https://emersonbottero.github.io/mermaid-docs/syntax/sequenceDiagram.html)

***