feat(telemetry): record which agent skills init installed

[gabrielmeloc22]

Problem

We ship agent skills with clerk init but can't measure whether they change anything. Nothing in telemetry says which skills a project has — or whether it has any. Every run looks identical whether the developer installed them, declined the prompt, or had no package runner on PATH. The existing skills stage only proves init reached that step.

That makes the return on any skill change unmeasurable, and it hides a number nobody currently knows: how often people decline the install. That decline rate is the ceiling on the reach of every skill we write.

What this adds

Two payload fields:

• skills — the installed skill names, comma-joined
• skills_outcome — installed | declined | runner_missing | failed

Only a successful install populates skills, so a filter like skills LIKE '%clerk-orgs%' means this project has that skill rather than it was offered one. skills_outcome is what separates "the user said no" from "init never got that far".

The names come from DEFAULT_UPSTREAM_SKILLS and FRAMEWORK_SKILL_MAP, so only CLI constants reach the payload — same constraint flags already follows by recording names and never values. TelemetrySkillsOutcome is a closed union for the same reason TelemetryStage is: a renamed call site fails to compile instead of quietly splitting the funnel.

installSkills already distinguished all four exits internally and threw that away by returning void; this records them.

Disclosure

The telemetry notice enumerates what's collected, so it now names this field too. Worth checking whether clerk.com/docs/telemetry needs the same addition — that page is outside this repo.

Deliberately not included

Skill versions. The CLI doesn't know them: the external skills CLI resolves clerk/skills at HEAD and writes files into per-agent directories, so reading versions back means locating those dirs and parsing YAML frontmatter — fragile, and it breaks whenever that CLI changes layout. Since skills install at init and don't auto-update, event timestamp plus the clerk/skills history pins the version to within a commit, which is enough for cohorting.

Testing

bun run test — 2697 pass, 0 fail. Typecheck, lint, and format clean.

New coverage: the four installSkills exits each record the right outcome, a decline never probes for a runner, non-installed outcomes leave skills empty, and a command that never reaches the step reports null.

Notes

• Draft because the field names are the part worth arguing about before anything lands in the warehouse — they're awkward to change once queries depend on them.
• Only covers skills installed by clerk init. A manual npx skills add clerk/skills stays invisible.
• skills update can move a project between cohorts later. Rare, but it means the timestamp proxy degrades.

[changeset-bot]

🦋 Changeset detected

Latest commit: 4e7ec34

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}