/viral-product-evaluator

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

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

Prerequisites

• Read access to the target codebase directory.
• 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 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 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` (frontmatter `dependencies`), and only on the **live URL** path; every other input needs nothing installed. Run once, before the first fetch:

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 tests run first because gstack may install `/browse` without `asm` knowing.

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

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

• an orchestrator's **`evidence-dir`** → read its `page.html` + `head.json`; no `/browse`.
• 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 principles, the feature surface, and landing-page auto-detection. 3. **Extra instructions** (optional) — strategic context such as "we keep a free tier on 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)

Phase 1 — Resolve inputs & gather evidence

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

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