feat(skills): ship 5 distributable agent skills for library users

[braden-w]

Adds 5 distributable agent skills in skills/ so that any project using wellcrafted can teach their AI coding agent how to use it correctly. A developer who npm install wellcrafted and then runs npx skills add wellcrafted-dev/wellcrafted gets patterns, anti-patterns, and API conventions installed directly into their agent's context.

The library had 20 internal skills in .claude/skills/ that taught agents how to use wellcrafted — but they were locked to this repo, full of Whispering-specific references (RecorderError, DeviceStreamError, FfmpegError, Tauri platform detection). A developer's agent had no idea how to use defineErrors, would guess at patterns, produce as any casts, and create class-based errors instead of variant factories. These 5 skills fix that.

# What a wellcrafted user runs
npx skills add wellcrafted-dev/wellcrafted

wellcrafted/
├── .claude/skills/          ← Internal: for contributing to wellcrafted
│   └── ... (20 skills)
│
├── skills/                  ← Distributable: for USERS of wellcrafted
│   ├── define-errors/       defineErrors variants, extractErrorMessage, InferErrors
│   ├── result-types/        Ok, Err, trySync/tryAsync, { data, error } destructuring
│   ├── query-factories/     createQueryFactories, defineQuery/defineMutation, dual interface
│   ├── branded-types/       Brand<T>, brand constructor pattern
│   └── patterns/            Style guide: control flow, factory composition, service layers
│
└── src/                     ← Library source (unchanged)

How each skill was built

Every skill was adapted from internal .claude/skills/ sources. The adaptation rule was strict: every project-specific reference gets replaced with a generic domain, every import path uses wellcrafted/*, every anti-pattern gets a WRONG/CORRECT code block.

Skill	Lines	Adapted from	Key change
define-errors	272	.claude/skills/define-errors/	RecorderError → UserError, FfmpegError → FileError
result-types	264	.claude/skills/error-handling/	Stripped Elysia/handler sections, added utility function docs
query-factories	197	.claude/skills/query-layer/	Stripped Whispering RPC namespace, shows React + Svelte
branded-types	131	.claude/skills/typescript/ branded section	Stripped arktype pipe patterns, standalone focus
patterns	361	Merged from 4 skills: control-flow, factory-function-composition, services-layer, single-or-array-pattern	All Whispering services → generic UserService/HttpClient

Verified clean with grep -ri "whispering\|RecorderError\|DeviceStream\|FfmpegError\|Tauri\|Elysia" skills/ — zero hits.

What else changed

README.md gets a new "AI Agent Skills" section before "Development Setup" — tells library users how to install skills. The existing EpicenterHQ section for contributors stays untouched.

AGENTS.md updated to document the two-tier skill system: skills/ for library users, .claude/skills/ for contributors.

Spec at specs/20260311T124200-distributable-agent-skills.md — all items checked off, review section added. Committed alongside code so the git history shows what was planned vs. what was built.

Why this structure

npx skills discovers SKILL.md files in skills/ at repo root — no registry, no approval process, just push to GitHub. The tool scans multiple directories (skills/, root, curated/skills/, agent-specific dirs), so both skills/ and .claude/skills/ are found. A user running npx skills add wellcrafted-dev/wellcrafted sees all 5 distributable skills and can pick which ones to install.

The skills intentionally do NOT go in the npm package (not in files array). They're distributed via GitHub because npx skills pulls from repos, not npm. This means updating a skill is just a push to main — no version bump needed.

Why the skills are self-contained

Each skill is a standalone document with all patterns and anti-patterns inline. The alternative was linking back to README.md, but that means the agent would need to fetch external docs at runtime. Self-contained skills load instantly and work offline. There's some content overlap with the README, but the skills go deeper on patterns and anti-patterns than the README does — the README tells the high-level story, skills teach the detailed craft.