builder-skills

Agent skills for builders shipping Convex apps. By Wayne Sutton.

Seventeen skills. Fourteen teach an agent how to build on Convex the way the docs say to: validators on every function, indexes over filters, idempotent mutations, HTTP actions that verify signatures, migrations that do not take the app down. Three teach it how to run a project: write a PRD before touching code, keep task.md, changelog.md, and files.md true from git evidence, and never run a git command that can destroy work.

They work with Claude Code, Codex, Cursor, OpenCode, and anything else that reads a SKILL.md.

Looking for the official Convex skills? Those are at get-convex/convex-agent-plugins. This repo is my opinionated set, tuned for how I build.

Install

Three ways in. Pick one.

skills.sh (any agent, editable files)

npx skills add waynesutton/builder-skills

The installer asks which skills you want and which agents to install them for. It writes ordinary files into your repo that you can edit. Pull my updates later with npx skills update.

Claude Code plugin (managed, auto updates)

claude plugins marketplace add waynesutton/builder-skills
claude plugins install builder-skills@waynesutton

Or inside a session:

/plugin marketplace add waynesutton/builder-skills
/plugin install builder-skills@waynesutton

npm CLI (pick your target folder)

npx @waynesutton/builder-skills install-all
npx @waynesutton/builder-skills install-all --target codex
npx @waynesutton/builder-skills install-all --target cursor
npx @waynesutton/builder-skills install convex-functions project-workflow
npx @waynesutton/builder-skills install-templates

--target takes claude (default, .claude/skills), codex (.codex/skills), cursor (.cursor/skills), agents or opencode (.agents/skills), or any path. Add --link to symlink instead of copy.

Then run install-templates

npx @waynesutton/builder-skills install-templates

This drops five starter files at your project root and two editable skills in .claude/skills/:

File	What it is
AGENTS.md (+ CLAUDE.md symlink)	Stack, commands, rules, and a pointer to the skills
files.md	One line per file. What it is for.
changelog.md	Keep a Changelog. Dates from git log, never invented.
task.md	To Do / In Progress / Completed with UTC timestamps
prds/lessons.md	One line per lesson learned. Read at session start.
.claude/skills/dev/	House style. Edit it.
.claude/skills/help/	Root cause first, confidence bar, what not to touch. Edit it.

Nothing existing gets overwritten.

Why these exist

I build with Convex every day and I got tired of the same three failures.

The agent forgets the Convex rules. It writes filter instead of withIndex. It skips the returns validator. It schedules api.* instead of internal.*. It puts Date.now() in a query and wonders why the cache never hits. The convex-* skills fix that. Each one is short, points at https://docs.convex.dev/llms.txt for the current API, and pushes deep material into references/ so the agent only loads what the task needs.