@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/docs-comparison-pages/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: docs-comparison-pages
+description: >
+  Write honest "X vs Y", "alternatives to X", and "migrate from X" pages from
+  verified facts, each unique and dated for review. Use when "comparison
+  page", "vs page", "alternatives to", "competitor page", or "migration guide
+  from".
+license: MIT
+effort: high
+---
+
+# docs-comparison-pages — The pages buyers read last
+
+**Degree of freedom: MIXED.** Which competitors and angles `[HIGH freedom]`;
+fact verification, per-page uniqueness, and the freshness contract
+`[LOW freedom — run exactly]`.
+
+Apply-now. In one 162-page programmatic test, comparison pages were 28% of
+the pages and took 78% of the clicks and six of seven leads. They also sit
+squarely inside Google's scaled-content-abuse policy when generated in bulk.
+This skill writes a few pages that survive both a buyer and a reviewer.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **docs-comparison-pages** (this) | Comparison / alternatives / migration page content and its freshness contract |
+| `enhance-web-seo` | Title, meta, canonical, JSON-LD, sitemap for those pages |
+| `plan-aeo-readiness` | Whether answer engines can read and cite them |
+| `docs-writer` | Product docs and the migration steps' technical accuracy |
+| `plan-antislop` | Voice audit when a page reads generated |
+| `docs-launch-kit` | Launch posts — not evergreen pages |
+
+Do **not** fire for "write a blog post about our launch" → `docs-launch-kit`.
+
+## How to reason
+
+1. **Query** — which bottom-funnel question does a real buyer type, and which alternative do they name?
+2. **Facts** — every claim about the competitor comes from their current public page, dated
+3. **Angle** — where is the product honestly better, honestly worse, and for whom
+4. **Unique** — what on this page could not be pasted onto the next one
+5. **Freshness** — who re-verifies competitor prices and features, and when
+
+## Worked example
+
+> **Query:** "mushi-mushi vs Sentry user feedback" — buyers name Sentry.
+> **Facts:** Sentry pricing page fetched 2026-09-17; free tier limits quoted with the date; our limits from `pricing.ts`.
+> **Angle:** better for in-app screenshot + reporter chat; worse for backend error grouping; for teams shipping web apps without a support desk.
+> **Unique:** a side-by-side of one real bug report in both tools; the migration snippet from their SDK init to ours.
+> **Freshness:** `lastVerified: 2026-09-17`, review quarterly; page shows "prices checked on …".
+
+## Self-critique before reporting
+
+- **Dated facts** — every competitor claim carries the fetch date and URL in the source block
+- **Both directions** — the page names at least one thing the alternative does better
+- **No template stamping** — two pages share structure, never paragraphs
+- **Freshness contract** — `lastVerified` in frontmatter and a visible "checked on" line; review cadence recorded
+- **Right owner** — meta/schema → `enhance-web-seo`; voice → `plan-antislop`
+
+---
+
+## Procedure
+
+### 1. Choose pages  [HIGH freedom]
+
+From `plan-gtm`'s alternatives list (or the founder), pick ≤5 pages to start:
+`<product> vs <alt>`, `<alt> alternatives`, `migrate from <alt>`. One page per
+real query; skip alternatives nobody compares against.
+
+### 2. Verify facts  [LOW freedom — run exactly]
+
+For each alternative: fetch its pricing page, feature/limits page, and docs this session (Firecrawl or WebFetch) — recognizing the product's name is not knowing its current prices or limits, so fetch even for products you know well. Record `URL · fetched date · quote` in a source
+block at the bottom of the page. Product-side facts come from the repo
+(`pricing`, limits, feature flags) with file references. Anything
+unverifiable is omitted, not softened.
+
+### 3. Write  [HIGH freedom — words; LOW freedom — shape]
+
+Shape per page (order may vary, sections may not be skipped):
+
+1. **Verdict in two sentences** — who should pick which.
+2. **Comparison table** — 6–10 rows buyers care about; ✅/⚠️/❌ plus one clause each; prices with the checked-on date.
+3. **Where the alternative wins** — honest, specific.
+4. **Where this product wins** — with a screenshot or a real artifact.
+5. **Migration** (migrate-from pages) — steps, code, data export/import, what does not carry over.
+6. **FAQ** — 3–5 real objections (→ FAQ JSON-LD via `enhance-web-seo`).
+7. **Sources** — the dated block from step 2.
+
+Voice: first person plural, plain claims, no superlatives, no mannered prose (throat-clearing openers, stacked hedges, triplets for rhythm, a closing line that restates the paragraph). If a paragraph
+could sit on another vendor's page, rewrite it.
+
+### 4. Freshness contract  [LOW freedom — run exactly]
+
+Frontmatter `lastVerified: YYYY-MM-DD`, `reviewEvery: 90d`; visible line
+"Prices and limits checked on …". Add a repo reminder (issue, cron, or
+`docs/launch` calendar row) for the next review. A page past its review date
+gets re-verified or unpublished — never left stale.
+
+### 5. Hand off
+
+`enhance-web-seo` for title/meta/canonical/JSON-LD and sitemap;
+`plan-aeo-readiness` if answer-engine citation is a goal; `test-playwright`
+for the migration snippet where it is runnable.
+
+## Guardrails
+
+- **No bulk generation.** ≤5 pages per pass, each hand-checked; templated batches are the spam policy's target.
+- **No trademark misuse.** Competitor names as plain text; their logos only with permission.
+- **No invented weaknesses.** If you cannot cite it, it is not on the page.
+- **Keep the loser's case.** A page with no "where they win" section is not published.
+
+## Chains with
+
+- **`plan-gtm`** → alternatives list and channel plan.
+- **`enhance-web-seo`** → meta, schema, sitemap.
+- **`plan-aeo-readiness`** → citation readiness.
+- **`docs-launch-kit`** → announce a new comparison page in the next kit.

