Umiejętność audytu SEO agenta

seo-audit — Podstawowy audyt SEO

Lekka umiejętność agenta SEO przeznaczona do szybkich, domyślnych audytów SEO pojedynczych stron. Oparta na OpenClaw. Odpowiednia do pierwszych kontroli stron lub gdy potrzebna jest szybka ocena bez pełnej głębi technicznej.

Kiedy używać tej umiejętności

Użyj seo-audit gdy:

• Użytkownik mówi: "przeprowadź audyt tej strony", "sprawdź SEO", "przeanalizuj mój URL", "szybka kontrola SEO", "co jest nie tak z moją stroną"
• Nie jest wymagana konkretna głębokość — to domyślny punkt wejścia
• Użytkownik potrzebuje szybkiego, czytelnego podsumowania zamiast pełnego technicznego rozbicia

Jeśli użytkownik potrzebuje większej głębi, przejdź do seo-audit-full:

Wskazówka: Do głębokich audytów technicznych, zaawansowanego SEO na stronie lub pełnych raportów, użyj umiejętności seo-audit-full.

Oczekiwane dane wejściowe

Jeśli podano tylko adres URL i nie ma dostępnego kodu źródłowego ani danych z crawlów, należy wyraźnie zaznaczyć:

Ograniczenie: Ten audyt opiera się wyłącznie na widocznej treści strony i publicznie dostępnych sygnałach. Kod źródłowy, dane GSC, dzienniki crawlów i metryki wydajności nie są dostępne dla tego audytu.

Wynik

Wygeneruj Podstawowy Raport Audytu SEO wypełniając szablon z assets/report-template.html, następnie zapisz go do pliku — nigdy nie wyświetlaj surowego HTML w terminalu.

Plik nazewnictwa: reports/<hostname>-<slug>-audit.html

https://example.com/blog/best-tools → reports/example-com-blog-best-tools-audit.html
https://example.com/                → reports/example-com-audit.html

Po zapisaniu powiedz użytkownikowi:

✅ Raport zapisany → reports/example-com-audit.html
   Otworzyć teraz? (tak / nie)

Jeśli tak → uruchom: open reports/example-com-audit.html

Symbole zastępcze w szablonie — wypełnij każdy niezależnie:

Skrypty

Uruchom te skrypty przed napisaniem jakichkolwiek wniosków. Wypisują strukturalny JSON — użyj JSON bezpośrednio jako dowodu; nie pobieraj ręcznie tych samych adresów URL.

Zależności: pip install requests (parsowanie HTML używa Python stdlib)

# Krok 1: kontrola poziomu witryny (robots.txt + sitemap.xml)
python scripts/check-site.py https://example.com

# Krok 2: kontrola poziomu strony (H1, title, meta description, canonical)
python scripts/check-page.py https://example.com
# Z głównym słowem kluczowym (zalecane — umożliwia sprawdzenie obecności słowa kluczowego w H1)
python scripts/check-page.py https://example.com --keyword "running shoes"

# Opcjonalnie: pobierz surowy HTML strony do dalszej inspekcji
python scripts/fetch-page.py https://example.com --output page.html

# Krok 3: walidacja schematu JSON-LD
python scripts/check-schema.py https://example.com
# Lub z wcześniej pobranego HTML (unika zbędnego pobierania):
python scripts/check-schema.py --file page.html

Każdy skrypt kończy działanie z kodem 0 (wszystko zaliczone/ostrzeżenia) lub 1 (jakiekolwiek niepowodzenie/błąd).

ŚCISŁY ZAKRES — nie dodawaj żadnych kontroli nie wymienionych poniżej. Bez wyjątków.

Dozwolone kontrole poziomu witryny (w {{site_checks_html}}):

• robots.txt · sitemap.xml · Obsługa 404 · Kanonizacja adresów URL · i18n / hreflang

Dozwolone kontrole E-E-A-T (w {{eeat_checks_html}}):

