From 1af0be5b01ea2a52c24dbf1e2ec8b1d164ecfb1b Mon Sep 17 00:00:00 2001 From: Harlan Wilton Date: Tue, 6 Oct 2026 02:47:50 +1100 Subject: [PATCH 1/4] feat(trending): give Skills a lasting trending award A Skill that trends has no record of it once it leaves the board. Record the best rank each evidenced row reaches per week and month, show it beside the Skill heading, and let the README badge carry it. --- GLOSSARY.md | 9 + VISION.md | 2 +- app/components/BadgeEmbedControl.vue | 55 ++++- docs/adr/0010-trending-awards.md | 41 ++++ docs/arch/cron.md | 3 +- .../registry/app/components/SkillDetail.vue | 34 ++- .../server/api/skills/[...slug].get.ts | 7 +- .../server/tasks/record-trending-awards.ts | 51 ++++ .../registry/server/utils/trending-awards.ts | 126 ++++++++++ migrations/0139_skill_trending_awards.sql | 21 ++ server/routes/b/[...slug].get.ts | 14 +- server/utils/skill-badge.ts | 63 ++++- shared/schedule-policy.ts | 1 + shared/skill-badge.ts | 28 +++ shared/trending-award.ts | 98 ++++++++ test/unit/badge-embed-control.test.ts | 21 +- test/unit/trending-awards.test.ts | 223 ++++++++++++++++++ 17 files changed, 775 insertions(+), 22 deletions(-) create mode 100644 docs/adr/0010-trending-awards.md create mode 100644 layers/registry/server/tasks/record-trending-awards.ts create mode 100644 layers/registry/server/utils/trending-awards.ts create mode 100644 migrations/0139_skill_trending_awards.sql create mode 100644 shared/trending-award.ts create mode 100644 test/unit/trending-awards.test.ts diff --git a/GLOSSARY.md b/GLOSSARY.md index 4220c5df..c01cbd5c 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -24,6 +24,7 @@ Shared terms match the skilld CLI glossary (`skilld-dev/skilld/GLOSSARY.md`). Th | track | `/skills/`, `layers/registry` | track 1—N Skill | "track" | | comparison | `/compare/`, `layers/marketing` | comparison N—N Skill | "comparison" | | trending | `/skills/trending`, ADR-0004 | Repository 1—N social mention | "trending" | +| trending award | `skill_trending_awards`, ADR-0010 | Skill 1—N trending award | "#3 trending" | | registry | skilld.dev | one | "skilld" | | skilld token | `cli_tokens`, `layers/identity` | Author 1—N token | "skilld token" | | provenance | Skill detail, cards | Skill 1—1 author and source link | "written by", "source" | @@ -153,6 +154,14 @@ Collisions **Never:** popular, hot, top, leaderboard. +### trending award + +**Is:** the best rank a Skill reached on the `week` or `month` trending board in one calendar period (ADR-0010). It stays after the Skill leaves the board. Only a row with a post or a star surge earns one. + +**Format:** `#3 trending · Sep 2026` on a chip or a README badge. `#3 trending, week of 29 Sep 2026` in full. + +**Never:** trophy, medal, achievement, honor, top pick. + ### registry **Is:** skilld.dev, the curated index of Skills and the discovery MCP server. diff --git a/VISION.md b/VISION.md index 7ad1c741..059b57c6 100644 --- a/VISION.md +++ b/VISION.md @@ -156,7 +156,7 @@ The interface recedes; the content speaks. Warm stone, rare rose, mono chrome, b 1. **skilld-maintained Skills stay separate from registry provenance.** The skilld project may publish visible skilld-maintained Skills for generation, review, search, and install guidance. They name the project as author and remain readable source assets. Generated output never enters the registry as platform-authored maintainer content. Registry Skills retain their Repository owner and exact GitHub provenance. Machine-generated search metadata stays labeled and stays metadata. 2. **We are not AI-powered.** The product category is a curated registry. "AI" never modifies skilld itself in copy, positioning, or feature naming. 3. **No pay-to-play, ever.** No sponsored listings, promoted skills, paid placement, or ads. This is the money posture made permanent: curation that can be bought is not curation. -4. **Popularity is never the quality signal.** Unverifiable third-party counts (installs scraped from skills.sh) never order a surface, never feed trust tiers, and never appear as our numbers; we cannot vouch for a figure we cannot source. GitHub stars are the one sanctioned popularity signal: verifiable at the canonical source, synced for free, honest to display. Stars may order browse surfaces (catalog sort, the human-reviewed leaderboard) and may feed trust as a supporting input (a well-starred repository has earned community evidence), but stars alone never grant the top trust tier: admission and the highest trust signals stay human judgments, the homepage's organizing principle stays curation and freshness, and no star count ever substitutes for review. **Likes carve-out (ADR-0003, 2026-08-10):** Skill likes are first-party (a row we wrote, keyed to a GitHub-authenticated user, so we can state exactly what the number counts) and Skill-grained (stars measure a repository and lend the same count to all twenty Skills inside it). Like counts may be displayed and may back an opt-in `?sort=likes`. They never feed trust, never affect admission, never become a default order, and never order a trending surface: a board ranked by our own users' taste is a mirror. The carve-out covers display and that one sort key; every other clause above holds unchanged. **Trending carve-out (ADR-0004, 2026-08-19):** `/skills/trending` and the weekly email are ordered by social mentions we record ourselves from the public X and Bluesky APIs, and by star surges on repositories holding exactly one Skill. Both pass the test that admitted stars and rejected installs: we can state what the number counts, and a reader can check it, because every socially attributed row ships the post that named the Skill with its author and link. Each row states which route named it; a heading may never claim people named something when a star count did. Neither signal feeds trust or admission, and installs stay barred. +4. **Popularity is never the quality signal.** Unverifiable third-party counts (installs scraped from skills.sh) never order a surface, never feed trust tiers, and never appear as our numbers; we cannot vouch for a figure we cannot source. GitHub stars are the one sanctioned popularity signal: verifiable at the canonical source, synced for free, honest to display. Stars may order browse surfaces (catalog sort, the human-reviewed leaderboard) and may feed trust as a supporting input (a well-starred repository has earned community evidence), but stars alone never grant the top trust tier: admission and the highest trust signals stay human judgments, the homepage's organizing principle stays curation and freshness, and no star count ever substitutes for review. **Likes carve-out (ADR-0003, 2026-08-10):** Skill likes are first-party (a row we wrote, keyed to a GitHub-authenticated user, so we can state exactly what the number counts) and Skill-grained (stars measure a repository and lend the same count to all twenty Skills inside it). Like counts may be displayed and may back an opt-in `?sort=likes`. They never feed trust, never affect admission, never become a default order, and never order a trending surface: a board ranked by our own users' taste is a mirror. The carve-out covers display and that one sort key; every other clause above holds unchanged. **Trending carve-out (ADR-0004, 2026-08-19):** `/skills/trending` and the weekly email are ordered by social mentions we record ourselves from the public X and Bluesky APIs, and by star surges on repositories holding exactly one Skill. Both pass the test that admitted stars and rejected installs: we can state what the number counts, and a reader can check it, because every socially attributed row ships the post that named the Skill with its author and link. Each row states which route named it; a heading may never claim people named something when a star count did. Neither signal feeds trust or admission, and installs stay barred. **Awards carve-out (ADR-0010, 2026-10-06):** a trending award keeps the best rank an evidenced row reached on the week or month board, dated to its period, on the Skill page and on an opt-in README badge. It repeats a claim the board already made with its evidence, so no one can buy or farm it. Star filler and the all-time range earn none, and awards never feed trust, admission, indexability, or order. 5. **We are not the npm of skills.** No publish flow and no namespace ownership. GitHub is the registry of record. Artifact delivery may cache immutable signed bytes for installation. It never becomes the source of truth. Protocol work serves the skilld CLI and requires a dated ADR. 6. **We do not optimize engagement.** Sessions per week is not a goal. Time-to-install and digest usefulness are. No streaks, no notification escalation, no re-engagement campaigns beyond the digest the user asked for. 7. **We are not an enterprise product.** No private registries, SSO, seats, or compliance surface. Private GitHub Artifact delivery is transient and account scoped. The free posture cannot carry enterprise support obligations. diff --git a/app/components/BadgeEmbedControl.vue b/app/components/BadgeEmbedControl.vue index b063cd04..4ea1a830 100644 --- a/app/components/BadgeEmbedControl.vue +++ b/app/components/BadgeEmbedControl.vue @@ -1,13 +1,20 @@