v1.6.0 to v1.7.0

118 added, 102 removed. Audit A to A.

---

name: "viral-product-evaluator"

description: "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."

license: MIT

effort: high

+ dependencies:

+ - browse

metadata:

- version: 1.6.0

+ version: 1.7.0

author: "Luong NGUYEN <luongnv89@gmail.com>"

---

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

+ (`code-review`).

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

+ - Landing page signal: public URL, local file, auto-detectable in the tree, or an

+ orchestrator's `evidence-dir`.

+ - The skill's `references/*.md` files present.

- Missing prerequisites → stop and report before gathering evidence.

+ Missing prerequisites after the one ask in Edge cases → stop with a BLOCKED response

+ (`references/final-report.md`) 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.

+ (`viral-evaluation.md`) — it never edits source, changes copy, or commits. Applying fixes is

+ a separate task for 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, an

- auto-detected page, or an orchestrator's `evidence-dir` needs nothing installed. Resolve it before fetching anything:

+ This skill invokes `/browse` (frontmatter `dependencies`), and only on the **live URL** path;

+ every other input needs nothing installed. Run once, before the first fetch:

```bash

- 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

- }

+ if test -f "$HOME/.claude/skills/browse/SKILL.md"; then

+ echo "browse_mode=installed browse_skill=$HOME/.claude/skills/browse/SKILL.md"

+ elif test -f "$HOME/.agents/skills/browse/SKILL.md"; then

+ echo "browse_mode=installed browse_skill=$HOME/.agents/skills/browse/SKILL.md"

+ elif command -v asm >/dev/null && asm deps --help >/dev/null 2>&1; then

+ asm deps discover viral-product-evaluator --json || echo "discover failed; acquire still runs" >&2

+ echo "browse_mode=lease"

+ else

+ echo "Missing skill: browse. Install: asm install github:garrytan/gstack:browse -p claude -s global --yes" >&2

+ echo "No asm yet: npm install -g agent-skill-manager@latest" >&2

+ echo "browse_mode=none"

+ fi

+ printf 'vpe_session=%s\n' "viral-product-evaluator-$(date +%s)-$$" # record it; reuse it verbatim

```

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

+ The install-path tests run first because gstack may install `/browse` without `asm` knowing.

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

+ 1. `browse_mode=installed`: read the recorded `browse_skill` path.

+ 2. `browse_mode=lease`: run `asm deps acquire browse --session <vpe_session> --json`; read the

+ returned `skillMdPath` directly.

+ 3. `browse_mode=none`, or step 2 failed: **fail-soft** — print the install lines, then ask the

+ user for a local file or saved HTML of the page. Never score a URL you could not load.

+ 4. **Release in `finally`.** If step 2 ran, run `asm deps release --session <vpe_session> --json`

+ once at every terminal outcome, stops included.

## Repo Sync Before Edits (mandatory)

- Phase 3 writes `viral-evaluation.md` to the repo root or current working directory. When that path lives inside a git worktree, sync before the write to avoid clobbering remote work:

- ```bash

- branch="$(git rev-parse --abbrev-ref HEAD)"

- git fetch origin

- git pull --rebase origin "$branch"

- ```

- If the working tree is dirty: stash → sync → pop. If `origin` is missing or a conflict occurs: **stop and ask the user.** Skip this section only when the output path is outside any git repository.

+ Phase 3 writes `viral-evaluation.md`. An inline-only run never syncs or stashes a checkout.

+ When the output path is inside a git worktree, follow `references/repo-sync.md`: confirm with

+ the user, then stash, sync and pop before the write.

## Inputs

- Accept any combination the user provides; ask only for what's missing and truly needed.

- 1. **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.

+ 1. **Landing page** — resolve in this order:

- an orchestrator's **`evidence-dir`** → read its `page.html` + `head.json`; no `/browse`.

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

+ - a **live URL** → run the Dependency Preflight, confirm the fetch with the user, then load

+ 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 the common spots (`index.html`, `app/page.tsx`,

+ `pages/index.*`, `src/App.*`, `landing/`, `marketing/`, `public/`). If exactly one

+ candidate is found, use it. If none or several are found, ask the user.

2. **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.

+ pricing/paywall principles, the feature surface, and landing-page auto-detection.

3. **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.

+ purpose". Honor these when *interpreting* a verdict (note the deliberate deviation) but

+ still score the principle as written so the number stays comparable.

## 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 (`evidence-dir` → saved files; 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.

+ 1. Resolve the landing page per *Inputs*.

+ 2. Locate the codebase (default: the current working directory).

+ 3. Grep it for `price`, `plan`, `tier`, `checkout`, `subscription`, `free`, `trial`, `stripe`,

+ `paddle` and read the matches.

+ 4. Record the monetization evidence section A of the rubric lists (`references/principles.md`).

+ When nothing matches, record "no billing evidence found" — that is itself evidence.

+ 5. Skim routes, nav items and top-level modules; record a one-line feature inventory.

+ 6. When the codebase is too large for the context budget, delegate steps 3–5 to a one-off

+ **Agent** task scoped to pricing and feature evidence.

+ 7. 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** with `scripts/virality_score.py`: pass every verdict as

- `{"verdicts": {"<principle number>": "PASS|PARTIAL|FAIL", ...}}` and use the helper's

- `counts`, `score`, and `tier` (contract in `references/principles.md` → Scoring). Do not

- tally or round in prose.

+ 1. Read `references/principles.md` — the full rubric.

+ 2. Score **every** principle PASS / PARTIAL / FAIL; never skip one. Absence of a thing a viral

+ product would ship (pricing, testimonials, demo) is a real **FAIL**, not "unknown".

+ 3. Quote product-specific evidence for each verdict — the actual headline, the actual tier,

