google-ads-ver-2/.claude/skills/google-ads-client-report/SKILL.md

name, description

name	description
google-ads-client-report	Workflow for generating, reviewing, validating, and uploading monthly Google Ads client HTML reports in this repository. Use when the user asks for `raport-klienta`, `analiza-klienta` with a domain and month, a monthly client report, regenerating a report, adding report recommendations, checking Semstorm/SEO sections, or uploading a report to adspro.projectpro.pl.

Google Ads Client Report

Core Rule

Pisz po polsku. Prowadź użytkownika etapami: pobranie danych, uzupełnienie rekomendacji, akceptacja, generowanie HTML, akceptacja uploadu, wysyłka.

Nigdy nie wysyłaj raportu na serwer bez jasnej zgody użytkownika po wygenerowaniu HTML.

Start

Dla prośby w stylu:

raport-klienta aruba.rzeszow.pl 04-2026
analiza-klienta aruba.rzeszow.pl 04-2026

uruchom:

python gads.py raport-klienta aruba.rzeszow.pl 04-2026

Formaty miesiąca mogą być MM-YYYY, MM.YYYY albo YYYY-MM. Do dalszych komend używaj YYYY-MM.

Jeżeli użytkownik napisze tylko raport-klienta, uruchom:

python gads.py raport-klienta

Pokaż pełną listę klientów i poproś o numer. Po wyborze klienta i miesiąca uruchom:

python gads.py raport-klienta --client-number <numer-klienta> --month <YYYY-MM>

Recommendations

Pierwsza komenda tworzy dane i plik rekomendacji:

scripts/reports/output/<domena>_<YYYY-MM>.json
scripts/reports/output/<domena>_<YYYY-MM>_recommendations.json

Odczytaj oba pliki. Uzupełnij recommendations konkretnymi wnioskami:

• pisz z perspektywy osoby prowadzącej konto;
• pisz decyzyjnie: co robimy, zostawiamy, ograniczamy, kontrolujemy;
• nie pisz do klienta, że "warto sprawdzić" albo "należy przeanalizować";
• używaj poprawnych polskich znaków;
• nie usuwaj kontekstu liczbowego z pliku.

Pokaż użytkownikowi krótką tabelę wniosków i zapytaj o akceptację.

Required Data Validation

Przed wygenerowaniem albo wysłaniem raportu sprawdź plik:

scripts/reports/output/<domena>_<YYYY-MM>.json

Wymagane kontrole:

• semstorm.current ma istnieć. Semstorm powinien być zawsze pobrany, gdy .env zawiera SEMSTORM_LOGIN i SEMSTORM_PASSWORD. Jeśli brakuje danych, nie wysyłaj raportu; napisz, czego brakuje.
• Jeśli klient ma sales_history_sheet w config/clients.toml, sekcja e-commerce i historia sprzedaży mają pochodzić z Google Sheet, nie z GA4.
• Jeśli klient ma seo_works_history_sheet, raport ma zawierać seo_activities.
• Jeśli klient ma seo_links_history_sheet, raport ma zawierać seo_links z liczbą większą od 0, jeżeli arkusz zawiera dane dla miesiąca.
• Sprawdź wygenerowany HTML pod kątem sekcji: SEO — Widoczność (Semstorm), SEO — Pozostałe działania, SEO — Pozyskane linki.

Pomocne komendy:

$json = Get-Content -Raw "scripts\reports\output\<domena>_<YYYY-MM>.json" | ConvertFrom-Json
$json.semstorm.current
$json.seo_activities
$json.seo_links.Count
Select-String -Path "scripts\reports\output\<domena>\<YYYY-MM>\index.html" -Pattern "Semstorm|Pozostałe działania|Pozyskane linki"

Generate HTML

Po akceptacji rekomendacji uruchom:

python gads.py raport-klienta --client <domena> --month <YYYY-MM> --confirm-recommendations TAK

Jeżeli potrzebna jest nazwa klienta w raporcie:

python gads.py raport-klienta --client <domena> --month <YYYY-MM> --client-name "<Nazwa>" --confirm-recommendations TAK

Po wygenerowaniu pokaż ścieżkę:

scripts/reports/output/<domena>/<YYYY-MM>/index.html

Zapytaj osobno, czy wysłać raport na serwer.

Upload

Po zgodzie użytkownika uruchom komendę z oboma potwierdzeniami, żeby narzędzie nie zatrzymało się ponownie na etapie rekomendacji:

python gads.py raport-klienta --client <domena> --month <YYYY-MM> --client-name "<Nazwa>" --confirm-recommendations TAK --confirm-upload TAK

Jeśli nazwa klienta nie jest potrzebna, można pominąć --client-name.

Po wysyłce podaj URL:

https://adspro.projectpro.pl/raporty/<slug>/<YYYY-MM>/

If Data Is Missing

Nie wysyłaj raportu, jeżeli brakuje wymaganych sekcji. Najpierw popraw pobieranie danych albo konfigurację:

• Semstorm: sprawdź .env, SEMSTORM_LOGIN, SEMSTORM_PASSWORD, SEMSTORM_API_BASE, ewentualnie uruchom python scripts/reports/fetch_semstorm_data.py --domain <domena> --month <YYYY-MM>.
• SEO works/linki: sprawdź config/clients.toml i pola seo_works_history_sheet, seo_links_history_sheet.
• Po poprawce uruchom ponownie generowanie HTML i walidację przed uploadem.