mateonunez-skills

mateonunez-skills

Shipping AIt. Music on; nonsense off.

My agent skills — small, composable, behaviour-focused. Each one addresses a real failure mode I've watched coding agents hit, and steers the agent away from it before the failure happens. Organised the way Matt Pocock organises his.

These are not tool docs. They're behaviour interventions in my voice, encoding the way I work — Result<T, E> over throws, vertical slices over layers, Biome over the ESLint+Prettier stack, node:test over Jest. Forged on real projects: ait (a personal AI platform), mateonunez.co (Next.js 16 + WCAG 2.1 AA), and a fistful of Fastify plugins.

If it doesn't hold up in production, it doesn't make the cut.

Quick start

npx skills add mateonunez/skills

or

git clone https://github.com/mateonunez/skills.git
cd agentfiles
./scripts/link-skills.sh

The script symlinks every SKILL.md under skills/ (excluding deprecated/) into ~/.claude/skills/, where Claude Code picks them up.

Why these skills exist

I built these for the failure modes I see most often when collaborating with coding agents.

#1 — The agent throws everywhere

"Errors are values."
— Rob Pike

The problem: agents reflexively throw new Error() in service-layer code, then bury try/catch three layers up at the call site. Control flow becomes invisible. The type system can't help me — every function lies about what it can fail with.

The fix: /result-not-throw. Business logic returns Result<T, E> with discriminated __type errors. Throws are reserved for boundaries (HTTP handlers, CLI entry, framework adapters). The compiler enforces exhaustive error handling.

#2 — The agent reaches for Jest

"The standard library is the first thing you should reach for."
— common sense, often ignored

The problem: every greenfield package gets jest, @types/jest, ts-jest, babel-jest by default. Half a megabyte of dependencies for what node:test ships built into the runtime. Same story with ESLint + Prettier when Biome covers both.

The fix: /node-native-tests and /single-tool-per-job. Use the runtime. Use the one tool that does the job. New dev dependencies have to clear a real bar.

#3 — The agent organises by layer

"The best modules are deep. They allow a lot of functionality to be accessed through a simple interface."
— John Ousterhout, A Philosophy of Software Design

The problem: controllers/ here, services/ there, repositories/ over there. Every feature change touches five folders. The horizontal cuts ripple across the codebase on every PR.

The fix: /vertical-slices. Package by feature. The seam between features is a workspace package boundary, not a layer convention. Workspace protocol (workspace:*) and scoped packages (@scope/feature) make the boundary visible at every import site.

#4 — The agent normalises nothing

"The vendor's wire format is not my domain model."
— every ETL pipeline that ever survived a vendor breaking change

The problem: fetch('https://api.spotify.com/...').then(r => r.json()) and the response goes straight to the database. Three vendors later, every consumer special-cases every shape, and a Spotify API change cascades through six files.

The fix: /entity-normalization. At the boundary, normalise to a typed NormalizedEntity with a __type discriminator. Vendor noise lives in metadata. Downstream code is vendor-agnostic by construction.

#5 — The agent ships UI without a11y

"Accessibility is a baseline, not a feature."
— most of the web, getting it wrong

The problem: <div onClick> in place of <button>. Missing alt. outline: none with no replacement. Modals that don't trap focus. The agent ships UI that works for sighted, mouse-using users — and silently breaks for everyone else.

The fix: /a11y-default-review. A short checklist run after every UI change. Keyboard, focus, semantics, ARIA polish. The bar is WCAG 2.1 AA — the same bar I hold mateonunez.co to.

Reference

Engineering

Skills I use daily for code work.