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.

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 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

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/:

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.

The agent starts coding before it knows what it is building. project-workflow makes it triage first, write a two screen PRD in prds/, track the work in task.md, and record a lesson when the same correction happens twice.

The docs drift from the code. project-docs reads git log and the working tree, then updates changelog.md, files.md, and task.md from what shipped. It refuses to log a Convex component that is not registered in convex.config.ts, and it scans for secrets before saving. The evidence rules borrow from get-convex/convex-hackathon-skill.

And one more that cost me two days once: git-safety. No reset --hard, checkout -- ., clean -fd, or stash drop without the user saying yes to that exact command. "Undo" means edit the file, not check it out.

How I build with these

The loop is short. Ask for the change. The agent writes a PRD in prds/, builds against it, and moves the task through task.md. When it lands, /project-docs reads the git evidence and updates the three docs. Then I commit with the message it prints.

A project run this way ends up with four things next to the code:

prds/          one PRD per non trivial change, plus lessons.md
task.md        what is queued, in flight, and done, with UTC timestamps
changelog.md   what shipped, dated from git log
files.md       what every file is for

waynesutton-ai is the live example. This repo runs the same loop on itself.

Skills

Convex

Workflow

How a skill is built

skills/convex-http-actions/
  SKILL.md                    under 300 lines. decision guide, one canonical example, mistakes, checklist
  references/webhooks.md      loaded only when the task is a webhook
  references/rest-and-cors.md loaded only when the task is a REST route
  agents/openai.yaml          icon metadata for Codex
  assets/                     icons

Frontmatter is name and description only. The description is third person and ends with a Use when ... sentence, because that is what the agent reads to decide whether to load the skill. Everything else is progressive disclosure: metadata always, body on match, references on demand.

This follows the guidance in Anthropic's Agent Skills overview and OpenAI's Rethinking skills and prompts for GPT-6 Astra: short routers over long itineraries, triggers in the description, deep content one hop away.

Programmatic use

import { listSkills, getSkill, getSkillMeta, SKILLS } from "@waynesutton/builder-skills";

listSkills();                       // ["avoid-feature-creep", "convex", ...]
getSkillMeta("convex-functions");   // { name, description }
getSkill("git-safety");             // raw SKILL.md

Repo layout

skills/            the 17 skills
templates/         starters installed by install-templates
bin/cli.js         builder-skills CLI
index.js           programmatic API
scripts/           check-skills.mjs, run with npm run check
.claude-plugin/    plugin.json and marketplace.json
.codex/skills/     symlinks into skills/ so Codex finds them in this repo
command/convex.md  OpenCode slash command
prds/              PRDs for this repo and lessons.md
AGENTS.md          agent context for this repo (CLAUDE.md symlinks here)
GEMINI.md          Gemini CLI context

Contributing

Read CONTRIBUTING.md. Short version: keep SKILL.md under 300 lines, frontmatter is name + description, every reference file is linked, npm run check passes.

Related

• Convex docs and llms.txt
• get-convex/convex-agent-plugins, the official Convex skills
• get-convex/convex-hackathon-skill, evidence based build logs
• mattpocock/skills, the repo whose shape this one borrows
• waynesutton/markdown-site, the Convex publishing framework behind waynesutton.ai
• skills.sh, the installer

License

Apache-2.0. See LICENSE.