القائمة
Health audit and troubleshooting
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Update site dependencies and template files to the latest version
Add ecommerce to your site — sells physical goods, digital downloads, services, or software
Design CSS animations: hover effects, scroll reveals, page transitions
Back up site changes to GitHub, or restore an earlier snapshot
Embed appointment scheduling (Cal.com or Calendly) into the site
Collect and display business hours, address, phone, and LocalBusiness JSON-LD
| name | check |
| description | Health audit and troubleshooting |
| license | ISC |
| compatibility | Designed for Claude Code / compatible agents operating inside an Anglesite project (Astro + Keystatic, Node >=22). Deploy/provisioning steps require a Cloudflare account and Wrangler. |
| allowed-tools | Bash(npm run *), Bash(npx astro check), Bash(npx pa11y *), Bash(npx pa11y-ci *), Bash(npx tsx scripts/link-check.ts *), Bash(npx tsx scripts/a11y-audit.ts *), Bash(npx tsx scripts/a14y-audit.ts *), Bash(npx a14y *), Bash(a14y *), Bash(grep *), Bash(find dist/ *), Bash(stat *), Bash(npm audit *), Bash(lsof *), Bash(netstat *), Bash(getent *), Bash(nslookup *), Bash(gh issue *), Bash(gh label *), Write, Read, Glob, mcp__cloudflare__accounts_list, mcp__cloudflare__search_cloudflare_documentation, mcp__cloudflare__workers_list, mcp__cloudflare__workers_get_worker, mcp__cloudflare__workers_get_worker_code |
| metadata | {"author":"David W. Keith","version":"1.6.0","source":"https://github.com/Anglesite/anglesite","invocation":"user-facing","argument-hint":"[optional: describe the problem]"} |
Run a full health check on the site — and fix what you find. If the owner described a specific problem, diagnose that first; otherwise run the full audit below. The checklists are for you (the agent) — do not show raw checklist items, technical terms, or jargon to the owner. Translate every finding into plain English. See the Results section at the bottom for how to present findings.
These explain why each check category matters:
rel="me" are checkedAGENTIC_CRAWLERS=blockRead EXPLAIN_STEPS from .site-config. If true or not set, explain before every tool call that will trigger a permission prompt — tell the owner what you're about to do and why in plain English. If false, proceed without pre-announcing tool calls.
npx astro check passes (TypeScript)npm run build succeedsThese checks are not optional. Accessibility failures are as serious as security failures.
Build the site first, then run the unified accessibility audit:
npm run ai-a11y
The report is written to reports/a11y-report.md (the reports/ directory is gitignored — regenerated on demand, never committed).
This script (scripts/a11y-audit.ts) walks every HTML file in dist/ and produces a per-page WCAG 2.1 AA report with suggested fixes. It runs three checkers and aggregates the results:
scripts/a11y-validate.ts).npm install -D pa11y or pa11y-ci). Catches contrast, ARIA, label association, and landmark issues the heuristic pass can't see.npm install -D @axe-core/playwright playwright). Provides rich selector/remediation context.Any tool that isn't installed is skipped automatically — the audit always runs at least the heuristic pass.
The script exits with:
0 — no errors and no warnings (or --warn-only was passed)1 — one or more WCAG 2.1 AA violations2 — warnings only (best-practice issues, no AA violation)Pass --warn-only (or set A11Y_WARN_ONLY=true in .site-config) to always exit 0 while a site is mid-remediation. Pass --json for a machine-readable report.
Use the accessibility utilities in scripts/ for additional checks beyond the audit script:
scripts/contrast.ts: read CSS custom properties from src/styles/global.css and verify meetsWcagAA(textColor, bgColor) for all text/background pairsscripts/a11y-validate.ts: run validateHeadingHierarchy(), validateLinkText(), and validateImageAlt() against the built HTML output (the audit script already calls these)<h1>, and headings don't skip levelssrc/styles/global.css<label> elementslang attribute set on <html> element/accessibility statement page exists and is linked from the footerIf any accessibility check fails, explain what the issue is, who it affects, and how to fix it.
Anglesite sites are built and maintained by AI agents — they should also be readable by other agents (search agents, browsing agents, content-mapping agents). a14y.dev is an open scoring service (Apache-2.0) that runs 38 checks across discoverability, parsing, and comprehension and emits a numeric score plus a per-check pass/fail report.
The audit needs a running HTTP server. Make sure the dev server is up at https://DEV_HOSTNAME (or pass an explicit URL with --url) before running:
npm run ai-a14y
Optional flags (forwarded to the a14y CLI):
--url https://... — audit a specific URL instead of https://DEV_HOSTNAME--fail-under 80 — set the score threshold for CI use--json — machine-readable output (a14y emits a versioned scorecard JSON)--warn-only — never fail the process, even when the score is below the thresholdOr set the equivalent .site-config keys: A14Y_FAIL_UNDER and A14Y_WARN_ONLY=true.
If a14y isn't installed, the script prints install instructions and exits with code 127. To install:
npm install --save-dev a14y
When the audit returns findings, translate them for the owner: a14y rule IDs (e.g. llms-txt-missing, structured-data-thin) are technical labels — describe the user-visible impact ("AI agents that try to summarize your site won't have a quick reference") and the concrete fix.
AGENTIC_CRAWLERS in .site-config controls whether a14y also gates /anglesite:deploy:
AGENTIC_CRAWLERS=allow (default when unset) — a14y is a deploy gate; below-threshold scores pause publishing.AGENTIC_CRAWLERS=block — the owner has declared agentic crawlers shouldn't read this site. The check still runs here for reference, but never blocks deploy — gating on agent-readability when the policy is to keep agents out would be incoherent.If the owner is unsure, the default (allow) reflects Anglesite's open-by-default stance.
Check that the site works on small screens. Start the dev server if not already running.
<meta name="viewport" content="width=device-width, initial-scale=1">max-width: 100%max-width: 100% or srcset)Read CLOUDFLARE_ACCOUNT_ID from .site-config. If set, call mcp__cloudflare__accounts_list and check which account is currently active.
/anglesite:deploy and let it sort itself out."CLOUDFLARE_ACCOUNT_ID is unset (older sites set up before this check), suggest running /anglesite:deploy once so the picker can lock the site to a specific account.This check is informational — never block the audit on it. Owners often switch accounts intentionally during the workday.
Local checks confirm the source compiles — they can't see what's actually running on Cloudflare. When an owner reports "the contact form isn't sending email" or "subscribers aren't being added," the most common cause is local edits that were never deployed.
Run this only if CLOUDFLARE_ACCOUNT_ID is set in .site-config and the active account matches it (see "Cloudflare account alignment" above). If accounts don't match, skip this section — calling Workers APIs against the wrong account would produce misleading results. If CLOUDFLARE_ACCOUNT_ID is unset, skip silently.
Read references/skills/check/deployed-worker-drift.md and follow
the instructions to verify each Cloudflare Worker the site uses against its
deployed counterpart.
dist/ (emails, phone numbers, names).env files not tracked by gitpublic/_headers (CSP, X-Frame-Options, etc.)/keystatic routes in production buildrobots.txt blocks /keystatic/.env files in dist/ or public/npm audit — check for known vulnerabilitiespublic/images/ checked for EXIF GPS data (see docs/security.md)Run the automated link checker after a successful build:
npm run ai-linkcheck
This scans every page in dist/ and reports:
dist/To also check external links (slower — makes HTTP requests), run:
npm run ai-linkcheck -- --external
This additionally reports:
public/_redirectsIf any links are intentionally broken or external (e.g., internal-only domains, staging URLs), the owner can add them to .site-config:
LINK_CHECK_ALLOW=staging.example.com,internal.corp
Multiple patterns are comma-separated. Wildcards are supported: https://cdn.example.com/*.
IndieWeb endpoint routes (/auth and its subpaths, /.well-known/oauth-authorization-server, /micropub, /media, /webmention) are recognized automatically when the matching INDIEWEB_* flags are set in .site-config — they're served by the site Worker, not by files in dist/, so the link checker never reports them as broken. No allowlist entry needed.
Present link health findings using the same severity mapping as other checks:
<title> and <meta name="description">og:title, og:description, og:image)/sitemap-index.xmlrobots.txt exists and includes sitemap URLRead AGENTIC_CRAWLERS from .site-config (default allow) and confirm llms.txt and robots.txt reflect that single source of truth:
auditRobotsTxt(content, siteUrl, agenticCrawlers) from scripts/seo.ts against dist/robots.txt. Under allow, no centralized agentic crawler should be in a Disallow: / block; under block, every entry in AGENTIC_CRAWLER_BOTS should appear with Disallow: /. If anything is off, regenerate public/robots.txt via generateRobotsTxt(...) and rebuild.AGENTIC_CRAWLERS=block, confirm dist/llms.txt does not exist (and public/llms.txt doesn't either). Publishing an AI-readable index when the owner has blocked agents is incoherent — flag it as "Worth fixing soon" and offer to delete the file.AGENTIC_CRAWLERS=allow and the site has substantial content, mention that llms.txt gives AI agents a quick reference and offer to generate one (see /anglesite:seo Step 5).The list of tracked agentic crawler user-agents (GPTBot, ClaudeBot, anthropic-ai, CCBot, Google-Extended, PerplexityBot, Bytespider) lives in AGENTIC_CRAWLER_BOTS in template/scripts/seo.ts. Add new agents there — every surface above reads from that one list.
If BUSINESS_TYPE is set in .site-config, invoke the copy-edit skill for content quality coaching.
Read the copy-edit skill and follow it. Note that this is a non-interactive check context — present 1-5 findings as a brief section, no questions. Include the output as a "Copy quality" section in the health report. If BUSINESS_TYPE is not set, still run the audit using generic best practices.
Check that the site has the legal pages appropriate for its features and business type. Read BUSINESS_TYPE and ECOMMERCE_PROVIDER from .site-config. Refer to references/docs/smb/legal-checklist.md for the full checklist and references/docs/smb/legal-templates.md for free template sources.
/privacy/ and is linked from the footer/accessibility/ (or as a section on another page) and is linked from the footerECOMMERCE_PROVIDER set): terms of service exists at /terms//returns/ or /refund-policy/BUSINESS_TYPE is a licensed profession (legal, healthcare, accounting, insurance, fitness, contractor, real-estate): professional disclaimer present in footer or on a dedicated pageReport legal compliance findings as "Worth fixing soon" severity, not deploy blockers. Frame findings as helpful next steps:
| Missing item | What to tell the owner |
|---|---|
| No privacy policy | "Your site collects contact info through the form, so it needs a privacy policy page. I can draft one for you — it's straightforward since your site doesn't track visitors." |
| No terms of service (with ecommerce) | "Since you're selling through your website, you'll want a terms of service page. I can create one as a starting point." |
| No return policy (with ecommerce) | "Customers will want to know your return policy before buying. I'll add a page for that." |
| Missing professional disclaimer | "Most [profession] websites include a disclaimer. I'll add a brief one to your footer." |
| Missing copyright notice | "I'll add a copyright line to your footer — it's a small thing that signals ownership." |
docs/indieweb.md)h-card in site header with p-name and u-urlh-entry on blog posts with p-name, dt-published, e-contenth-feedrel="me" links present for the owner's social profilesu-syndication with rel="syndication"/rss.xml with <link rel="alternate"> discovery in <head>h-event markup if the business hosts eventsIf the site has <canvas> elements (creative effects, experiments, visualizations), verify:
<canvas> has either aria-label (if it conveys content) or aria-hidden="true" (if purely decorative)<noscript> fallback (description + static image for experiment pages)prefers-reduced-motion is respected — animations stop or simplify when reduced motion is preferredThese checks apply to any page with <canvas>, not just web-artist sites — a bakery with a snow effect needs the same accessibility treatment.
<head> beyond essential CSSdist/_astro/ (Astro should produce near-zero client JS)For a thorough performance audit, tell the owner: "Let's check how fast your site loads. I'll open Google's free speed test tool." Then open:
Open the PageSpeed tool in their browser: https://pagespeed.web.dev/
Have the owner paste their site URL. Explain the scores: green (90+) is great, orange (50-89) needs work, red (<50) is urgent.
og:title, og:description, and og:image present on every page in dist/twitter:card meta tag present (value: summary_large_image if og:image exists, summary otherwise)og:image and is approximately 1200x630 pixelsapple-touch-icon.png exists in public/ (180x180) — if missing, run npm run ai-images to generate itog-image.png exists in public/ — if missing, run npm run ai-images to generate itmanifest.webmanifest icon paths reference files that actually exist in public/og:title and og:description (not all the same)If BUSINESS_TYPE is set in .site-config, invoke the reputation skill for review coaching and competitive awareness.
Read REVIEW_PLATFORMS from .site-config if available. When invoking the reputation skill, note that this is a non-interactive check context so it should present tips, not questions.
If REVIEW_PLATFORMS is set, include the platform names in the nudge: "Reminder: check your [Google, Yelp] reviews — responding within a few days helps your reputation." If not set, use the generic nudge.
Read the reputation skill and follow it. Include the output as a "Reputation" section in the health report. Keep it brief — 1-3 action items max. If BUSINESS_TYPE is not set, skip this section.
If ECOMMERCE_PROVIDER is set in .site-config, assess whether the store has outgrown its current platform. This check uses scripts/ecommerce-upgrade.ts.
.mdoc files in src/content/products/ (if the directory exists)ECOMMERCE_WEBHOOK_URL is set in .site-config, query Analytics Engine using buildRevenueQuery(30) from scripts/ecommerce-revenue.ts to get 30-day revenue and order countassessUpgrade() with the provider, product count, and revenue data (if available)formatUpgradeMessage(). Frame it as "Worth looking into" (not "Must fix").Example finding for the owner:
"Your store has 14 products and is bringing in about $12,000/month — great work! At this size, you might benefit from switching to Shopify, which gives you a dashboard for inventory and orders. Snipcart charges about $240/month in fees at your volume; Shopify would be about $387/month but includes tools that save you time. No rush — just something to think about as you grow."
If no ecommerce provider is configured, skip this section entirely. Do not suggest adding ecommerce during a health check.
The owner is not technical. Do not report raw checklist items. Translate every finding into one plain-English sentence that answers: what's wrong, why it matters, and what happens next. Group by severity using these everyday labels:
Examples of how to translate findings:
| Technical finding | What to tell the owner |
|---|---|
| Missing alt text on 3 images | "Three photos on your site don't have descriptions for people who use screen readers. I can add those for you." |
| Low color contrast on body text | "The text on some pages is hard to read against the background. I'll adjust the colors so it's easier on the eyes." |
| OG tags missing | "When you share your site link in a text or on social media, it won't show a nice preview card yet. I can fix that." |
| h-card missing | "Search engines and other sites can't find your business name and address in a standard format. I'll add that to the page." |
| npm audit found vulnerability | "One of the behind-the-scenes tools has a known security issue. I'll update it." |
| CSP header misconfigured | "Your site's security settings need a small adjustment. I'll take care of it." |
| EXIF GPS data in images | "Some of your photos have location information embedded in them. I'll strip that out so visitors can't see where the photos were taken." |
Never show the owner: CSS selectors, HTML tag names, HTTP headers, schema.org terms, WCAG levels, npm package names, or code snippets. If you need to explain why something matters, use an analogy or a concrete consequence ("visitors on phones will have to scroll sideways").
Summary: After the audit, present a markdown scorecard so the owner sees at a glance what's working and what needs attention:
- [x] Build
- [x] Accessibility
- [ ] SEO ← 2 issues
- [x] Security
- [x] Privacy
Use [x] for passing categories and [ ] for ones with issues. Add a brief annotation after any failing item.
If any must-fix issues are found, explain and offer to fix them. If everything passes, keep it short: "Your site looks good — it builds correctly, works on phones, is secure, and is easy for search engines to find. No issues."
After the check, tell the owner: "This is the same kind of checkup a good web developer would do regularly. Your site should get one of these at least once a month — just type /anglesite:check anytime."
After completing a full health audit (regardless of whether issues were found — running the check is the maintenance event), update MAINTENANCE_MONTHLY_LAST in .site-config to today's date in YYYY-MM-DD format. Use the Read tool to load the file, then the Write tool to replace or append the line. This is what /anglesite:deploy's pre-deploy scan reads when surfacing overdue-maintenance warnings (see docs/webmaster.md → Maintenance schedule).
Don't stamp the log if the audit was aborted early (e.g., the build failed before any checks ran) — only when the owner has actually been through the checkup.
After the audit, if any must-fix issues were found that couldn't be resolved in the current session, file a GitHub issue for each one. Read GITHUB_REPO from .site-config. If not set, skip this step.
Follow the bug filing workflow in docs/bug-filing.md. Use the appropriate label:
accessibilitysecuritybuildcontentbugIf the issue is in Anglesite itself (not the owner's site), use the plugin bug filing workflow in docs/bug-filing.md to open a pre-filled issue in the owner's browser against Anglesite/anglesite.
If the owner reported a specific problem (or you found one during the audit), diagnose and fix it.
Cloudflare ships features quickly (Workers Static Assets, the Pages → Workers migration, bot management defaults, error code semantics). Before suggesting a fix for any Cloudflare-adjacent issue — DNS propagation, SPF/DKIM/DMARC, Workers limits, custom domain quirks, wrangler errors — call mcp__cloudflare__search_cloudflare_documentation with a query that names the symptom (e.g., "wrangler deploy 10021 error", "Workers static assets _headers precedence", "DMARC alignment p=quarantine"). Read the matching result before reasoning from training data. If the search returns nothing useful, say so to the owner rather than guessing.
This applies whenever the issue might involve Cloudflare behavior. Skip it for purely local issues (Node version, port conflicts, Astro build errors).
npm run ai-check
Then read .site-config to verify it has SITE_NAME and DEV_HOSTNAME. If either is missing, suggest running /anglesite:start first.
npx wrangler login to re-authenticate.lsof -i :4321 (macOS/Linux) or netstat -ano | findstr :4321 (Windows) to find what's using port 4321.npm run ai-setup to fix shell profile.npm run ai-setup to reinstall it.dscacheutil -q host -a name HOSTNAMEgetent hosts HOSTNAMEnslookup HOSTNAME
Replace HOSTNAME with the value from .site-config. If it doesn't resolve to 127.0.0.1, run npm run ai-setup.npm run ai-check and look for https_portforward. If missing, run npm run ai-setup (macOS auto-configures; Linux/Windows require manual setup — see setup log).npm run ai-setup to regenerate.npm run ai-setup to reload pfctl. On Linux/Windows, check the setup log for manual instructions.~/.anglesite/logs/build.log, deploy.log, check.log, dev.lognpx astro check and npm run build to reproduce