insane0777/awwwards-skills

awwwards-doctor

Use when awwwards-mcp scraping or tools stop working — BlockedError, "layout may have changed" parser errors, empty results, failed captures, stale searches — or when the user reports the MCP behaving oddly.

Ver código-fonte

Como usar

  1. Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
  2. Consulte no original as ferramentas, credenciais e ambientes necessários.
  3. Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/insane0777/awwwards-skills --skill awwwards-doctor

Antes de começar

  • A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
  • Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Documento original do Skill

Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.

Awwwards MCP Doctor

You are repairing the awwwards-mcp toolchain or working around it mid-task. Work in this order: diagnose → fix mechanically → fix parsers (if drift) → recover the user's task. Never delete user data; the only destructive step (cache DB moved aside) keeps the old file — in the OS temp dir for --fix, beside the cache after a full backup for the manual reset.

Profile note: this skill's tools are search_sites, get_site_details, capture_live_site, analyze_page_structure, capture_component, export_design_tokens and analyze_images. The examples below use those 1.x names (the default full profile). On AWWWARDS_MCP_PROFILE=v2, use search_references {request:{kind:"sites", ...}}, get_reference {request:{kind:"site_details", slug}}, capture_page {request:{kind:"screenshot", url}}, inspect_page {request:{kind:"structure", url}}, capture_page {request:{kind:"component", url}}, inspect_page {request:{kind:"tokens", url}} and audit_page {request:{kind:"images", url}} instead. Full mapping: v2-routing.md.

1. Run the doctor (awwwards-mcp source checkout)

Run these from the root of the awwwards-mcp source checkout (github.com/INSANE0777/Awwwards-mcp), the repository whose package.json is awwwards-mcp — not from an awwwards-skills checkout. The npm package does not ship these scripts; if you installed the server, use section 3 instead.

bash
npm run doctor             # diagnose only
npm run doctor -- --fix    # diagnose AND apply available fixes
npm run doctor -- --json   # machine-readable report

The doctor checks five things and knows how to fix the mechanical ones:

CheckFailure meaningWhat --fix does
networkawwwards.com blocked/challenged the requestnothing to fix locally — wait, retry later; never retry in a loop
parser-driftawwwards.com markup changed under the parserscaptures the raw live page into docs/drift-<timestamp>/ (gitignored) as the fixture for the fix
playwright-chromium / ffmpeg-staticoptional capture deps missing or brokeninstalls them (dev deps + npx playwright install chromium)
cacheSQLite DB corrupt/locked, or index older than 30 daysmoves an unreadable DB aside (kept in temp) and rebuilds via npm run index
bootdist/cli.js doesn't startnpm run build

Re-run the doctor after fixing; the verdict must be HEALTHY before you claim the MCP is repaired.

2. Fixing real parser drift (the only code-level failure)

If the doctor reports parser-drift, the anchor probes say which parser broke. Repair sequence — keep it mechanical, verify at each step:

  1. Capture the evidence: the --fix snapshot in docs/drift-*/ IS the

new truth. (The daily GitHub Action also opens/updates a parser-drift tracking issue with the drifted anchor names.)

  1. Locate the new anchors: open the captured HTML and find the markup

