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.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/insane0777/awwwards-skills --skill awwwards-doctor

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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

같은 저장소의 Skills

더 많은 Skills

모든 Skills
insane0777
커뮤니티

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).

1시간 설치 수
2
GitHub Stars
4
업데이트
11월 18일
insane0777
커뮤니티

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.

1시간 설치 수
2
GitHub Stars
4
업데이트
11월 12일
insane0777
커뮤니티

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.

1시간 설치 수
2
GitHub Stars
4
업데이트
11월 12일
insane0777
커뮤니티

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.

1시간 설치 수
2
GitHub Stars
4
업데이트
11월 12일