• O nas · Kontakt · Polityka prywatności · Warunki korzystania z usługi · Media/Partnerzy (tylko jeśli występują)

Dozwolone kontrole poziomu strony (w {{page_checks_html}}), w tej dokładnej kolejności: Slug URL · Tag tytułu · Meta opis · Tag H1 · Tag kanoniczny · Tekst alternatywny obrazów · Liczba słów · Umiejscowienie słowa kluczowego · Struktura nagłówków · Linki wewnętrzne · Schemat (JSON-LD)

Logika tekstu alternatywnego obrazów:

• Parsuj znaczniki <img> ze statycznego HTML
• Zaliczone: wszystkie obrazy mają niepusty alt (obrazy dekoracyjne z alt="" są OK)
• Ostrzeżenie: jakikolwiek obraz treści nie ma atrybutu alt
• Niezweryfikowane (status-info): 0 obrazów znalezionych w statycznym HTML → prawdopodobnie renderowane przez JS, nie można zweryfikować

⛔ TWARDA ZASADA — Wyświetlaj TYLKO wiersze kontroli zdefiniowane w report-template.html. Jeśli kontrola nie znajduje się na powyższych listach dozwolonych, NIE wyświetlaj jej — nawet jeśli znajdziesz problemy. Bez wyjątków. Żadnych "bonusowych" kontroli. Żadnej improwizacji. Szablon jest jedynym źródłem prawdy. Traktuj go jako ścisłą białą listę.

Wciąż ZABRONIONE (należą do seo-audit-full): znaczniki OG · Twitter Card · znaczniki społecznościowe · Waga strony · Core Web Vitals · Robots Meta

Jak używać wyników JSON:

• Mapuj status każdego pola → pass / warn / fail / error bezpośrednio na tabelę kontroli raportu
• Użyj ciągu detail każdego pola jako punktu wyjścia dla wiersza Dowód we wnioskach
• Nie zaprzeczaj wynikom skryptu, chyba że masz dodatkowe obserwowalne dowody
• Oddziel grupy kontroli za pomocą <div class="subsection-label">Etykieta</div> wewnątrz {{site_checks_html}}: Możliwość indeksowania · Kanonizacja adresów URL · i18n / hreflang · Schemat (JSON-LD) i <div class="subsection-label">Strony zaufania E-E-A-T</div> przed {{eeat_checks_html}}

Przegląd LLM — obowiązkowy, gdy llm_review_required: true:

Skrypt oznacza pola wymagające semantycznej lub jakościowej oceny, której nie może wykonać. Nigdy nie pozostawiaj llm_review_required: true nierozstrzygniętym — zawsze podejmij wyraźną decyzję oceniającą.

H1 — uruchamiane, gdy keyword_match == "partial":

h1_text : (z h1.values[0])
keyword : (słowo kluczowe przekazane do skryptu przez --keyword)

Oceń: Czy ten H1 semantycznie pokrywa intencję wyszukiwania słowa kluczowego?
  - Weź pod uwagę synonimy, naturalne warianty, pokrycie tematu
  - tak → zmień na "pass", odnotuj wariant
  - nie → utrzymaj "warn" lub podnieś do "fail", wyjaśnij lukę

Title — uruchamiane, gdy keyword_match == "partial" LUB keyword_position != "start":

title   : (z title.value)
keyword : (słowo kluczowe przekazane przez --keyword)

Oceń:
  1. Czy tytuł semantycznie pokrywa intencję wyszukiwania słowa kluczowego?
  2. Czy tytuł jest gramatycznie poprawny i naturalnie czytelny?
  3. Pozycja słowa kluczowego — zastosuj różne standardy w zależności od typu strony:
     - Strona główna   : Marka + główne słowo kluczowe jest poprawne (np. „Acme | Automatyzacja przepływu pracy AI”)
                    NIE oznaczaj marki na początku jako problemu.
     - Strony wewnętrzne: Powinno prowadzić główne słowo kluczowe (np. „Automatyzacja przepływu pracy AI dla zespołów — Acme”)
                    Oznacz, jeśli słowo kluczowe jest ukryte w środku tytułu bez dobrego powodu.