that replaced the old anchor (search the old anchor's purpose, e.g. the card JSON blob, the Elements section heading, the og:image meta).

  1. Re-anchor the parsers in src/parsers.ts — change the minimum needed

(one split/indexOf/regex literal), not the surrounding logic.

  1. Update the probe list in scripts/parser-drift-probe.mjs (in the same

awwwards-mcp checkout; PROBE_GROUPS) so the same failure is detectable next time.

  1. Refresh the fixture: download the live page with the same UA the

client uses and replace test/fixtures/listing.html (or the detail fixture). The offline tests run against fixtures only — a refreshed fixture proves the re-anchor against reality.

  1. npm run typecheck && npm test — all tests must pass.
  2. Commit as fix: re-anchor <parser> after awwwards.com markup change,

reference the tracking issue.

Note: the annual-award tools (get_annual_*) come from the official JSON API (src/annual.ts), not the parsers, and the expanded award-cut listings (sites_of_the_month/year, nominees, winner_category_*) have their own trimmed fixtures under test/fixtures/awards/ — refresh those when their anchors drift, alongside the daily listing's.

3. End users (installed via npm, not a repo checkout)

The doctor scripts live in the repo, so for an npm-installed server:

  1. Check the version notice: stderr at startup prints when a newer

awwwards-mcp exists. Update with npm install -g awwwards-mcp@latest (or clear the npx cache) and restart the agent — a surprising share of "broken" reports are old parsers fixed in a newer release. AWWWARDS_AUTO_UPDATE=1 in the MCP server env opts into background self-update on startup.

  1. Back up, then reset only the database. Stop the agent/MCP server first

so the DB is not mid-write. Resolve the cache root with CACHE="${AWWWARDS_CACHE_DIR:-$HOME/.awwwards-mcp}" (the server reads the same variable). Copy it aside first, then move only the SQLite files; the next index/run rebuilds them:

bash
   CACHE="${AWWWARDS_CACHE_DIR:-$HOME/.awwwards-mcp}"
   STAMP="$(date +%Y%m%d-%H%M%S)"
   cp -R "$CACHE" "$CACHE.backup-$STAMP"
   mkdir -p "$CACHE.moved-$STAMP"
   for f in "$CACHE"/cache.db*; do [ -e "$f" ] && mv "$f" "$CACHE.moved-$STAMP/"; done

A blanket delete of the cache root would also destroy preferences.json (setup choices), skill-memory/findings.jsonl (learned findings), winner watches (rows inside cache.db), and captures in images/ and scene-captures/. The targeted reset loses only the search index and watch rows — the index rebuilds, watches must be re-added — while preferences, learned findings and captures are kept. Never rm -rf the cache root.

  1. If it still fails, it's upstream (block or drift): open an issue at the

awwwards-mcp repo attaching the raw HTML of the failing URL.

4. Recovering the in-flight task (the reason you noticed)

The user's build/research doesn't wait for the repair. Degrade gracefully:

  • Stale cache is your friend: search_sites/get_site_details serve

cached data when live fetches fail — say so in the reply ("7-day-old cached data").

  • BlockedError means stop, not retry: the client never retries through

blocks; tell the user and continue with cached/alternate data.

  • Capture tools down (playwright missing): fall back to

get_site_details screenshots (CDN-served, no browser needed) until npm run doctor -- --fix restores chromium.

  • Token/image tools down: export_design_tokens reuses the

capture_component pack (same playwright/chromium requirement), and analyze_images needs the same browser. Without playwright both return the raw browser/module error (e.g. Cannot find package 'playwright'), not the friendly install hint — capture_live_site / analyze_page_structure are the tools that return the hint. Cached get_site_details screenshots are the fallback. analyze_images never downloads assets — zero images means the page has no <img> elements (canvas/CSS-background content) or the scan found none, not a broken audit.

  • One band, a preloader, or `mode:"anchors"`: 1.14 detects inner scroll

roots (scrollRoot) and waits out full-screen loaders; 1.15 returns mode:"anchors" for inner-scroll pages — six ordered viewport shots down the scroller as JSON paths (anchors[].scrollTop/file) with no inline image. That is the honest success payload, not a broken capture; use scrollCapture:"viewport" when you want one explicit viewport shot. A scrollRoot re-query error (0 or >1 matches) means the DOM changed between scan and shot — re-run or report the label and match count. If a page still returns a single band, its content may be in shadow DOM or canvas; inspect and report the limitation instead of treating it as a full band map.

  • Parser drift mid-task: results may be partially empty (e.g. details

without palette). Surface which part is missing; don't silently present degraded data as complete.

  • After the MCP is healthy again, re-run the failed calls and reconcile

with whatever the fallback produced.

Close the flywheel

Repairs are the highest-value lessons - they were expensive to learn. In a checkout of the awwwards-skills repository (the installed skill copy does not include this dev script), after a successful diagnosis + fix: node scripts/skill-memory.mjs record --skill awwwards-doctor --phase repair --symptom "..." --rule "..." [--evidence <report path>]. Distill folds recurring failure signatures into this installed copy so the next repair starts knowing them. When a rule proves out, promote --skill awwwards-doctor outputs it cleaned (no machine-local evidence paths) for the shipped-copy PR.

Anti-patterns

  • Retrying blocked requests in a loop — politeness rules and block

detection exist precisely so this doesn't hammer awwwards.com.

  • Diffing raw HTML to detect drift — cosmetic page changes would false-alarm

daily; only parser-anchor probes matter.

  • "Fixing" parsers by loosening them to return empty results quietly — a

parse that can't find its anchors must error loudly (that is the drift signal).

  • Blanket-deleting the cache root to "reset" — it destroys preferences,

learned findings, winner watches and captures. Back it up, then move only cache.db*.

  • Treating the doctor's UNHEALTHY verdict as done because one check passed.

<!-- skill-memory:start --> <!-- skill-memory:end -->

do mesmo repositório

Mais Skills

Todos os Skills
insane0777
Comunidade

awwwards-inspiration

Use when building a site that needs design references (e.g. "make it feel premium", "dark 3D portfolio vibes"), when the user asks for standalone inspiration research ("show me award-winning e-commerce sites", "what's trending in brutalism"), or when setting up or maintaining the awwwards-mcp local index or live-capture tooling (awwwards-index, capturelivesite).

Instalações / 1h
2
GitHub Stars
4
Atualizado
18 de nov.
insane0777
Comunidade

awwwards-atlas

Use when working with the experimental Atlas section/component evidence layer in awwwards-mcp 1.19+ - enabling AWWWARDSMCPATLAS, importing or capturing Atlas evidence, searching sections/components, reading regions or status, exporting local evidence packs, or maintaining the Atlas cache. Atlas is opt-in, off by default, and its labels are candidate-only.

Instalações / 1h
2
GitHub Stars
4
Atualizado
12 de nov.
insane0777
Comunidade

awwwards-design-md

Create an evidence-backed DESIGN.md for any public website URL. Use when asked to extract a site's design system, colors, typography, spacing, radii, shadows, components, or to generate a design.md compatible with Google's design.md format. Composes the awwwards MCP inspection/capture tools; does not invent brand intent, source token names, or unobserved states.

Instalações / 1h
2
GitHub Stars
4
Atualizado
12 de nov.
insane0777
Comunidade

awwwards-motion-study

Use when building a site whose reference has animation — before writing any motion code, and again when verifying a build. Teaches what to record from a live site (and what to skip), how to study the recordings frame-by-frame (video input or ffmpeg tile-per-element), how to turn the study into a motion inventory, and how to verify the build's motion against the reference. Complements awwwards-inspiration (step 6) with the full capture→review→build procedure.

Instalações / 1h
2
GitHub Stars
4
Atualizado
12 de nov.