package/skills/docs-domain-modeling/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: docs-domain-modeling
+description: >
+  Build a project's domain model: a CONTEXT.md glossary and ubiquitous
+  language. Use when pinning down terminology, or the agent "uses the wrong
+  words". Decision records (INDEX.md, rejected alternatives) → docs-adr.
+license: MIT
+---
+
+# Domain Modeling
+
+**Degree of freedom: MIXED.** Which term is canonical `[HIGH freedom]`;
+CONTEXT.md shape, lazy create, and the three ADR gates
+`[LOW freedom — run exactly]`.
+
+> A shared language between user, agent, and codebase pays off every session:
+> consistent naming, fewer tokens spent describing concepts, and a codebase the
+> agent can navigate by vocabulary. Adapted from
+> [mattpocock/skills](https://github.com/mattpocock/skills) (MIT).
+
+This is the *active* discipline — challenging terms, inventing edge-case
+scenarios, and writing the glossary and decisions down the moment they
+crystallize. Merely *reading* `CONTEXT.md` for vocabulary is a one-line habit any
+skill can do; this skill is for **changing** the model, not consuming it.
+
+## How to reason
+
+1. **Observe** — the word just used, and what CONTEXT.md already pins
+2. **Interpret** — conflict, overload, or a genuine new concept
+3. **Classify** — challenge / sharpen / write the glossary entry / offer an ADR
+4. **Capture** — write the moment it crystallizes; do not batch
+
+## Worked example
+
+> **Observe:** user says "account" for both the billing Customer and the login User; CONTEXT.md is empty; `accounts` and `auth.users` both exist.
+> **Interpret:** one word, two entities — the next session will keep writing the wrong one.
+> **Classify:** sharpen now — **Customer** (billing party) vs **User** (login). Not an ADR: naming is still reversible.
+> **Write immediately:** `**Customer**: the billing party. _Avoid_: account, user`
+
+## Self-critique before reporting
+
+- **Domain language** — definitions are not table or column names
+- **Avoid filled** — rejected synonyms are listed
+- **Inline, not batched** — each resolved term is in CONTEXT.md this turn
+- **Right owner** — INDEX.md / rejected alternatives → `docs-adr`; interview-the-user → `workflow-grilling`
+
+## File structure  [LOW freedom — this shape]
+
+```
+/
+├── CONTEXT.md            ← the glossary (create on first resolved term)
+├── docs/adr/             ← architectural decision records
+│   └── 0001-<dash-case-title>.md
+└── src/
+```
+
+Create files lazily — only when there is something to write. `CONTEXT.md` is a
+glossary and nothing else: no implementation details, no spec content, no
+scratch notes.
+
+### CONTEXT.md entry format
+
+```markdown
+**<Canonical term>**:
+<One- or two-line definition in domain language, not implementation language.>
+_Avoid_: <rejected synonyms, comma-separated>
+```
+
+## During the session  [HIGH freedom]
+
+- **Challenge against the glossary.** When the user uses a term that conflicts
+  with `CONTEXT.md`, call it out immediately: "Your glossary defines
+  'cancellation' as X, but you seem to mean Y — which is it?"
+- **Sharpen fuzzy language.** When a term is vague or overloaded, propose a
+  precise canonical term: "You're saying 'account' — do you mean the Customer or
+  the User?"
+- **Stress-test with concrete scenarios.** Invent edge-case scenarios that force
+  precision about the boundaries between concepts.
+- **Cross-reference with code.** When the user states how something works, check
+  whether the code agrees, and surface contradictions.
+- **Update `CONTEXT.md` inline.** Capture each resolved term the moment it is
+  resolved — don't batch.
+
+## ADRs — offer sparingly  [LOW freedom — all three gates]
+
+Only offer to create an ADR when **all three** hold:
+
+1. **Hard to reverse** — changing your mind later costs something real.
+2. **Surprising without context** — a future reader will ask "why this way?"
+3. **A real trade-off** — genuine alternatives existed and one was picked for
+   specific reasons.
+
+ADR body: Status, Context (the forces), Decision (what and why), Consequences
+(what becomes easier/harder). Number sequentially in `docs/adr/`.
+
+**Related:** `workflow-grilling` (use both in one session to interview *and* capture the
+language), `design-prd`, `docs-coauthor`.

package/skills/docs-launch-kit/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: docs-launch-kit
+description: >
+  Versioned launch kit from the repo's real features: Show HN, Product Hunt,
+  Reddit/X/LinkedIn posts, release notes, a calendar with UTM links. Use when
+  "launch post", "Show HN", "Product Hunt listing", "announce this release",
+  or "launch copy".
+license: MIT
+---
+
+# docs-launch-kit — Launch copy that survives the comments
+
+**Degree of freedom: MIXED.** Angle and voice `[HIGH freedom]`; facts from
+the repo, per-channel format rules, and the no-solicitation ban
+`[LOW freedom — run exactly]`.
+
+Apply-now. Produces `docs/launch/<version>.md` (or the path the repo already
+uses) with one angle, per-channel copy, UTM links, and a calendar. A launch is
+a **cadence** — every meaningful release gets a kit — so the file is versioned,
+not overwritten.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **docs-launch-kit** (this) | Announcement copy per channel + calendar + UTMs |
+| `enhance-readme` | README hero, screenshots, badges |
+| `docs-writer` | Reference docs, changelog entries, long-form articles |
+| `plan-antislop` | Voice audit when the copy reads generated |
+| `enhance-web-seo` | Titles/meta for the pages the posts link to |
+| `plan-gtm` | Which channels and which ICP — this skill writes for that decision |
+| `deploy-npm` / `workflow-ship-and-observe` | The release itself |
+
+Do **not** fire for "write the changelog" alone → `docs-writer`.
+
+## How to reason
+
+1. **Angle** — one problem the ICP recognizes, stated before the product name
+2. **Evidence** — every claim maps to a file, a changelog line, or a number that can be checked
+3. **Format** — each channel gets its native shape; nothing is cross-posted verbatim
+4. **Calendar** — sequence and timing; who answers comments and for how long
+5. **Measure** — UTM per channel; success is signups and activation, not points
+
+## Worked example
+
+> **Angle:** "Coding agents call it done when it compiles" — not "145 skills".
+> **Evidence:** `complete-everything` state file + `completion-judge` agent exist
+> in `skills/`; 3.6k npm downloads from `npm view`; no star count claimed.
+> **Format:** Show HN title states the mechanism; first comment explains why it
+> was built and what it does not do. PH tagline ≤60 chars, three gallery shots
+> from `docs/screenshots/`. Reddit r/cursor post leads with the failure story.
+> **Calendar:** HN Tuesday 13:00 UTC; PH the following week; Reddit on release
+> day; reply window 2 h for HN, all day for PH.
+> **Measure:** `?utm_source=hn&utm_medium=post&utm_campaign=v1.35`; report
+> signups per channel after 7 days.
+
+## Self-critique before reporting
+
+- **Angle first** — every post opens with the problem, not the product or a count
+- **Checked facts** — each number and feature in the copy was verified this session
+- **Native format** — HN copy has no marketing adjectives; PH copy fits its fields; Reddit follows the subreddit rules quoted in the file
+- **No solicitation** — no "upvote us" links, vote rings, or DMs asking for votes
+- **Disclosure** — the maker is identified as the maker on every channel
+- **Right owner** — README visuals → `enhance-readme`; changelog → `docs-writer`
+
+---
+
+## Procedure
+
+### 1. Gather facts  [LOW freedom — run exactly]
+
+Read `CHANGELOG.md` (or the release diff), README hero, `package.json`
+version, screenshots directory, and any live numbers (`npm view`, store
+listing, analytics). Build a **claims table**: `Claim | Source | Verified`.
+Copy may use only verified rows.
+
+### 2. Pick the angle  [HIGH freedom]
+
+One sentence the ICP would say about their own problem. Test: does it still
+work with the product name removed? Lead with what **changed** for the reader,
+never with counts, "excited to announce", or the tech stack.
+
+### 3. Write per channel  [LOW freedom — formats; HIGH freedom — words]
+
+| Channel | Shape | Rules that matter |
+|---|---|---|
+| **Show HN** | `Show HN: <what it does, plainly>` + first comment: why built, how it works, trade-offs, what it does not do, one ask | Official rules: a runnable thing, no signup wall or waitlist, human-written (AI-written posts are removed), never solicit votes; sober tone, no adjectives; answer every comment for 2 h; only ~11% of Show HN posts clear 10 points — the thread is the asset even when the front page misses |
+| **Product Hunt** | tagline ≤60 chars; description; 3–5 gallery images or a 30-s demo; maker first comment; hunter or self-hunt | Featured rate ~10%; 1–2% visit→signup for B2B; credibility and feedback, not acquisition; launch after real users exist; relaunch per major version |
+| **Reddit** | subreddit-specific post: story → what it does → link in comments if rules require | Quote the subreddit rules in the kit; value-first; one subreddit per day |
+| **X / Bluesky / LinkedIn** | hook line → 15-s demo or screenshot → link; LinkedIn in first person, longer | External links are throttled on X — the demo clip travels, the link rides in a reply; one thread, not five; reply to every quote |
+| **dev.to / Hashnode / blog** | problem → approach → code → what you would change → link | Canonical URL to your domain; this is the SEO asset; one honest piece beats a batch of generated ones (Google scaled-content policy) |
+| **Release notes as announcement** | Changelog section rewritten for users: what you can do now | Ships with the tag; link from every other post |
+| **Newsletter / Discord** | short, personal, one link | Existing users first — they retell it |
+
+### 4. Calendar  [HIGH freedom]
+
+Sequence: existing users → Show HN (Tue–Thu, 12–17 UTC) → community posts →
+Product Hunt a week later when social proof exists → article the following
+week. Name who watches comments and for how long. Put the next release's
+kit date at the bottom.
+
+### 5. Links and measurement  [LOW freedom — run exactly]
+
+`?utm_source=<channel>&utm_medium=post&utm_campaign=<version>` on every
+link; one row per channel in the kit's **Results** table: visits, signups,
+activated, notes — filled after 7 days. Channel numbers to judge against
+(Show HN front page 5–30k visits / 50–400 signups; Product Hunt 1–2% B2B
+signup) live in `plan-gtm/references/benchmarks-2026.md`.
+
+### 6. Output
+
+```markdown
+# Launch kit — <product> <version> — <date>
+## Angle
+## Claims table
+## Show HN
+## Product Hunt
+## Reddit — r/<name> (rules: …)
+## X / Bluesky / LinkedIn
+## Article outline
+## Release notes (user-facing)
+## Calendar
+## Results (fill after 7 days)
+```
+
+## Guardrails
+
+- **No vote solicitation.** No upvote asks, rings, or DMs — HN and PH both penalize it.
+- **No fabricated proof.** Testimonials, numbers, and logos come from the claims table.
+- **Disclose.** The maker posts as the maker.
+- **No cross-post spam.** One native post per channel; respect each community's rules.
+- **Voice check.** If a paragraph could be any product's launch, or reads as mannered prose (throat-clearing opener, stacked hedges, "excited to announce", triplets for rhythm), rewrite or send to `plan-antislop`.
+
+## Chains with
+
+- **`plan-gtm`** → channel plan and ICP this kit writes for.
+- **`enhance-readme`** → README hero and screenshots the posts link to.
+- **`enhance-web-seo`** → the article and landing page it links.
+- **`iterate-post-launch`** → reads the Results table one week later.