@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/enhance-skill-prompts/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: enhance-skill-prompts
+description: >
+  Upgrade how an existing SKILL.md instructs, not what it does: freedom, a
+  classification contract, one worked example, an evidence rubric, effort. Use
+  when "enhance this skill's prompts", "upgrade skill authoring", or "apply
+  the prompt playbook".
+license: MIT
+effort: high
+---
+
+# enhance-skill-prompts — Upgrade HOW a skill instructs, never WHAT it does
+
+**Degree of freedom: LOW-to-MEDIUM.** This is a fragile transformation. A
+well-meant rewrite can change behavior. Follow the phases in order. Preserve
+intent, scope, and family semantics exactly. If a change would alter
+behavior, scope, or read-only / plan-only / apply-now stance, stop and flag
+it instead.
+
+Grounded in [docs/PROMPT-ENHANCEMENT-PLAYBOOK.md](../../docs/PROMPT-ENHANCEMENT-PLAYBOOK.md)
+and the annotated exemplar
+[references/exemplar-audit-auth-flows.md](references/exemplar-audit-auth-flows.md).
+Live reference after the exemplar was applied:
+`skills/audit-auth-flows/SKILL.md`. New skill from scratch →
+`meta-skill-creator`.
+
+## Phase 0 — Classify the skill  [HIGH freedom]
+
+Read the target SKILL.md and determine:
+
+- **Family & register:** audit/plan (interpretive → mostly HIGH) vs
+  housekeep/deploy/migration (fragile sequences → LOW where a step must be
+  exact).
+- **Judgment points:** triage, severity, root cause, winner-selection → T2/T3.
+- **Fragile steps:** probes, baseline capture, destructive ops → T1 LOW.
+- **Existing example:** is the `## Worked example` a real few-shot (chain plus output shape on a concrete case) or a placeholder?
+- **Effort tier (T7):** which family the skill belongs to, and therefore which `effort:` it declares.
+
+State the classification before editing. It decides which techniques apply.
+
+## Phase 1 — Apply T1–T8 (only where they fit)  [HIGH freedom]
+
+Apply in this order. Skip any technique that does not fit and record why.
+
+**T1 — Declare degrees of freedom.** Short register line under the H1.
+Where mixed, tag fragile phases `[LOW freedom — run exactly]` and
+interpretive ones `[HIGH freedom]`. Do not over-constrain interpretive
+audits or under-constrain fragile sequences.
+
+**T2 — One named-stage judgment frame.** The stages a conclusion must
+pass through (audits: Observe → Interpret → Classify → Severity; plans:
+Propose → Risk → Keep-working → Phase). Place it ONCE near the top and
+reference it. It defines what a finding must contain, not how to think:
+reasoning depth comes from `effort:` (T7), and generic "think step by
+step" or "double-check" prose is dead weight on Opus 5.5.
+
+**T3 — Exactly one worked example.** The chain AND the output shape on a
+realistic case, labeled illustrative. Put it right after the T2 frame.
+
+**T4 — Self-critique rubric before output.** Explicit, answerable checks
+(evidenced-not-assumed, reproducible, severity-justified, right-owner,
+no-false-safety). Plan skills: run this before presenting the burndown.
+Opus 5.5 self-verifies unprompted, so each rubric line must name the
+evidence it is checked against (a tool result, a rendered rect, a header,
+a CI run); a line that is a generic re-check ("verify your work",
+"double-check") is cut. Principle-based ("constitutional-style") checking
+belongs here as a rubric, not a label.
+
+**T5 — Terminology consistency.** One term per concept. Unify
+gate/check/guard, finding/issue/problem, user/caller/client to the skill's
+dominant term.
+
+**T6 — Conciseness.** Cut restated context the agent already has. Never
+trim a fragile step's exactness. Net tokens should usually drop even after
+T2+T3.
+
+**T7 — Effort routing.** Declare `effort:` in frontmatter by family:
+audit / plan / judge / security / architecture → `high` (`xhigh` only for
+the hardest planning, with a measured reason); mechanical, read-only,
+formatting, handoff, inventory → `low`; ordinary implementation → omit
+(Opus 5.5 defaults to `medium`, which matches Opus 5 at high). A read-only
+inventory skill may add `context: fork` + `agent: Explore` to keep the main
+context clean. Cursor ignores the key; `validate:skills` checks its value.
+Effort is the only thinking control on Opus 5.5 — never steer depth with
+prose ("think harder", "don't overthink", "double-check").
+
+**T8 — Volume, shape, and communication.** Each rule once, at normal
+volume, with its reason — drop MUST / NEVER / CRITICAL markers, "be
+thorough", and update suppressors ("no preamble", "don't narrate"): Opus
+5.5 follows instructions literally, so emphasis over-triggers and
+suppressors leave the user blind between tool calls. State the success
+condition instead of a prohibition list. Exception: frontend design
+direction works best as *named* default patterns to avoid (cream
+background, italic accent word in headlines, "01 / 02 / 03" section
+labels, monospace labels, pill buttons, Inter / Roboto, purple gradients,
+three equal cards) — "avoid a generic AI look" swaps one default for
+another. Numbered steps only for fragile sequences (destructive ops, auth,
+migrations, baseline capture); judgment phases get outcomes, constraints,
+and how to verify. The always-on verification rule already asks for an
+intent line, load-bearing notes and a standalone recap; do not repeat it
+per skill and never suppress it ("no preamble", "hold findings"). Skills
+that run unattended add one line saying when the turn may end.
+
+## How to reason
+
+1. **Observe** — existing H1 register, phases, examples, body length
+2. **Interpret** — which of T1–T8 are missing vs already present as headings or keys
+3. **Classify** — apply / skip-with-reason / stop (would change behavior)
+4. **Severity** — a trigger or stance change is an invalid edit
+
+## Worked example
+
+> **Observe:** `meta-skill-creator` has T1 and a technique table; no `## Worked example`.
+> **Interpret:** the table mention is not T3; the agent still has no few-shot.
+> **Classify:** add one `## Worked example` + `## Self-critique` after the table; do not rewrite Anatomy or frontmatter.
+> **Invariant:** description triggers unchanged; still "create a pack SKILL.md".
+
+## Self-critique before reporting
+
+- **Headings exist** — T3 is `## Worked example`, T4 is `## Self-critique…`, not a table cell
+- **Behavior same** — no phase-order, stance, or trigger change
+- **One example** — not a second tutorial
+- **Right owner** — new skill from scratch → `meta-skill-creator`
+
+## Phase 2 — Preserve invariants  [LOW freedom — run exactly]
+
+The edit is invalid if any of these break:
+
+- Same **name, description triggers, and scope** — routing must not change.
+- Same **behavior and stance** — read-only stays read-only; apply-now stays
+  apply-now; plan-only stays plan-only; phase order and Definition-of-Done
+  coverage unchanged in substance.
+- **House limits** — description ≤320 chars (same folding as
+  `scripts/validate-skills.mjs`), body <500 lines, name matches dir.
+- **Frontmatter:** `name` and `description` untouched unless a within-budget
+  description change is explicitly requested. Adding or adjusting `effort:`
+  (T7) is allowed and is not a routing change.
+- Cross-references use live skill names; the responsive skill is `audit-responsive`.
+- Strip `<!-- TECHNIQUE -->` comments from live SKILL.md (they belong only
+  in the exemplar).
+
+If any invariant would break, revert that change and note it.
+
+## Phase 3 — Report the diff  [LOW freedom — do not skip]
+
+Do not silently rewrite. Present, per skill:
+
+1. **Classification** — family | register | judgment points | fragile steps | has-example?
+2. **Technique table** — technique | applied? | where | why-skipped-if-not
+3. **Section diffs** — before/after for each change
+4. **Invariant check** — each invariant | holds?
+
+Apply on approval. For a batch, finish one skill as reference, get
+sign-off, then proceed.
+
+## Definition of Done
+
+- [ ] Skill classified before editing
+- [ ] T1–T8 applied or skipped with a reason
+- [ ] Invariants verified; frontmatter triggers unchanged
+- [ ] Diff reported; applied only on approval
+
+## Related
+
+- `meta-skill-creator` — new SKILL.md from scratch
+- `audit-skill-conflicts` — routing / coherence after a batch
+- `validate:skills` — per-file spec after edits