WAŻNE — NIE oznaczaj jako negatywnych:
  - Lata (np. „2026”) → sygnalizują świeżość, zwiększają CTR — traktuj jako pozytywne, chyba że
    strona jest wyraźnie treścią wiecznie zieloną, gdzie datowanie zaszkodziłoby długowieczności.
  - Liczby (np. „5 najlepszych”, „Top 10”, „3 kroki”) → ustanawiają jasne oczekiwania,
    konsekwentnie przewyższają tytuły nieliczbowe w CTR — zawsze traktuj jako plus.
  - Określone kwalifikatory („Open-Source”, „Self-Hosted”, „Free”) → zawężają intencję
    i przyciągają kliknięcia wyższej jakości — nie karaj.

URL Slug — uruchamiane, gdy keyword_match != "full" lub is_homepage == false:

slug    : (z url_slug.slug)
keyword : (słowo kluczowe przekazane przez --keyword)

Oceń:
  1. Czy slug zawiera główne słowo kluczowe lub naturalny wariant?
  2. Czy hierarchia ścieżki jest logiczna? (/kategoria/słowo-kluczowe jest idealna)
  3. Czy jest zwięzły i czytelny dla człowieka?
  Strona główna (is_homepage: true): pomiń — ocena nie jest potrzebna.

Meta Description — zawsze uruchamiane, gdy treść jest obecna:

meta_description : (z meta_description.value)
keyword          : (słowo kluczowe przekazane przez --keyword)

Oceń wszystkie cztery:
  1. Pełne zdanie/a? (1-2 zdania, bez fragmentów)
  2. Wspomina o konkretnym rezultacie — nie ogólnikowy puch?
     Dobrze: "Skróć czas projektowania o 60% dzięki szablonom opartym na AI"
     Źle:  "Najlepsze narzędzie do wszystkich Twoich potrzeb projektowych"
  3. Słowo kluczowe lub naturalny synonim użyte raz — nie upchane?
  4. Bardziej szczegółowe niż to, co napisałby typowy konkurent?

WAŻNE — NIE oznaczaj jako negatywnych:
  - Lata (np. „2026”) → sygnalizują świeżość, poprawiają CTR dla zapytań wrażliwych na czas.
    Odnotuj rok tylko, jeśli strona jest wyraźnie treścią wiecznie zieloną, gdzie datowanie szkodzi.
  - Liczby (np. „5 najlepszych”, „3 kroki”) → konkretna specyfika, silny sygnał CTR.
  - Końcowe „i więcej.” → co najwyżej drobna uwaga stylistyczna, nigdy Ostrzeżenie czy Niezaliczenie.

Zalecany przepływ pracy

Postępuj zgodnie z poniższymi krokami w kolejności:

1. Potwierdź zakres — potwierdź, że jest to podstawowy audyt; zanotuj wszelkie brakujące dane

2. Wywnioskuj główne słowo kluczowe — pobierz stronę za pomocą fetch-page.py, a następnie określ główne słowo kluczowe:

   • Jeśli użytkownik wyraźnie podał słowo kluczowe → użyj go bezpośrednio
   • Jeśli nie → przeczytaj H1, tytuł i pierwszy akapit strony, a następnie wywnioskuj jedno, najbardziej prawdopodobne docelowe wyrażenie kluczowe (co wpisałby szukający, aby znaleźć tę stronę?)
   • Jasno określ wywnioskowane słowo kluczowe przed uruchomieniem kontroli:

     "Wywnioskowane główne słowo kluczowe: open source claude alternatives"

