App / Website Evaluation
Audit an app or website and hand back a prioritized, evidence-backed report: what's good,
what's missing, and the highest-impact fixes — ranked by impact × effort, each tied to concrete
evidence (a missing tag, a failing header, an absent file), never vague advice.
Be self-referential. There is no universal "good site." Judge each property against what's
best for its type and its community: a marketing site, a SaaS app, a docs site, a blog, an
open-source project, an e-commerce store, a portfolio, an API, or a mobile-app landing page each
have different priorities, standards, and growth channels. So classify first, then evaluate
against that class's norms. Apply the same lens to your own recommendations — the best PR and
software-design move for a niche dev tool is not the same as for a consumer app.
1. Classify the target (do this first)
Determine, from the URL/repo/screens and by asking if unclear:
- Type (marketing / SaaS / docs / blog / OSS project / e-commerce / portfolio / API / app
landing) and primary goal (signups, sales, stars, leads, reads, installs).
- Audience & community (developers, designers, consumers, a specific niche) — this drives
which channels, tone, and standards matter.
- Stage (pre-launch, launched, scaling) and stack (static, SSR, SPA, CMS) — a SPA has
different crawlability/perf concerns than a static site.
Everything below is weighted by these answers. State the classification at the top of the report.
2. Gather evidence
Run the bundled checker, then read the source if you have it. It takes one of three input
sources:
S=${CLAUDE_PLUGIN_ROOT}/skills/app-evaluation/scripts/evaluate-site.sh
"$S" --url https://example.com # live fetch (needs curl): headers, HTTPS, robots/sitemap, perf
"$S" --dir ./dist # a local BUILT/deployed dir (no network)
curl -sSL https://example.com | "$S" --html - # score pre-fetched HTML — no curl to origin
"$S" --html page.html --headers resp-headers.txt # …and score the live security headers too
Behind a sandbox egress proxy (web/remote Claude Code) --url often 403s: fetch the page any
other way and feed --html (+ --headers for the live header checks), or combine
--url with --html so your HTML is scored while the origin probes still run. A local build
served on localhost also works — plain-http/HSTS there are reported as INFO, not FAILs. Probe
misses behind a filter downgrade to INFO automatically. Pairing rules and details: --help.
Point --dir at the built/deployed output, not source. Many sites generate robots.txt,
sitemap.xml, and .well-known/security.txt at build time (e.g. a build-web.js), so scanning
src/ false-negatives Crawlability and Security — build first and target dist/ / build/ / the
deployed tree. The tool prints a NOTE when --dir looks like a source tree (a package.json build
script, or a src/ with no root robots/sitemap).
It prints a PASS/WARN/FAIL/INFO checklist per dimension, then a standardized Scorecard
(per-dimension 0–100 + letter grade, a weight-averaged overall that's starred when weight went
unassessed; --json for machine-readable). Formula and grade rubric: reference.md; flags:
--help. Security scores even off the network via source-visible controls (meta CSP,
security.txt, third-party-script posture). Don't stop at the script: read robots.txt, the
sitemap, the <head>, and the repo if you have it — the score is the evidence base, your judgment
(weighted by type/community) is the report.
3. Evaluate across dimensions
Start from the script's per-dimension letter grade + score, then adjust with judgment and the
evidence you read (the script is heuristic; a JS-rendered SPA can hide content from a fetch, so a
weak score may be a false negative — note it). Full checklists, the community directory, and the
scoring rubric are in reference.md — the dimensions:
| Dimension |
Look for (see reference.md for the full list) |
| Crawlability / indexing |
robots.txt, XML sitemap, canonical URLs, no accidental noindex, clean URLs, SPA pre-render/SSR |
| SEO |
unique <title> + meta description, heading hierarchy, semantic HTML, structured data (JSON-LD), internal links, image alt |
| AI-readiness |
llms.txt, machine-readable data (JSON-LD/schema.org), semantic markup, clean content extraction, an API or feed where it fits |
| Social / sharing |
Open Graph (og:title/description/image), Twitter card, a share image that renders, canonical social handles linked |
| Brand assets / standards |
favicon set + apple-touch-icon, logo (incl. SVG), a clear tagline, consistent naming, manifest.webmanifest, 404 page |
| Security / hygiene |
HTTPS + HSTS, security headers (CSP, X-Content-Type-Options, Referrer-Policy), no secrets/source maps leaked, deps current, security.txt |
| Performance / load |
payload size, render-blocking JS/CSS, image format/sizing (AVIF/WebP, dimensions), caching/CDN, lazy-loading, Core Web Vitals |
| Accessibility |
lang, viewport, contrast, labels/alt, focus order, keyboard nav (a11y is also SEO + reach) |
| Growth / community / PR |
analytics present, where this type is discovered, communities to join or submit to, easy PR/advertising wins (see reference.md) |
4. Report — standardized format (consistent every time)
Lead with the scorecard, then prioritize. Use this exact order so reports are comparable run-to-run:
- Classification (type, audience, goal) in one line, so every recommendation is anchored.
- Scorecard — the overall grade + score, then the per-dimension grades (reuse the script's
table; re-grade a dimension only when you have evidence the heuristic was wrong, and say why).
- Top fixes, ranked by impact × effort — lead with high-impact/low-effort (e.g. "add a
meta description and an og:image: 10 min, big SEO + share-CTR win"). Each cites evidence.
- By dimension, the per-dimension grade + the specifics behind it (what passed / what to fix).
- Growth plan for this type & community: concrete places to submit/join (Product Hunt, HN,
relevant subreddits/Discords, dev.to, Indie Hackers, awesome-lists, app stores, directories —
pick by type; reference.md has the directory), plus PR/advertising wins that suit the audience.
- What's already good — affirm it; don't only list problems.
Be honest about confidence and limits: a black-box URL scan can't see the codebase, server config,
or analytics; say what you'd need (repo access, the build dir, the CMS) to go deeper. Verify claims
against real output — don't assert a tag is missing without checking, and prefer fixing root causes
(a layout/template) over per-page patches.
See reference.md for the full per-dimension checklists, the by-type community/submission
directory, the AI-readiness and llms.txt guidance, and the impact×effort scoring rubric.
1---2name: app-evaluation3description: Evaluate an app or website and produce a prioritized, evidence-backed report — SEO and crawlability, AI-readiness, social/sharing assets, security and standards, performance/load-time, accessibility, and growth (which communities to join or submit to, PR/advertising wins). Use when the user asks to audit/review/evaluate/grade a website or app, improve its SEO/reach/discoverability, get it ready to launch or submit, or asks "how good is my site and what should I fix?"4---56# App / Website Evaluation78Audit an app or website and hand back a **prioritized, evidence-backed** report: what's good,9what's missing, and the highest-impact fixes — ranked by impact × effort, each tied to concrete10evidence (a missing tag, a failing header, an absent file), never vague advice.1112**Be self-referential.** There is no universal "good site." Judge each property against what's13best **for its type and its community**: a marketing site, a SaaS app, a docs site, a blog, an14open-source project, an e-commerce store, a portfolio, an API, or a mobile-app landing page each15have different priorities, standards, and growth channels. So **classify first**, then evaluate16against that class's norms. Apply the same lens to your own recommendations — the *best* PR and17software-design move for a niche dev tool is not the same as for a consumer app.1819## 1. Classify the target (do this first)2021Determine, from the URL/repo/screens and by asking if unclear:22- **Type** (marketing / SaaS / docs / blog / OSS project / e-commerce / portfolio / API / app23 landing) and **primary goal** (signups, sales, stars, leads, reads, installs).24- **Audience & community** (developers, designers, consumers, a specific niche) — this drives25 which channels, tone, and standards matter.26- **Stage** (pre-launch, launched, scaling) and **stack** (static, SSR, SPA, CMS) — a SPA has27 different crawlability/perf concerns than a static site.2829Everything below is weighted by these answers. State the classification at the top of the report.3031## 2. Gather evidence3233Run the bundled checker, then read the source if you have it. It takes **one of three input34sources**:3536```37S=${CLAUDE_PLUGIN_ROOT}/skills/app-evaluation/scripts/evaluate-site.sh38"$S" --url https://example.com # live fetch (needs curl): headers, HTTPS, robots/sitemap, perf39"$S" --dir ./dist # a local BUILT/deployed dir (no network)40curl -sSL https://example.com | "$S" --html - # score pre-fetched HTML — no curl to origin41"$S" --html page.html --headers resp-headers.txt # …and score the live security headers too42```4344**Behind a sandbox egress proxy** (web/remote Claude Code) `--url` often 403s: fetch the page any45other way and feed **`--html`** (+ **`--headers`** for the live header checks), or combine46**`--url` with `--html`** so your HTML is scored while the origin probes still run. A local build47served on `localhost` also works — plain-http/HSTS there are reported as INFO, not FAILs. Probe48misses behind a filter downgrade to INFO automatically. Pairing rules and details: `--help`.4950**Point `--dir` at the built/deployed output, not source.** Many sites generate `robots.txt`,51`sitemap.xml`, and `.well-known/security.txt` **at build time** (e.g. a `build-web.js`), so scanning52`src/` false-negatives Crawlability *and* Security — build first and target `dist/` / `build/` / the53deployed tree. The tool prints a NOTE when `--dir` looks like a source tree (a `package.json` build54script, or a `src/` with no root robots/sitemap).5556It prints a PASS/WARN/FAIL/INFO checklist per dimension, then a **standardized Scorecard**57(per-dimension 0–100 + letter grade, a weight-averaged overall that's **starred** when weight went58unassessed; `--json` for machine-readable). Formula and grade rubric: `reference.md`; flags:59`--help`. Security scores even off the network via source-visible controls (meta CSP,60`security.txt`, third-party-script posture). Don't stop at the script: read `robots.txt`, the61sitemap, the `<head>`, and the repo if you have it — the score is the evidence base, your judgment62(weighted by type/community) is the report.6364## 3. Evaluate across dimensions6566Start from the script's **per-dimension letter grade + score**, then adjust with judgment and the67evidence you read (the script is heuristic; a JS-rendered SPA can hide content from a fetch, so a68weak score may be a false negative — note it). Full checklists, the community directory, and the69scoring rubric are in **`reference.md`** — the dimensions:7071| Dimension | Look for (see reference.md for the full list) |72| :-- | :-- |73| **Crawlability / indexing** | `robots.txt`, XML `sitemap`, canonical URLs, no accidental `noindex`, clean URLs, SPA pre-render/SSR |74| **SEO** | unique `<title>` + meta description, heading hierarchy, semantic HTML, structured data (JSON-LD), internal links, image `alt` |75| **AI-readiness** | `llms.txt`, machine-readable data (JSON-LD/schema.org), semantic markup, clean content extraction, an API or feed where it fits |76| **Social / sharing** | Open Graph (`og:title/description/image`), Twitter card, a share image that renders, canonical social handles linked |77| **Brand assets / standards** | favicon set + `apple-touch-icon`, logo (incl. SVG), a clear **tagline**, consistent naming, `manifest.webmanifest`, 404 page |78| **Security / hygiene** | HTTPS + HSTS, security headers (CSP, X-Content-Type-Options, Referrer-Policy), no secrets/source maps leaked, deps current, `security.txt` |79| **Performance / load** | payload size, render-blocking JS/CSS, image format/sizing (AVIF/WebP, dimensions), caching/CDN, lazy-loading, Core Web Vitals |80| **Accessibility** | `lang`, `viewport`, contrast, labels/alt, focus order, keyboard nav (a11y is also SEO + reach) |81| **Growth / community / PR** | analytics present, where this *type* is discovered, communities to join or submit to, easy PR/advertising wins (see reference.md) |8283## 4. Report — standardized format (consistent every time)8485Lead with the scorecard, then prioritize. Use this exact order so reports are comparable run-to-run:86871. **Classification** (type, audience, goal) in one line, so every recommendation is anchored.882. **Scorecard** — the **overall grade + score**, then the per-dimension grades (reuse the script's89 table; re-grade a dimension only when you have evidence the heuristic was wrong, and say why).903. **Top fixes**, ranked by **impact × effort** — lead with high-impact/low-effort (e.g. "add a91 `meta description` and an `og:image`: 10 min, big SEO + share-CTR win"). Each cites evidence.924. **By dimension**, the per-dimension grade + the specifics behind it (what passed / what to fix).935. **Growth plan** for *this* type & community: concrete places to submit/join (Product Hunt, HN,94 relevant subreddits/Discords, dev.to, Indie Hackers, awesome-lists, app stores, directories —95 pick by type; reference.md has the directory), plus PR/advertising wins that suit the audience.966. **What's already good** — affirm it; don't only list problems.9798Be honest about confidence and limits: a black-box URL scan can't see the codebase, server config,99or analytics; say what you'd need (repo access, the build dir, the CMS) to go deeper. Verify claims100against real output — don't assert a tag is missing without checking, and prefer fixing root causes101(a layout/template) over per-page patches.102103See `reference.md` for the full per-dimension checklists, the by-type community/submission104directory, the AI-readiness and `llms.txt` guidance, and the impact×effort scoring rubric.
cportka