package/skills/enhance-skill-prompts/references/exemplar-audit-auth-flows.md

@@ -0,0 +1,311 @@
+> Teaching copy of `audit-auth-flows` with technique annotations (`<!-- TECHNIQUE -->`).
+> Live shipped file (comments stripped; pack frontmatter unchanged):
+> `skills/audit-auth-flows/SKILL.md`.
+
+---
+name: audit-auth-flows
+description: >
+  Read-only audit of app-layer auth: route×gate matrix, session lifecycle,
+  OAuth, provider traps (getSession vs getUser, middleware-only gates,
+  CVE-2025-29927). Use when "audit our auth" or "check middleware protection".
+  RLS → plan-rls-audit.
+license: MIT
+effort: high
+---
+
+<!-- TECHNIQUE: effort routing. A security audit is judgment work, so the
+frontmatter declares `effort: high`; the model default is medium. Claude Code
+honors the key, Cursor ignores it. Mechanical fixed-sequence skills declare
+`effort: low`. Read-only does not mean low: audits are read-only and high. -->
+
+# audit-auth-flows — Middleware is edge routing, not a security boundary
+
+## Degree of freedom: MIXED — declared per phase
+
+<!-- TECHNIQUE: T1 degree-of-freedom declaration (Anthropic official). The
+skill states its register up front and per phase, so the agent knows where
+to reason freely and where to follow exact steps. It pairs with the `effort:`
+key above: the register line says where to reason freely; the effort key says
+how deep. This header is the single most important addition. -->
+
+- Phases 0–4 (discovery, judgment): **[HIGH freedom]** — reason about what
+  you find; checklists prompt investigation, they are not tick-scripts.
+- Phase 5 (live probes) and the getSession grep: **[LOW freedom — run
+  exactly]** — a skipped probe is an unproven claim, not a saved step.
+
+Read-only. Map the auth surface and prove, route by route, that identity is
+verified where it matters. Then stop. Hand fixes to a follow-up session.
+
+**2026 consensus (official, post CVE-2025-29927):** Next.js middleware
+runs before cache and routing. Vercel: *"We do not recommend Middleware
+to be the sole method of protecting routes in your application."* An
+audit that only reads `middleware.ts` and declares the app safe has
+missed the point. Defense in depth: edge + route handler / server action
++ data layer. Each layer covers a different part of the request path.
+
+## How to reason in this audit
+
+<!-- TECHNIQUE: T2 named-stage chain (not "think step by step"). Thinking is
+always on for the model and `effort` in frontmatter sets its depth, so this
+is not a reasoning script: it is the record shape every finding carries, so
+no finding can be written without its evidence, its meaning, its bucket, and
+a justified severity. Placed once, referenced by each phase. -->
+
+Every finding is recorded in this shape, in this order:
+
+1. **Observe** — what does the code/probe actually show? (quote the line or the response)
+2. **Interpret** — what does that mean for who can reach what? (don't assume intent)
+3. **Classify** — real exposure / defense-in-depth-gap / correct-as-is / needs-a-probe
+4. **Severity** — by blast radius: unauth data access & auth bypass = critical;
+   everything else justified against what an attacker actually gains.
+
+If you cannot complete Interpret from static code, it is a **needs-a-probe**
+item for Phase 5, not a conclusion.
+
+## Worked example
+
+<!-- TECHNIQUE: T3 one worked example, shown in the chain's order AND the
+finding-row shape. Examples pin format — the model matches their length and
+structure — so label it illustrative, keep it realistic, and add a second only
+where it varies the judgment (a different Classify outcome), not a second
+tutorial. The output-format section carries the rest. -->
+
+> **Observe:** `middleware.ts` matcher is `['/dashboard/:path*']`. The route
+> `/api/orders/[id]` has no check in the handler.
+> **Interpret:** API routes are not under the matcher, so middleware never
+> runs on them; the order endpoint is reachable without auth. Layout-level
+> checks don't cover direct API calls.
+> **Classify:** real exposure (not merely a defense-in-depth gap — data is
+> actually reachable).
+> **Severity:** critical — unauthenticated data access.
+> **Finding row:** `/api/orders/[id]` | edge+route | critical | matcher
+> excludes /api; handler has no `getUser()` check | probe P5-a confirmed
+> 200 while logged out.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **audit-auth-flows** (this) | Session lifecycle, route×gate matrix, OAuth, provider traps |
+| `audit-security` | OWASP checklist (injection, headers, deps) — may fix inline |
+| `plan-security-audit` | Plan-only hardening burndown |
+| `plan-rls-audit` | Data-layer who-can-read-which-rows |
+| `plan-secrets-audit` | Where `service_role` / keys live |
+| `plan-privacy-compliance` | Consent / policy vs collection — not session gates |
+| `backend-patterns` | Building the middleware / guard fixes after this audit |
+| `test-exploratory` | Live guest vs logged-in probe (runtime complement to this static matrix) |
+
+---
+
+## Phase 0 — Detect the auth stack  [HIGH freedom]
+
+Identify: provider (Supabase Auth / NextAuth / Clerk / Auth0 / custom),
+framework protection (Next.js middleware + `matcher`, route guards,
+server-action checks), session transport (cookie vs `localStorage` vs
+`Authorization` header), token model (JWT vs server session). Enumerate
+pages, API routes, server actions, edge functions, admin areas. Record
+the pinned framework version — auth CVEs are version-gated.
+
+---
+
+## Phase 1 — Route × gate coverage matrix  [HIGH freedom — the centerpiece]
+
+Every protected route / action, one row. Apply the reasoning chain per row.
+
+| route/action | intended access | gate that protects it | verified server-side? | data-layer backstop? |
+
+Hunt the gaps this exposes:
+
+- **Matcher holes** — `config.matcher` misses a protected path. API
+  routes and server actions often bypass page middleware — each needs
+  its own check.
+- **Layout-only protection** — a layout/wrapper is a client-side
+  illusion. It does not gate data fetches or direct API/action calls.
+- **Middleware-as-only-gate** — the CVE-2025-29927 class. Any route
+  where middleware is the *sole* authorization layer is a finding
+  **regardless of framework version or host**. Patching the CVE is not
+  defense in depth.
+- **Server action exposure** — Next.js server actions are POST
+  endpoints callable directly. Each mutating action must check identity
+  itself.
+- **Unlisted routes** — grep the router; do not trust the matcher list.
+
+---
+
+## Phase 2 — Provider and framework traps  [HIGH freedom, except the grep = LOW]
+
+**Supabase (check first on this stack):**
+
+- **[LOW freedom — run exactly]** `grep -rn "getSession(" <server-code-paths>`.
+  <!-- TECHNIQUE: T1 applied to the fragile bit. Promoted from advisory
+  prose to an explicit "run exactly" step so the agent cannot reason past
+  the grep. -->
+  Treat every server-side hit as a finding until proven client-side-only.
+  Official JS docs: cookie/storage values *may not be authentic*;
+  `getSession()` is strongly advised against for authorization.
+  `getUser()` performs a network request to the Auth server and *can* be
+  used to base authorization rules. Newer SSR guides also use
+  `getClaims()` to *refresh* cookies — that is not a substitute for
+  verifying identity at the handler.
+- Service-role key on any client-exposed path → `plan-secrets-audit`.
+  RLS assumed but not enforcing → `plan-rls-audit` (data-layer
+  backstop; this skill is the app layer above it).
+- `autoRefreshToken` disabled without manual refresh; JWT expiry
+  absurdly short (<300s) hammering refresh.
+
+**Next.js CVE-2025-29927** (GHSA-f82v-jwr5-mffw, critical): bypass
+authorization if the check occurs only in middleware, via the internal
+`x-middleware-subrequest` header. **Patched:** 12.3.5 / 13.5.9 /
+14.2.25 / 15.2.3. **Impacted:** self-hosted `next start` and
+`output: 'standalone'`. Vercel-hosted apps were incidentally
+protected; Netlify and Cloudflare Workers were not affected. Workaround
+if unpatched: drop `x-middleware-subrequest` before it hits Next.
+If below the fix → P0 *and* a defense-in-depth finding. Also sweep
+later Next.js auth CVEs (do not treat 29927 as the only one).
+
+**General rule:** any "the framework enforces auth at the edge"
+assumption is a finding, whatever the framework.
+
+**NextAuth / Clerk / Auth0** — session strategy (JWT vs database),
+callback / redirect validation, and whether `auth()` / session checks
+actually run server-side per protected operation.
+
+---
+
+## Phase 3 — Session lifecycle  [HIGH freedom]
+
+**Cookies** — `HttpOnly`, `Secure`, `SameSite` (Lax min, Strict for
+sensitive); scoped path/domain; not readable by JS. Token in
+`localStorage` is XSS-exfiltratable — flag it; CSRF-vs-XSS must be a
+deliberate choice.
+
+**Logout that actually logs out** — a stateless JWT stays valid until
+expiry if logout only clears the client. Confirm server-side
+invalidation (Supabase `signOut` revokes the refresh token). Probe it
+(Phase 5). Official sessions FAQ: access tokens can still be presented
+after sign-out unless the app also checks revocation / uses
+`getUser()`.
+
+**Rotation & timeouts** — rotate on privilege change (login, role
+elevation) to kill fixation; idle timeout and absolute-max lifetime
+both present. Current norm: short access tokens, longer **rotated**
+refresh tokens with reuse detection, capped absolute session.
+
+**Refresh-token rotation + reuse detection** — official Supabase
+sessions docs: a refresh token is single-use, with two exceptions
+(default **10s reuse interval** — do not widen; parent-token retry for
+lost responses). Outside those exceptions the **whole session family
+is revoked**. Disabling that in Advanced Settings is "generally not
+recommended" — flag if widened or disabled.
+
+---
+
+## Phase 4 — Credentials, OAuth, authorization  [HIGH freedom]
+
+**OAuth / OIDC** — `state` (CSRF on the callback), PKCE for public
+clients, redirect-URI allowlist exact-match, provider `email_verified`
+checked before trust, account-linking collisions handled.
+
+**Credential flows** — reset tokens single-use + expiring + not leaked
+in URL/referrer; **user enumeration** via differing error text or
+timing on login/reset/signup; rate limiting on auth endpoints
+specifically; MFA state cannot be skipped mid-flow.
+
+**Authorization above the data layer** — not just "is logged in" but
+"is allowed"; IDOR on API params (`/api/orders/:id` scoped to caller?);
+admin routes gated by role server-side. Name which layer each control
+lives in. `plan-rls-audit` owns the data-layer half.
+
+---
+
+## Phase 5 — Live probes  [LOW freedom — run each, in order, non-prod]
+
+<!-- TECHNIQUE: T1 low-freedom exact steps for the fragile part. These are
+not suggestions; each is a labeled probe whose result is evidence. The
+reasoning chain's "needs-a-probe" items resolve here. -->
+
+Force the failures rather than only reading code. Log each as
+`P5-x | expected | actual | evidence`:
+
+- **P5-a** Hit each protected route / API / action **unauthenticated** →
+  expect deny (not a redirect that still returns data).
+- **P5-b** Replay a **logged-out** session token → expect reject.
+- **P5-c** Tamper the session cookie / swap another user's identifier →
+  reject.
+- **P5-d** IDOR: as user A, request user B's object by id → deny.
+- **P5-e** If Next.js is version-vulnerable or self-hosted: send
+  `x-middleware-subrequest` and confirm WAF/edge *and* a route-handler
+  check still stop it.
+- **P5-f** User-enumeration: compare wrong-password vs nonexistent-user
+  (text + timing).
+
+Do not run these against production. Do not write exploit PoCs into
+the repo.
+
+---
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+<!-- TECHNIQUE: T4 evidence check before output. Opus 5.5 self-verifies
+without being told, so this is not a "double-check your work" step — every
+item names a specific piece of evidence (quote, probe, layer) a finding must
+carry, and findings without it are dropped or downgraded. Add items that
+name evidence; never generic "verify" lines. -->
+
+Challenge every finding against this rubric; drop or downgrade any that fail:
+
+1. **Evidenced, not assumed** — quoted line or probe result? If it rests on
+   "the code probably…", mark unconfirmed or run the probe.
+2. **Reproducible** — did the probe succeed twice, or once? Flaky ≠ finding.
+3. **Severity justified** — "critical" requires actual unauth access or
+   bypass, not theoretical risk.
+4. **Right layer** — app-layer (yours) or data-layer (→ `plan-rls-audit`)?
+5. **No false safety** — did you confirm a gate *works*, or only that it
+   *exists*? A check a probe bypassed is critical, not a pass.
+
+---
+
+## Definition of Done
+
+- [ ] Auth stack + framework version recorded
+- [ ] Degree-of-freedom respected: Phase 5 probes and the getSession grep
+      run exactly, in order
+- [ ] Route×gate matrix complete; every row reasoned
+      Observe→Interpret→Classify→Severity
+- [ ] Matcher holes, layout-only, middleware-as-sole-gate, unprotected
+      server actions surfaced
+- [ ] `getSession()`-for-authz grepped; `getUser()` confirmed on every
+      server gate
+- [ ] CVE-2025-29927 (and later auth CVEs) checked against the pinned version
+- [ ] Cookie flags, localStorage exposure, CSRF pairing assessed
+- [ ] Server-side logout invalidation confirmed by probe; rotation +
+      idle/absolute timeouts present
+- [ ] Refresh reuse interval not widened; family revocation not disabled
+- [ ] OAuth state / PKCE / redirect-allowlist / email_verified checked
+- [ ] User-enumeration, reset tokens, auth-endpoint rate limits, MFA-skip
+      checked
+- [ ] App-layer authorization (roles, IDOR, admin) split from the RLS half
+- [ ] Live probes run non-prod; each logged pass/fail
+- [ ] Self-critique rubric applied; unevidenced/flaky findings dropped or
+      downgraded
+- [ ] Read-only — findings presented, not patched
+
+## Output format
+
+1. **Route × gate matrix** — the table, gaps highlighted
+2. **Findings** — issue | layer (edge/route/data) | severity (critical =
+   unauth access / auth bypass) | file:line or probe | fix shape — each
+   finding in the worked-example shape
+3. **Provider-trap list** — exact call to change (`getSession` →
+   `getUser`, etc.)
+4. **Probe log** — P5-x | expected | actual | evidence
+5. **Fix plan** — auth-bypass and getSession-authz first, then session
+   lifecycle, then enumeration/OAuth. Handoffs: `plan-rls-audit`,
+   `plan-secrets-audit`, `plan-security-audit`, `backend-patterns`.
+   Present and stop.
+
+<!-- TECHNIQUE: T5 terminology — this file uses finding (not issue/problem),
+gate (not check/guard) for the auth layer, and probe for live evidence.
+T6 conciseness — neighbor table kept (routing), official CVE/getSession/
+getClaims/10s facts kept (not restated twice). Teaching comments live only
+in this exemplar; strip them from the live SKILL.md. -->

package/skills/enhance-web-conversion/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: enhance-web-conversion
+description: >
+  Conversion pass for landing, pricing, and upgrade paths: positioned hero,
+  one CTA, real proof, anchored tiers, upgrade prompts at value moments. Use
+  when "pricing page", "improve conversion", or "paywall UX". Page build →
+  enhance-web-landing.
+license: MIT
+---
+
+# enhance-web-conversion — Message, offer, proof, prompt
+
+**Degree of freedom: MIXED.** Copy angle, packaging, and proof selection
+`[HIGH freedom]`; the hero five-second check, the dark-pattern ban, and the
+event names `[LOW freedom — run exactly]`.
+
+Apply-now. `enhance-web-landing` makes the page look hand-crafted; this skill
+makes it **say the right thing to the right person and ask once**. It touches
+hero copy, CTA, pricing packaging, social proof, trust signals, and in-app
+upgrade moments — and measures each with an event.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **enhance-web-conversion** (this) | What the page claims, offers, proves, and asks |
+| `enhance-web-landing` | Layout, type, motion, visual system of the page |
+| `enhance-onboarding` | Getting the free user to first value (before any ask) |
+| `audit-payment-system` | Whether checkout, webhooks, and refunds actually work |
+| `audit-monetization-iap` | Mobile store purchases |
+| `plan-gtm` | Chose the model and the ICP this skill writes for |
+| `plan-antislop` | Voice audit when the copy reads generated |
+| `enhance-web-seo` | Titles, meta, schema for the same pages |
+
+Do **not** fire for "make the pricing page prettier" alone → `enhance-web-landing`.
+
+## How to reason
+
+1. **Message** — does the hero state who it is for, what it does, why not the alternative — in five seconds?
+2. **Offer** — does the packaging match the monetization model and make one tier the obvious pick?
+3. **Proof** — is every claim backed by a named person, a number, or a screenshot?
+4. **Prompt** — does the upgrade ask appear where value was just felt, and say what unlocks?
+5. **Measure** — does each of the above fire an event so the change can be judged?
+
+## Worked example
+
+> **Message:** hero reads "145 skills · 57 commands"; the positioning says
+> "refuses done while unchecked work remains". Rewrite: *"Coding agents call it
+> done when it compiles. These playbooks don't."* CTA "Install in 30 seconds".
+> **Offer:** free forever — so the only ask is the install; remove the second CTA.
+> **Proof:** replace "used by developers" with the skills.sh install badge (live
+> number) and one named quote from an issue thread.
+> **Prompt:** none — no paid tier; add a "star if this saved you a rework" line
+> after the first successful run (in-app, not on the landing page).
+> **Measure:** `cta_clicked { location }`, `install_copied`; before/after
+> visit→install unmeasured → measured.
+
+## Self-critique before reporting
+
+- **Five-second pass** — a stranger reading only the hero can say who/what/why-different
+- **One primary CTA per screen** — its verb matches the model ("Start free" / "Start 14-day trial" / "Book a demo")
+- **Every proof is real** — names, logos, numbers, and quotes exist in the repo or were supplied
+- **No dark patterns** — cancel path visible; no fake timers, confirm-shaming, or pre-checked add-ons
+- **Events added** — pricing and upgrade events listed with where they fire
+- **Right owner** — visual system → `enhance-web-landing`; checkout bugs → `audit-payment-system`
+
+---
+
+## Procedure
+
+### 1. Hero and CTA  [LOW freedom — check; HIGH freedom — write]
+
+Five-second check on the current hero: **who** (ICP named or implied), **what**
+(outcome, not feature count), **why not the alternative**, **one CTA** above the
+fold. Rewrite what fails. Sub-headline carries the mechanism; the H1 carries the
+outcome. Model-matched CTA copy:
+
+| Model | Primary CTA | Under it |
+|---|---|---|
+| Freemium / ungated | Start free · Try it now | "No account needed" / "Free forever for …" |
+| Trial, no card | Start 14-day trial | "No credit card required" (lifts visit→signup) |
+| Trial, card | Start trial | Price after trial + cancel-anytime, visible |
+| Open-core / hosted | Deploy on cloud · Self-host | Link to the other path |
+| Sales-assisted | Book a demo | Who it is for (team size / ACV) |
+
+### 2. Pricing page  [HIGH freedom]
+
+- **≤3 self-serve tiers** good-better-best; the recommended middle tier is
+  visually and verbally the default; the higher tier sits on the right as the
+  anchor. An enterprise column shows "from $X" — hiding its price removes the
+  anchor and hurts middle-tier conversion.
+- **Same CTA verb on every column**; "No credit card required" under the
+  button when true.
+- **Annual toggle** — default monthly for self-serve products with a free
+  tier; state the saving as "2 months free", not "save 17%" (norm 15–25%).
+- **Free tier limits explicit** — what runs out (seats, rows, runs), never vague "basic".
+- **Usage / credits** — if the model meters, show the unit, the included
+  amount, and a live estimate; bill shock is the top objection.
+- **Feature table** lists outcomes people search for; hide internals.
+- **FAQ** answers cancel, refund, data export, security — the objections that stall checkout.
+- A dual CTA (free plan **or** 14-day card trial) lifted premium trial starts
+  26% in one 2026 case; offer it only when `plan-gtm` chose both paths.
+- Benchmarks to set expectations (2026, ChartMogul × Kyle Poyar × ProductLed):
+  freemium good 3–5%, trial no-card 4–6%, card-required 25–35%; median 8%.
+  Judge the change by Signup→Paid, not visits. Rows and URLs:
+  `plan-gtm/references/benchmarks-2026.md`.
+
+### 3. Proof and trust  [HIGH freedom]
+
+Order of strength: live numbers (installs, stars, customers) → named quotes with
+role → recognizable logos → screenshots of the real product → security/privacy
+pages. Place the strongest one directly under the hero CTA and again beside the
+pricing CTA. Fabricated or anonymous "Jane D., CEO" quotes are removed, not kept.
+
+### 4. In-app upgrade prompts  [HIGH freedom]
+
+Ask at **value moments**: a limit reached, a premium feature touched, a result
+worth keeping. The prompt names what unlocks, shows price, and completes in one
+step. Dismiss is one click and remembered. Never interrupt the activation path
+(`enhance-onboarding` owns that stretch). For a free tier, a "powered by"
+badge on shared output is the cheapest loop (0.5–3% conversion, near-total
+exposure); a referral credit follows once activation is measured.
+
+### 5. Events  [LOW freedom — names]
+
+```
+cta_clicked { location, label }
+pricing_viewed · plan_selected { plan, interval }
+checkout_started · checkout_completed { plan, interval }
+upgrade_prompt_shown { trigger } · upgrade_prompt_clicked { trigger }
+```
+
+Reconcile with `audit-analytics`; consent-gated; no PII.
+
+### 6. Verify
+
+- Five-second read of the new hero by someone outside the project (or a fresh model with only the screenshot): what is it, for whom, what outcome — then the doppelganger check with the logo removed (could this be a competitor's page?)
+- Playwright: pricing → checkout start path; cancel/downgrade path still reachable
+- Events observed in the debug view
+- Report: before/after copy, packaging diff, proof sources, events, files
+
+## Guardrails
+
+- **No dark patterns** — no fake countdowns or scarcity, hidden cancel, confirm-shaming, pre-checked upsells, or bait pricing.
+- **Claims need evidence** — a number or a name; otherwise cut the claim.
+- **Model is not yours to change** — packaging follows the `plan-gtm` decision.
+- **Voice** — if it reads like every other SaaS page, hand the copy to `plan-antislop`.
+
+## Chains with
+
+- **`plan-gtm`** → positioning statement and monetization verdict this skill implements.
+- **`enhance-web-landing`** → visual pass on the same pages.
+- **`enhance-web-seo`** → title/meta/schema for landing and pricing.
+- **`audit-payment-system`** → before turning on a card-required trial.
+- **`test-playwright`** → lock checkout and cancel paths.