3. Uruchom check-site.py — parsuj wyniki JSON dla robots, sitemap, obsługi 404 i kanonizacji adresów URL

   Kontrola 404: pobierz <origin>/this-page-definitely-does-not-exist-seo-audit-check

   • Zwraca 404 → Pass · Zwraca 200 (miękki 404) → Fail · Zwraca 301 do strony głównej → Warn

   Kontrole kanonizacji adresów URL (każda jest osobną podkontrolą):

   • HTTP→HTTPS: pobierz http://<host> — musi 301 na https://. Zwraca 200 → Fail.
   • Spójność www: pobierz oba https://www.<host> i https://<host> — jeden musi 301 na drugi. Oba zwracają 200 → Warn.
   • Końcowy ukośnik: porównaj faktycznie serwowany URL z tagiem kanonicznym na stronie. Niezgodność → Warn.
   • Zgodność kanoniczna: href tagu kanonicznego musi dokładnie pasować do finalnego URL po wszystkich przekierowaniach. Niezgodność → Warn.

4. Kontrola infrastruktury E-E-A-T — dla każdej strony zaufania poniżej sprawdź dwie warstwy:

   • Warstwa 1 — Istnieje: pobierz URL, sprawdź status HTTP (200 = istnieje, 404/przekierowanie = brak)
   • Warstwa 2 — Osiągalna: pobierz HTML strony głównej, sprawdź, czy stopka lub nawigacja zawiera link do tej strony

   Strona	Wymagana
   O nas	Tak
   Kontakt	Tak
   Polityka prywatności	Tak
   Warunki korzystania z usługi	Tak
   Media / Partnerzy	Nie — uwzględnij tylko jeśli występują

   Zasady statusu:

   • Brak strony (nie-200) → Fail
   • Strona istnieje, ale nie jest powiązana w stopce/nawigacji → Warn
   • Strona istnieje i jest powiązana w stopce/nawigacji → Pass
   • Brak opcjonalnej strony → pomiń, nie dołączaj wiersza

5. Uruchom check-page.py --keyword "<wywnioskowane_słowo_kluczowe>" — parsuj wyniki JSON dla H1, title, meta description, canonical i URL slug

6. Kontrola i18n / hreflang — uruchom tylko, jeśli strona zawiera znaczniki hreflang lub <html lang> sugeruje wielojęzyczność:

   • Pomiń całkowicie (N/A), jeśli nie znaleziono znaczników hreflang i witryna wydaje się jednojęzyczna
   • Jeśli znaczniki hreflang są obecne, sprawdź:
     • Wzajemna symetria: każdy wskazany URL musi linkować z powrotem do wszystkich innych wariantów — jakikolwiek uszkodzony link = Fail
     • Kody językowe: muszą być poprawne BCP 47 (np. zh-CN nie zh, en-US nie en-us) — błędny kod = Warn
     • x-default: powinien być obecny dla stron wyboru języka lub zapasowych — brak = Warn
     • Atrybut html[lang]: musi pasować do głównego hreflang strony — niezgodność = Warn
     • Struktura URL: zalecany wzorzec — domyślny język (zazwyczaj en) w katalogu głównym bez prefiksu, inne języki pod ścieżkami (/zh/, /es/).
       • /page (en) + /zh/page + /es/page → Pass
       • /en/page + /zh/page → Warn (prefiks en jest zbędny, marnuje głębokość indeksowania)
       • Oznaczaj tylko, jeśli wzorzec jest wyraźnie niespójny lub en jest niepotrzebnie poprzedzony prefiksem

7. Uruchom check-schema.py — parsuj wyniki JSON dla typów schematu i walidacji pól

   python scripts/check-schema.py https://example.com
   # Lub z wcześniej pobranego HTML:
   python scripts/check-schema.py --file page.html
   

   Skrypt wyodrębnia bloki JSON-LD, waliduje @type i wymagane pola zgodnie ze specyfikacją Schema.org. llm_review_required: true jest zawsze ustawione — potwierdź, że inferred_page_type pasuje do rzeczywistej treści strony.

   Typ strony → oczekiwane odniesienie @type:

   Typ strony	Oczekiwany @type	Min. wymagane pola
   Strona główna	WebSite + Organization	name, url, logo
   Blog / Artykuł	Article lub BlogPosting	headline, datePublished, author, image
   Produkt	Product	name, image, offers (price, priceCurrency)
   FAQ	FAQPage	mainEntity[].name, acceptedAnswer.text
   How-to	HowTo	name, step[].text
   Lokalny biznes	LocalBusiness	name, address, telephone
   Ogólny landing	—	N/A — pomiń, brak powszechnie wspieranego typu

   • Pass: poprawny @type obecny, wszystkie wymagane pola prawidłowe, brak konfliktów
   • Warn: @type obecny, ale brakuje zalecanych pól
   • Fail: oczekiwany @type całkowicie brak
   • N/A: ogólna strona landing — nie karaj

