Skills

A verdict says what to use. A skill says how to use it: the install line, the file layout, the settings that are wrong by default, and the check that proves it works. Skills live in skills/ in the public repository, one folder per skill, in the open Agent Skills format that the skills CLI reads.

Install

npx skills add WellWorn-dev/wellworn

The CLI clones the repository, lists what it found, and asks which skills and which agents to install to. Adding --list shows the catalogue without installing anything. Two skills are in the repository today:

Install one by name, without the prompts:

npx skills add WellWorn-dev/wellworn --skill better-auth-nextjs --agent claude-code -y

That copies the folder to .claude/skills/better-auth-nextjs/ in the current project and records the source in skills-lock.json:

{
  "version": 1,
  "skills": {
    "better-auth-nextjs": {
      "source": "WellWorn-dev/wellworn",
      "sourceType": "github",
      "skillPath": "skills/better-auth-nextjs/SKILL.md",
      "computedHash": "1ab27e0524097f164c2e07deff38dcb097b4774846333e930a72dcbd93f2a915"
    }
  }
}

Pass -g to install to ~/.claude/skills instead of the project, and -a to target another agent: the CLI supports Cursor, Codex, Cline, Windsurf, OpenCode and others, each with its own directory. A path straight to one skill works as a source too, which is the form verdicts print:

npx skills add WellWorn-dev/wellworn/skills/better-auth-nextjs

Verified 2026-09-08 against github.com

What a skill folder holds

One directory, one SKILL.md, no other required file. The frontmatter carries a name the CLI uses for the folder and a description the agent reads to decide whether the skill applies, so the description has to say when to use it, not only what it is:

---
name: better-auth-nextjs
description: Set up Better Auth 1.7 in a Next.js 16 App Router project with Drizzle on Postgres, email + password with verification, Google login, and the organization plugin. Use when a verdict picked Better Auth or when adding auth to a Next.js app.
---

The body of a Wellworn skill has four parts. A version line naming what it was verified against and the date. Numbered steps an agent can follow without opening anything else. A traps section, each entry the thing that silently misbehaves rather than the thing that errors. A check at the end that proves the setup works, written as an observation, not a claim. From the same file:

Cookie cache: role and plan changes wait up to 5 minutes. For role-gated routes call getSession with disableCookieCache: true, or disable session.cookieCache.

Keep the whole file short enough that an agent can read it in one go. Anything longer than a page belongs in the library's own documentation, which the verdict already links.

Writing one for a verdict

Skills are contributed the same way verdicts are, as a pull request against the public repository, and they go through the same human review. The rules that apply to the file:

• One folder per skill at skills/<slug>/SKILL.md, slug in lowercase with hyphens.
• State the exact versions you tested against and the date you tested them. A skill without versions cannot be rechecked.
• Every trap needs the symptom first and the fix second, the way an agent hits them.
• Commands must be copy-pasteable as written, with the package manager spelled out.

Contributing covers the review queue and what a reviewer checks before publishing.

How a skill reaches an agent

A published skill can be linked to the verdict it belongs to and to the package it is about. When a verdict has a skill on it, the recommend and compare answers carry a SKILL line with the install command:

SKILL npx skills add WellWorn-dev/wellworn/skills/better-auth-nextjs

The skill tool takes the slug on its own and answers with the version and the same install line, which is what an agent uses when it already knows which skill it wants. A slug with no published skill answers with a pointer to the skills index rather than an error, so a wrong guess costs one call and nothing else.