+ the file/line. Generic findings are not acceptable.

+ 4. Tag every `judgment`/`visual` principle (hero punch, emotional headline, OG-image design,

+ founder presence, novelty, price-vs-competitor) **low-confidence** and record what a human

+ must eyeball. When a principle's evidence source was unavailable (no codebase access, a

+ failed fetch), tag it low-confidence as well and say why.

+ 5. Compute the **Virality Score** with `scripts/virality_score.py` — pass every verdict as

+ `{"verdicts": {"<n>": "PASS|PARTIAL|FAIL", ...}}` (contract in `references/principles.md` →

+ Scoring). Do not tally or round in prose.

### 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` — `output-dir` when given, else repo root, or

- the current working directory when there is no repo — and also print the verdict block + top

- fixes inline.

+ 1. Read `references/report-template.md` and build the report in that exact shape: verdict

+ block → scorecard (all 32) → top fixes → what's working → caveats.

+ 2. Order the top fixes by **impact × ease**, hero/paywall/headline/proof/single-CTA first;

+ merge principles sharing a root cause into one fix.

+ 3. Make each fix concrete enough to act on — the actual proposed headline, the tier to cut,

+ the CTA label — quoting **Now** and **Change**.

+ 4. Print the verdict block and top fixes inline, then ask the user to confirm writing the

+ report. One confirmation covers the write and, when the output path is inside a git

+ worktree, the sync.

+ 5. On confirmation: run `references/repo-sync.md` when needed, then write

+ `viral-evaluation.md` to `output-dir`, else the repo root, else the current working

+ directory.

+ 6. When the user declines, return the full report inline and mark the run PARTIAL.

+ 7. Close with the final response from `references/final-report.md`, including its status rule.

## Orchestrated Runs

With `orchestrated-by`, `evidence-dir`, `skip-checks` or `output-dir` lines, follow

`references/orchestrated-runs.md`; without them nothing changes. All 32 principles are

always scored.

## Honest evaluation

- This is a critique tool — its value is candor: never inflate scores, never invent flaws, label low-confidence verdicts. The full candor rules are in `references/honest-evaluation.md`.

+ This is a critique tool — its value is candor. The full candor rules are in

+ `references/honest-evaluation.md`.

## Step Completion Reports

- After each phase, emit the report from `references/step-reports.md`. The three phases are

- **Gather Evidence**, **Evaluate**, and **Prioritize & Report**.

+ After each phase, emit the report from `references/step-reports.md` — **Gather Evidence**,

+ **Evaluate**, **Prioritize & Report**.

## Acceptance Criteria

- - All 32 principles scored with specific evidence quoted from the product.

- - Virality Score and tier come from `scripts/virality_score.py` over all 32 verdicts

- (PASS=1, PARTIAL=0.5, FAIL=0); per-principle verdicts and evidence remain model-owned.

+ - All 32 principles scored with product-specific evidence quoted.

+ - Virality Score and tier come from `scripts/virality_score.py` over all 32 verdicts;

+ verdicts and evidence remain model-owned.

- Top fixes are concrete, prioritized by impact×ease, with before/after suggestions.

- - Report always written to viral-evaluation.md (`output-dir`, else repo root, else the current working directory) and

- also printed inline; Step Completion Reports emitted per phase.

+ - Report written to viral-evaluation.md after the user's confirmation, or returned inline when

+ declined; Step Completion Reports emitted per phase.

+ - The final response follows `references/final-report.md`: `Result: PASS | PARTIAL | BLOCKED`

+ first, then Evidence, Uncertainty and Decision.

+ - Reader checks: main result findable in the first line, facts separated from assumptions,

+ claims traceable to evidence, next decision clear.

- Negative-trigger domains respected (no SEO/ASO/copy/code-review work).

## Expected output

- A report containing:

+ A `viral-evaluation.md` report (plus an inline summary and a `Result:`-first final response)

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

+ - No landing page: ask once for a URL or file; if the user confirms none exists, score

+ codebase-only (LP principles FAIL with a caveat); without an answer, end BLOCKED. Never

+ fabricate a page.

+ - `/browse` missing for a live URL: fail-soft per the Dependency Preflight.

+ - Strategic deviation (e.g. no testimonials by design): score as written, note the trade-off

+ in caveats.

+ - Partial evidence (a fetch failed mid-run): mark affected principles low-confidence, never

+ guess a PASS.

+ - User declines the report write: return the report inline; the run is PARTIAL.

+ - Output path inside a git worktree: confirm, then sync per `references/repo-sync.md` before

+ writing.

---

## Reference files

- `references/principles.md` — the 32-principle rubric: per-principle checks, evidence source,

PASS/PARTIAL/FAIL bars, confidence flags, and the `scripts/virality_score.py` scoring

contract. **Load every run.**

- - `references/report-template.md` — exact output shape (verdict block, scorecard, prioritized

- fixes, strengths, caveats) with a calibration example.

+ - `references/report-template.md` — the exact report shape, with a calibration example.

+ - `references/final-report.md` — the final chat response: status rule (PASS / PARTIAL /

+ BLOCKED), response shapes, and the reader-check criteria.

+ - `references/repo-sync.md` — the confirm-first sync procedure for an output path inside a git

+ worktree.

- `references/step-reports.md` — Step Completion Report formats for the three phases.

- - `references/honest-evaluation.md` — the full candor rules: no inflation, no invented flaws,

- labelled low-confidence, stop on fetch/read failure.

+ - `references/honest-evaluation.md` — the candor rules: no inflation, no invented flaws,

+ labelled low-confidence.

- `scripts/virality_score.py` — deterministic Virality Score + tier helper (`tests/` holds its

stdlib fixtures).