Skip to content

Commit 2b007ad

Browse files
harlan-zwharlan-zw
authored
feat: show what skilld does differently on home and vs page (#516)
1 parent 8c8116a commit 2b007ad

23 files changed

Lines changed: 2544 additions & 37 deletions

‎COPY.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,10 @@ These exact strings. Do not paraphrase them per page.
4949
| Demo provenance | {Agent logo} {model}, such as Opus 5.5 | guidance only: the recording line on the Skill page panel and the homepage stage. Screen readers and the title get "Recorded with {agent}, {model}". No date and no GitHub link: the Skill page is where visitors inspect a Skill |
5050
| Demo outdated | Recorded on an older version of this Skill. | guidance only: under the Demo panel when the Skill moved past the recorded commit |
5151
| Home section: changes | Keep up with skill changes. | guidance only: the homepage section heading for watching and the digest |
52+
| Home section: why | What skilld does differently. | guidance only: the homepage Why band heading, after trending. No line under it: the three columns from `HOME_WHY_REASONS` follow directly, each a title, `summary`, and picture. Their skills.sh lines stay on `/vs/skills-sh` |
53+
| Why trust line | Built by Harlan Wilton · Compare with skills.sh | guidance only: the line that closes the homepage Why band. The avatar and name link Harlan's GitHub, and the button opens `/vs/skills-sh`. The columns carry every claim, so the line carries none |
54+
| Why reasons | Human first · Preview the output · Independent and open source · Open trending weights · No more skill bloat · Know what it runs · Know what it costs · No telemetry | guidance only: the reason titles. Each has a one-line `summary` for the homepage and a full `line` for the comparison. The homepage shows the first three, which Harlan chose on 2026-10-07. `WHY_REASONS` in `app/utils/why-skilld.ts` holds each title, its line, and the sourced skills.sh line, and both surfaces read it. The Preview line opens with the Demos line above. Open trending weights links the ranking code, so its weights must match `shared/trending-skill-score.ts`. Know what it runs never claims a Skill is safe |
55+
| Comparison H1 | skilld vs skills.sh | guidance only: the `/vs/skills-sh` H1. Its lead says what skills.sh is before what skilld is. Every skills.sh fact carries its source link and the date it was checked |
5256
| Home section: authoring | Write a skill for your project. | guidance only: the homepage section heading for making a Skill |
5357
| Nav: developers | Developers | guidance only: the header menu trigger, and the group label in the mobile menu. The menu holds the four items below |
5458
| Nav: CLI | CLI · Search, run, install, and keep Skills current. | guidance only: the first compact row in the Developers menu: name, line. Links `/cli`. The mobile menu shows the name only. The line is the CLI line, so change that first |
@@ -66,7 +70,7 @@ These exact strings. Do not paraphrase them per page.
6670
| CLI claims line | Open-source CLI · No telemetry · 19 Agent targets | guidance only: the `/cli` claims line. The page counts the `--agent` values of `skilld install --help` |
6771
| CLI install label | Install the CLI | guidance only: the label beside the CLI install chip on `/cli`. A switch above the chip picks `macOS / Linux`, `Windows`, or `npm`, and `macOS / Linux` is preselected |
6872
| CLI install consequence | One native binary. It upgrades itself from signed releases. · Needs Node.js. npm handles upgrades. | guidance only: the line under the CLI install chip on `/cli`. The first is for `macOS / Linux` and `Windows`, the second for `npm`. `crates/skilld-command/src/upgrade.rs` in the CLI decides both. If it changes, change these strings |
69-
| Claim: open source | open-source CLI | guidance only: the CLI. Never call skilld.dev or its site open source |
73+
| Claim: open source | open source | guidance only: the CLI and the site. `skilld-dev/skilld` and `skilld-dev/skilld.dev` are both public under MIT, checked 2026-10-07. If either repository goes private, narrow the claim to the one a reader can clone. "No telemetry" still names the CLI only |
7074
| Claim: telemetry | no telemetry | guidance only: the CLI. Its README states that it sends no telemetry or analytics. Never say it of the site, which keeps anonymous analytics |
7175
| Claim: privacy | analytics without cookies or IPs | guidance only: analytics and privacy copy. Never the bare "privacy-friendly" |
7276
| Claim: comparison | skills.sh alternative | guidance only: always a link to `/vs/skills-sh` |
@@ -235,7 +239,6 @@ near-miss is also banned.
235239
| people (for our audience) | dev, devs | They are developers, and "people" is a vaguer word doing a smaller job. "Developers" in full is fine where the short form reads clipped |
236240
| first person in a CTA | the content, then the destination | "We send this every Monday" spends the words on us. "Trending skills to your inbox every Monday" gives the reader both things that matter |
237241
| privacy-friendly (bare) | analytics without cookies or IPs | A bare privacy claim cannot be checked. The mechanism can |
238-
| open source (for the site or skilld.dev) | open-source CLI | A reader must be able to clone what the claim names, and the claim names the CLI |
239242

240243
**Exception, the humans-versus-generated claim.** When the contrast is authorship by a human
241244
against machine generation, "human" and "person" are the right words and "dev" weakens the

‎app/components/HomeWhy.vue‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
<script setup lang="ts">
2+
import type { RecentPullRequest } from '#shared/open-source-pull-requests'
3+
import type { TrendingBoardRow } from '#shared/trending-range'
4+
import type { HomeDemoItem } from '~/utils/home-demos'
5+
import { HOME_WHY_REASONS, WHY_REASONS } from '~/utils/why-skilld'
6+
import WhyTrustLine from './why/_WhyTrustLine.vue'
7+
import WhyVisual from './why/_WhyVisual.vue'
8+
9+
/**
10+
* What skilld does differently from skills.sh, as three columns: a title, one
11+
* line, and a small picture of the real interface. The skills.sh side of each
12+
* reason lives on `/vs/skills-sh`, so the homepage stays light.
13+
*
14+
* From 1024px the columns share one subgrid, so the titles, lines and pictures
15+
* each sit on one row, and every column ends at the same height.
16+
*/
17+
const { trendingRow, demos, pulls } = defineProps<{
18+
/** The first trending row ranked by posts, for the people picture. */
19+
trendingRow: TrendingBoardRow | null
20+
/** The approved demos, for the previews picture. */
21+
demos: readonly HomeDemoItem[]
22+
/** Recently merged pull requests, for the open source picture. */
23+
pulls: readonly RecentPullRequest[]
24+
}>()
25+
26+
const reasons = HOME_WHY_REASONS.map(id => WHY_REASONS[id])
27+
</script>
28+
29+
<template>
30+
<section id="why" class="home-wm" aria-labelledby="why-heading">
31+
<span class="home-watermark" aria-hidden="true">Why</span>
32+
<div class="mx-auto max-w-6xl px-4 py-12 sm:px-6 md:py-16">
33+
<h2 id="why-heading" class="home-h2 text-balance">
34+
What skilld <span class="home-ink">does differently</span>.
35+
</h2>
36+
37+
<ul class="home-why mt-8 list-none p-0">
38+
<li v-for="reason in reasons" :key="reason.id" class="home-why__col">
39+
<h3 class="home-why__title">
40+
<UIcon :name="reason.icon" class="size-4 shrink-0 text-muted" aria-hidden="true" />
41+
{{ reason.title }}
42+
</h3>
43+
<p class="home-why__line">
44+
{{ reason.summary }}
45+
</p>
46+
<WhyVisual :id="reason.id" :trending-row="trendingRow" :demos :pulls compact class="home-why__visual" />
47+
</li>
48+
</ul>
49+
50+
<WhyTrustLine class="mt-8" />
51+
</div>
52+
</section>
53+
</template>
54+
55+
<style scoped>
56+
.home-why {
57+
display: grid;
58+
grid-template-columns: minmax(0, 1fr);
59+
gap: 2.5rem;
60+
}
61+
62+
.home-why__col {
63+
display: flex;
64+
min-width: 0;
65+
flex-direction: column;
66+
}
67+
68+
/* One subgrid: each row takes its tallest cell, so the pictures stretch to match. */
69+
@media (min-width: 64rem) {
70+
.home-why {
71+
grid-template-columns: repeat(3, minmax(0, 1fr));
72+
grid-template-rows: auto auto 1fr;
73+
column-gap: 1.5rem;
74+
row-gap: 0;
75+
}
76+
77+
.home-why__col {
78+
display: grid;
79+
grid-row: span 3;
80+
grid-template-rows: subgrid;
81+
}
82+
}
83+
84+
.home-why__title {
85+
display: flex;
86+
align-items: center;
87+
gap: 0.5rem;
88+
font-size: 1rem;
89+
font-weight: 600;
90+
line-height: 1.5rem;
91+
color: var(--ui-text-highlighted);
92+
}
93+
94+
.home-why__line {
95+
margin-top: 0.25rem;
96+
font-size: 0.875rem;
97+
line-height: 1.6;
98+
color: var(--ui-text-muted);
99+
text-wrap: pretty;
100+
}
101+
102+
.home-why__visual {
103+
margin-top: 1rem;
104+
}
105+
</style>

‎app/components/why/_WhyBehaviorsVisual.vue‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
<script setup lang="ts">
2+
import WhyPanel from './_WhyPanel.vue'
3+
4+
/**
5+
* Skill behaviors, drawn small. The first list is what `anthropics/skills/pdf`
6+
* asks an Agent to do, as production listed it on 2026-10-07, each with where
7+
* it appears. The second is the set the released CLI holds for approval:
8+
* a remote `skilld run` stops before any of them and changes nothing until the
9+
* user allows it. Labels are the rule labels from `skilld-protocol`.
10+
*/
11+
const SHOWN = [
12+
{ icon: 'i-lucide-terminal', label: 'Runs shell commands', where: 'SKILL.md:192' },
13+
{ icon: 'i-lucide-file-code', label: 'Ships scripts', where: '8 files' },
14+
{ icon: 'i-lucide-package', label: 'Installs or runs packages', where: 'SKILL.md:235' },
15+
]
16+
17+
const HELD = [
18+
'Runs code downloaded from the network',
19+
'Reads credential files or tokens',
20+
'Contains invisible characters',
21+
]
22+
23+
/** Approval behaviors past the three listed: root commands and destructive deletes. */
24+
const MORE_HELD = 2
25+
</script>
26+
27+
<template>
28+
<WhyPanel label="anthropics/skills/pdf · Skill behaviors">
29+
<ul class="why-behaviors" aria-label="What the pdf Skill asks your agent to do">
30+
<li v-for="behavior in SHOWN" :key="behavior.label" class="why-behaviors__row">
31+
<UIcon :name="behavior.icon" class="why-behaviors__icon text-muted" aria-hidden="true" />
32+
<span class="why-behaviors__label">{{ behavior.label }}</span>
33+
<span class="why-behaviors__where">{{ behavior.where }}</span>
34+
</li>
35+
</ul>
36+
<p class="why-behaviors__heading">
37+
<code>skilld run</code> waits for your approval:
38+
</p>
39+
<ul class="why-behaviors" aria-label="Behaviors skilld run holds until you approve them">
40+
<li v-for="label in HELD" :key="label" class="why-behaviors__row">
41+
<UIcon name="i-lucide-triangle-alert" class="why-behaviors__icon text-warning" aria-hidden="true" />
42+
<span class="why-behaviors__label">{{ label }}</span>
43+
</li>
44+
<li class="why-behaviors__row why-behaviors__more">
45+
+ {{ MORE_HELD }} more
46+
</li>
47+
</ul>
48+
</WhyPanel>
49+
</template>
50+
51+
<style scoped>
52+
.why-behaviors {
53+
display: grid;
54+
gap: 0.125rem;
55+
margin: 0;
56+
padding: 0;
57+
list-style: none;
58+
}
59+
60+
.why-behaviors__row {
61+
display: flex;
62+
min-width: 0;
63+
align-items: center;
64+
gap: 0.5rem;
65+
min-height: 1.5rem;
66+
}
67+
68+
.why-behaviors__icon {
69+
flex: none;
70+
width: 0.875rem;
71+
height: 0.875rem;
72+
}
73+
74+
.why-behaviors__label {
75+
min-width: 0;
76+
overflow: hidden;
77+
text-overflow: ellipsis;
78+
white-space: nowrap;
79+
font-family: var(--font-sans);
80+
font-size: 0.8125rem;
81+
color: var(--ui-text);
82+
}
83+
84+
.why-behaviors__where {
85+
flex: none;
86+
margin-left: auto;
87+
color: var(--ui-text-dimmed);
88+
}
89+
90+
.why-behaviors__more {
91+
padding-left: 1.375rem;
92+
color: var(--ui-text-dimmed);
93+
}
94+
95+
.why-behaviors__heading {
96+
margin-top: 0.875rem;
97+
margin-bottom: 0.375rem;
98+
padding-top: 0.75rem;
99+
border-top: 1px dashed var(--ui-border);
100+
/* Normal case, so the name keeps its lowercase (COPY.md). */
101+
color: var(--ui-text-muted);
102+
}
103+
</style>

‎app/components/why/_WhyCostVisual.vue‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
<script setup lang="ts">
2+
import WhyPanel from './_WhyPanel.vue'
3+
4+
/**
5+
* What a Skill costs an Agent's context, by when each part loads, as the
6+
* Skill page counts and names it: four bytes per token. The name and description load
7+
* in every session, SKILL.md when the Agent uses the Skill, and the other
8+
* Markdown only when SKILL.md sends the Agent there. Scripts run, so only
9+
* their output lands. `anthropics/skills/pdf` as production listed it on
10+
* 2026-10-07. Each bar is drawn in stone dots, its length to scale.
11+
*/
12+
interface Stage {
13+
when: string
14+
what: string
15+
tokens: number
16+
label: string
17+
}
18+
19+
const STAGES: Stage[] = [
20+
{ when: 'Always', what: 'name and description', tokens: 111, label: '≈111' },
21+
{ when: 'When used', what: 'SKILL.md', tokens: 1887, label: '≈1.9k' },
22+
{ when: 'On demand', what: 'forms.md, reference.md', tokens: 7137, label: '≈7.1k' },
23+
]
24+
25+
const MAX_TOKENS = Math.max(...STAGES.map(stage => stage.tokens))
26+
27+
function barWidth(tokens: number): string {
28+
// A floor, so the smallest stage still draws a dot or two.
29+
return `${Math.max(tokens / MAX_TOKENS * 100, 2.5)}%`
30+
}
31+
</script>
32+
33+
<template>
34+
<WhyPanel label="anthropics/skills/pdf · 11 files">
35+
<ul class="why-cost" aria-label="Tokens the pdf Skill adds to your agent's context">
36+
<li v-for="stage in STAGES" :key="stage.when" class="why-cost__stage">
37+
<span class="why-cost__head">
38+
<span class="why-cost__when">{{ stage.when }}</span>
39+
<span class="why-cost__tokens">{{ stage.label }} tokens</span>
40+
</span>
41+
<span class="why-cost__track" aria-hidden="true">
42+
<span class="why-cost__bar" :style="{ width: barWidth(stage.tokens) }" />
43+
</span>
44+
<span class="why-cost__what">{{ stage.what }}</span>
45+
</li>
46+
</ul>
47+
<p class="why-cost__scripts">
48+
<span>scripts/ · 8 files</span>
49+
<span>run, never read into context</span>
50+
</p>
51+
</WhyPanel>
52+
</template>
53+
54+
<style scoped>
55+
.why-cost {
56+
display: grid;
57+
gap: 0.875rem;
58+
margin: 0 0 0.875rem;
59+
padding: 0;
60+
list-style: none;
61+
}
62+
63+
.why-cost__stage {
64+
display: grid;
65+
gap: 0.25rem;
66+
}
67+
68+
.why-cost__head {
69+
display: flex;
70+
align-items: baseline;
71+
gap: 0.5rem;
72+
}
73+
74+
.why-cost__when {
75+
font-family: var(--font-sans);
76+
font-size: 0.8125rem;
77+
color: var(--ui-text-highlighted);
78+
}
79+
80+
.why-cost__tokens {
81+
margin-left: auto;
82+
color: var(--ui-text);
83+
font-variant-numeric: tabular-nums;
84+
}
85+
86+
/* The brand atom: a bar is a run of stone dots, never a fill. */
87+
.why-cost__track {
88+
display: block;
89+
height: 0.75rem;
90+
}
91+
92+
.why-cost__bar {
93+
display: block;
94+
height: 100%;
95+
background-image: radial-gradient(circle, var(--ui-text-muted) 1.6px, transparent 1.9px);
96+
background-size: 6px 6px;
97+
background-position: 0 0;
98+
}
99+
100+
.why-cost__what {
101+
color: var(--ui-text-dimmed);
102+
}
103+
104+
.why-cost__scripts {
105+
display: flex;
106+
flex-wrap: wrap;
107+
gap: 0.25rem 0.5rem;
108+
margin-top: auto;
109+
padding-top: 0.875rem;
110+
border-top: 1px dashed var(--ui-border);
111+
color: var(--ui-text-dimmed);
112+
}
113+
114+
.why-cost__scripts > span:last-child {
115+
margin-left: auto;
116+
}
117+
</style>

0 commit comments

Comments
 (0)