8. Podsumuj wnioski — każde znalezisko musi być zgodne z formatem Dowód / Wpływ / Poprawka

9. Działania priorytetowe — wypisz 3 poprawki o najwyższym wpływie

10. Wyrenderuj raport — zapisz do reports/<hostname>-<slug>-audit.html, następnie zapytaj użytkownika o otwarcie

11. Sugestia aktualizacji — jeśli znaleziono problemy wykraczające poza podstawowy zakres, zasugeruj seo-audit-full

Zasady pisania szczegółów raportu

Komórka Szczegóły w tabelach kontroli musi być zgodna z tymi zasadami — bez wyjątków:

Pass → jedno krótkie zdanie. Bez list, bez rozwinięcia.

Dobrze: "Poprawny zestaw URL XML · 104 adresy URL · wskazany w robots.txt."
Źle:  "Poprawny zestaw URL XML z 104 adresami URL. Poprawnie wskazany w robots.txt.
       Wpisy na blogu są prawdopodobnie indeksowane przez tę mapę witryny."

Warn → jeden <div class="detail-issue"> z ≤2 punktami. Jeden <div class="detail-fix"> z poprawką.

Dobrze:
  <div class="detail-issue">· Tytuł 48 znaków — 2 poniżej minimum. · Rok „2026” postarzeje stronę.</div>
  <div class="detail-fix">Rozszerz do 50–60 znaków; usuń rok, jeśli treść jest wiecznie zielona.</div>

Źle: trzy zdania prozy wyjaśniające, czym jest znacznik tytułu i dlaczego długość ma znaczenie.

Fail → tak samo jak Warn. Rozpocznij od dokładnego niepowodzenia. Bez wyjaśnień tła.

NIE wyjaśniaj, czym jest kontrola, NIE powtarzaj informacji już widocznych w plakietce statusu, NIE traktuj czytelnika jak nieobeznanego z podstawami SEO.

Obowiązkowy format znaleziska

Każde ważne znalezisko musi być zgodne z tą strukturą:

**Znalezisko: [Tytuł znaleziska]**

- **Dowód:** [Co zaobserwowano — bezpośredni cytat, odniesienie do zrzutu ekranu lub mierzalne dane]
- **Wpływ:** [Dlaczego ma to znaczenie dla SEO lub UX]
- **Poprawka:** [Konkretna, wykonalna rekomendacja]

Nie pisz ogólnikowych wniosków. Jeśli dowody są niewystarczające, wyraźnie określ założenia.

Sugestia aktualizacji

Dołącz to na końcu każdego podstawowego raportu audytu:

Chcesz głębszą analizę? To był podstawowy audyt SEO obejmujący sygnały na poziomie witryny i podstawowe kontrole na stronie. W celu zaawansowanego technicznego SEO, oceny jakości treści, analizy danych strukturalnych i pełnych wniosków opartych na crawlach, użyj umiejętności seo-audit-full.

Pliki referencyjne

• Szczegółowy zakres audytu i definicje pól: references/REFERENCE.md
• Końcowy szablon raportu HTML: assets/report-template.html
• Skrypt kontroli poziomu witryny: scripts/check-site.py
• Skrypt kontroli poziomu strony: scripts/check-page.py
• Pobieracz surowej strony: scripts/fetch-page.py
• Skrypt walidacji schematu: scripts/check-schema.py