Viral Product Evaluator
Grade a product against the 32 principles of viral products. Two inputs — a codebase and a
landing page — produce one output: a scored report of what's already satisfied and, in
priority order, what to do next to make it more viral.
When to Use
Trigger when the user wants to:
- Make a product, SaaS, or indie app "more viral" or more shareable
- Score / audit a landing page against viral-marketing or conversion principles
- Get a prioritized, ordered list of changes to improve a product's pull
- Check a product against "the 32 principles" (Marc Lou-style viral-product rules)
Do not use for: technical SEO (seo-ai-optimizer), App Store ASO (aso-marketing),
turning a README into a page (landing-page-generator), or bug-hunting code review
(code-review). This skill
evaluates and prioritizes; it does not rewrite the product.
Prerequisites
- Read access to the target codebase directory.
- Landing page signal: public URL, local file, or auto-detectable in the tree.
- The skill's
references/*.md files present for the rubric and output shape.
- User confirmation on any deviation from the 32 principles.
Missing prerequisites → stop and report before gathering evidence.
What this skill does and does not touch
It reads the codebase, fetches the landing page, and writes one report file
(viral-evaluation.md). It does not edit the user's source, change copy, or commit
anything — so no repo-sync/branch guardrail is needed. If the user then asks you to apply
fixes, that is a separate task (hand off to a copy/frontend skill); this skill stops at the
prioritized plan.
Dependency Preflight (mandatory)
This skill invokes /browse, and only on the live URL path — a local file or an
auto-detected page needs nothing installed. Resolve it before fetching anything:
test -d "$HOME/.claude/skills/browse" || asm list -p claude --json | grep -q '"browse"' || {
echo "Missing required skill: browse" >&2
echo "Install it: asm install github:garrytan/gstack:browse -p claude -s global --yes" >&2
echo "No asm yet: npm install -g agent-skill-manager" >&2
echo "Verify: asm list -p claude --json | grep 'browse'" >&2
}
The install-path test runs first because /browse ships in gstack and may be present without
asm knowing about it. -p claude -s global is required: asm install will not guess a provider
non-interactively, and a project-scoped install lands where the $HOME test cannot see it.
A missing /browse is fail-soft, not fatal: print the commands above, then ask the user for a
local file or saved HTML of the page. Never score a URL you could not load — do not invent one.
Inputs
Accept any combination the user provides; ask only for what's missing and truly needed.
- Landing page — one of:
- a live URL → fetch it with the
/browse skill (headless). Capture rendered copy,
headline, CTAs, pricing section, testimonials, nav, and <head> meta (og:image,
twitter:image, description, <title>).
- a local file (
index.html, a JSX/TSX/MDX page, a built dist/) → read it directly.
- auto-detect from the codebase → search for the landing/marketing page (common spots:
index.html, app/page.tsx, pages/index.*, src/App.*, landing/, marketing/,
public/). Confirm the candidate with the user if ambiguous.
- Codebase — a path to the repo (defaults to the current working directory). Used for the
pricing/paywall/subscription principles, the feature surface ("does one thing"), and to
locate the landing page if no URL/file was given.
- Extra instructions (optional) — strategic context such as "we keep a free tier on
purpose", "target audience is developers", "we must stay subscription". Honor these when
interpreting a verdict (note the deliberate deviation) but still score the principle as
written so the number stays comparable.
If neither a URL, a file, nor a detectable page exists, stop and ask the user where the landing
page lives — do not invent one.
Pipeline (3 phases, in order)
Run these in sequence. Emit the matching Step Completion Report (see
references/step-reports.md) after each.
Phase 1 — Resolve inputs & gather evidence
- Resolve the landing page input (URL →
/browse; file → read; else auto-detect).
- Locate the codebase and find monetization evidence: billing SDKs (Stripe, Paddle,
LemonSqueezy, RevenueCat, Chargebee), pricing config/constants, plan & tier definitions,
paywall/auth gating, trial logic. Grep for
price, plan, tier, checkout,
subscription, free, trial, stripe, paddle.
- Skim the feature surface (routes, nav items, top-level modules) to judge "does one thing".
- For a large codebase, use grep/read (or a one-off Agent task scoped to pricing +
feature evidence) so the main context stays clean. Collect: tier list, billing type (one-time
vs subscription), free-plan yes/no, and a one-line feature inventory.
- Note any extra instructions from the user.
Phase 2 — Evaluate against the 32 principles
- Read
references/principles.md — the full rubric. Score every principle PASS / PARTIAL /
FAIL using its criteria. Do not skip any; absence of a thing a viral product would ship
(pricing, testimonials, demo) is a real FAIL, not "unknown".
- For each verdict, capture specific evidence from THIS product — quote the actual headline,
name the actual tier, cite the file/line. Generic findings are not acceptable.
- Tag every
judgment/visual principle (hero punch, emotional headline, OG-image design,
founder presence, novelty, price-vs-competitor) as low-confidence and record what a human
must eyeball.
- Compute the Virality Score:
PASS=1, PARTIAL=0.5, FAIL=0, summed over 32, ×100/32,
rounded. Assign the tier (Viral-ready / Promising / Needs work / Not viral yet).
Phase 3 — Prioritize fixes & write the report
- Read
references/report-template.md and produce the report in that exact shape:
verdict block → scorecard (all 32) → top fixes (prioritized) → what's working → caveats.
- The top fixes list is the core deliverable. Order by impact × ease, hero/paywall/
headline/proof/single-CTA first. Merge principles that share a root cause into one fix. Make
each fix concrete enough to act on (give the actual proposed headline, the tier to cut, the
CTA label) — quote what it is Now and what to Change it to.
- Always write the report to
viral-evaluation.md — repo root, or the current working directory
when there is no repo — and also print the verdict block + top fixes inline.
Honest evaluation
This is a critique tool — its value is candor. Do not inflate scores to be encouraging. If the
hero fails, say it fails and show the fix. At the same time, do not invent flaws: a genuine PASS
is a PASS. Low-confidence verdicts must be labeled, never laundered into false certainty. When
extra instructions justify a deliberate deviation (e.g. a strategic free tier), score the
principle as written and explain the trade-off in the caveats — don't silently pass it.
On any failure to fetch inputs or read evidence, report the concrete error and stop — do not
guess or continue with incomplete data. Confirm with the user on every gate and before
finalizing the report. If a principle cannot be evidenced, mark FAIL or low-confidence; never invent.
Step Completion Reports
After each phase, emit the report from references/step-reports.md. The three phases are
Gather Evidence, Evaluate, and Prioritize & Report.
Acceptance Criteria
- All 32 principles scored with specific evidence quoted from the product.
- Virality Score computed correctly (PASS=1, PARTIAL=0.5, FAIL=0) and tier assigned.
- Top fixes are concrete, prioritized by impact×ease, with before/after suggestions.
- Report always written to viral-evaluation.md (repo root, else the current working directory) and
also printed inline; Step Completion Reports emitted per phase.
- Negative-trigger domains respected (no SEO/ASO/copy/code-review work).
Expected output
A report containing:
- Overall verdict + Virality Score (e.g. 68 — Promising)
- Scorecard table for all 32 principles
- Top 5-8 prioritized fixes with exact copy or code recommendations
- What's already working
- Caveats / low-confidence items
Edge cases
- No landing page detectable: ask for URL or file; do not fabricate.
- Codebase only (no public page): still score what can be inferred from code (pricing etc).
- Strategic deviation justified by user (e.g. no testimonials by design): score as written, note the trade-off in caveats.
- Partial evidence: mark affected principles low-confidence, never guess a PASS.
Reference files
references/principles.md — the 32-principle rubric: per-principle checks, evidence source,
PASS/PARTIAL/FAIL bars, confidence flags, and the scoring formula. Load every run.references/report-template.md — exact output shape (verdict block, scorecard, prioritized
fixes, strengths, caveats) with a calibration example.references/step-reports.md — Step Completion Report formats for the three phases.
1---2name: viral-product-evaluator3description: Review a product codebase and landing page against 32 viral principles and produce a Virality Score plus ranked fixes. Use to audit virality or prioritize growth. Don't use for SEO, ASO, copywriting, or code review.4license: MIT5---67# Viral Product Evaluator89Grade a product against the 32 principles of viral products. Two inputs — a **codebase** and a10**landing page** — produce one output: a scored report of **what's already satisfied** and, in11**priority order, what to do next to make it more viral**.1213## When to Use1415Trigger when the user wants to:16- Make a product, SaaS, or indie app "more viral" or more shareable17- Score / audit a landing page against viral-marketing or conversion principles18- Get a prioritized, ordered list of changes to improve a product's pull19- Check a product against "the 32 principles" (Marc Lou-style viral-product rules)2021Do **not** use for: technical SEO (`seo-ai-optimizer`), App Store ASO (`aso-marketing`),22turning a README into a page (`landing-page-generator`), or bug-hunting code review23(`code-review`). This skill24**evaluates and prioritizes**; it does not rewrite the product.2526## Prerequisites2728- Read access to the target codebase directory.29- Landing page signal: public URL, local file, or auto-detectable in the tree.30- The skill's `references/*.md` files present for the rubric and output shape.31- User confirmation on any deviation from the 32 principles.3233Missing prerequisites → stop and report before gathering evidence.3435## What this skill does and does not touch3637It **reads** the codebase, **fetches** the landing page, and **writes one report file**38(`viral-evaluation.md`). It does **not** edit the user's source, change copy, or commit39anything — so no repo-sync/branch guardrail is needed. If the user then asks you to *apply*40fixes, that is a separate task (hand off to a copy/frontend skill); this skill stops at the41prioritized plan.4243## Dependency Preflight (mandatory)4445This skill invokes `/browse`, and only on the **live URL** path — a local file or an46auto-detected page needs nothing installed. Resolve it before fetching anything:4748```bash49test -d "$HOME/.claude/skills/browse" || asm list -p claude --json | grep -q '"browse"' || {50 echo "Missing required skill: browse" >&251 echo "Install it: asm install github:garrytan/gstack:browse -p claude -s global --yes" >&252 echo "No asm yet: npm install -g agent-skill-manager" >&253 echo "Verify: asm list -p claude --json | grep 'browse'" >&254}55```5657The install-path test runs first because `/browse` ships in gstack and may be present without58`asm` knowing about it. `-p claude -s global` is required: `asm install` will not guess a provider59non-interactively, and a project-scoped install lands where the `$HOME` test cannot see it.6061A missing `/browse` is **fail-soft**, not fatal: print the commands above, then ask the user for a62local file or saved HTML of the page. Never score a URL you could not load — do not invent one.6364## Inputs6566Accept any combination the user provides; ask only for what's missing and truly needed.67681. **Landing page** — one of:69 - a **live URL** → fetch it with the `/browse` skill (headless). Capture rendered copy,70 headline, CTAs, pricing section, testimonials, nav, and `<head>` meta (`og:image`,71 `twitter:image`, `description`, `<title>`).72 - a **local file** (`index.html`, a JSX/TSX/MDX page, a built `dist/`) → read it directly.73 - **auto-detect** from the codebase → search for the landing/marketing page (common spots:74 `index.html`, `app/page.tsx`, `pages/index.*`, `src/App.*`, `landing/`, `marketing/`,75 `public/`). Confirm the candidate with the user if ambiguous.762. **Codebase** — a path to the repo (defaults to the current working directory). Used for the77 pricing/paywall/subscription principles, the feature surface ("does one thing"), and to78 locate the landing page if no URL/file was given.793. **Extra instructions** (optional) — strategic context such as "we keep a free tier on80 purpose", "target audience is developers", "we must stay subscription". Honor these when81 *interpreting* a verdict (note the deliberate deviation) but still score the principle as82 written so the number stays comparable.8384If neither a URL, a file, nor a detectable page exists, stop and ask the user where the landing85page lives — do not invent one.8687## Pipeline (3 phases, in order)8889Run these in sequence. Emit the matching Step Completion Report (see90`references/step-reports.md`) after each.9192### Phase 1 — Resolve inputs & gather evidence9394- Resolve the landing page input (URL → `/browse`; file → read; else auto-detect).95- Locate the codebase and find **monetization evidence**: billing SDKs (Stripe, Paddle,96 LemonSqueezy, RevenueCat, Chargebee), pricing config/constants, plan & tier definitions,97 paywall/auth gating, trial logic. Grep for `price`, `plan`, `tier`, `checkout`,98 `subscription`, `free`, `trial`, `stripe`, `paddle`.99- Skim the **feature surface** (routes, nav items, top-level modules) to judge "does one thing".100- For a large codebase, use **grep/read** (or a one-off **Agent** task scoped to pricing +101 feature evidence) so the main context stays clean. Collect: tier list, billing type (one-time102 vs subscription), free-plan yes/no, and a one-line feature inventory.103- Note any extra instructions from the user.104105### Phase 2 — Evaluate against the 32 principles106107- Read `references/principles.md` — the full rubric. Score **every** principle PASS / PARTIAL /108 FAIL using its criteria. Do not skip any; absence of a thing a viral product would ship109 (pricing, testimonials, demo) is a real **FAIL**, not "unknown".110- For each verdict, capture **specific evidence from THIS product** — quote the actual headline,111 name the actual tier, cite the file/line. Generic findings are not acceptable.112- Tag every `judgment`/`visual` principle (hero punch, emotional headline, OG-image design,113 founder presence, novelty, price-vs-competitor) as **low-confidence** and record what a human114 must eyeball.115- Compute the **Virality Score**: `PASS=1, PARTIAL=0.5, FAIL=0`, summed over 32, ×100/32,116 rounded. Assign the tier (Viral-ready / Promising / Needs work / Not viral yet).117118### Phase 3 — Prioritize fixes & write the report119120- Read `references/report-template.md` and produce the report in that exact shape:121 **verdict block → scorecard (all 32) → top fixes (prioritized) → what's working → caveats**.122- The **top fixes** list is the core deliverable. Order by **impact × ease**, hero/paywall/123 headline/proof/single-CTA first. Merge principles that share a root cause into one fix. Make124 each fix concrete enough to act on (give the actual proposed headline, the tier to cut, the125 CTA label) — quote what it is **Now** and what to **Change** it to.126- Always write the report to `viral-evaluation.md` — repo root, or the current working directory127 when there is no repo — and also print the verdict block + top fixes inline.128129## Honest evaluation130131This is a critique tool — its value is candor. Do not inflate scores to be encouraging. If the132hero fails, say it fails and show the fix. At the same time, do not invent flaws: a genuine PASS133is a PASS. Low-confidence verdicts must be labeled, never laundered into false certainty. When134extra instructions justify a deliberate deviation (e.g. a strategic free tier), score the135principle as written and explain the trade-off in the caveats — don't silently pass it.136137On any failure to fetch inputs or read evidence, report the concrete error and stop — do not138guess or continue with incomplete data. Confirm with the user on every gate and before139finalizing the report. If a principle cannot be evidenced, mark FAIL or low-confidence; never invent.140141## Step Completion Reports142143After each phase, emit the report from `references/step-reports.md`. The three phases are144**Gather Evidence**, **Evaluate**, and **Prioritize & Report**.145146## Acceptance Criteria147148- All 32 principles scored with specific evidence quoted from the product.149- Virality Score computed correctly (PASS=1, PARTIAL=0.5, FAIL=0) and tier assigned.150- Top fixes are concrete, prioritized by impact×ease, with before/after suggestions.151- Report always written to viral-evaluation.md (repo root, else the current working directory) and152 also printed inline; Step Completion Reports emitted per phase.153- Negative-trigger domains respected (no SEO/ASO/copy/code-review work).154155## Expected output156157A report containing:158- Overall verdict + Virality Score (e.g. 68 — Promising)159- Scorecard table for all 32 principles160- Top 5-8 prioritized fixes with exact copy or code recommendations161- What's already working162- Caveats / low-confidence items163164## Edge cases165166- No landing page detectable: ask for URL or file; do not fabricate.167- Codebase only (no public page): still score what can be inferred from code (pricing etc).168- Strategic deviation justified by user (e.g. no testimonials by design): score as written, note the trade-off in caveats.169- Partial evidence: mark affected principles low-confidence, never guess a PASS.170171---172173## Reference files174175- `references/principles.md` — the 32-principle rubric: per-principle checks, evidence source,176 PASS/PARTIAL/FAIL bars, confidence flags, and the scoring formula. **Load every run.**177- `references/report-template.md` — exact output shape (verdict block, scorecard, prioritized178 fixes, strengths, caveats) with a calibration example.179- `references/step-reports.md` — Step Completion Report formats for the three phases.
luongnv89