Workflow, building, and writing skills for builders shipping Convex apps. By Wayne Sutton.
Ten skills that teach a coding agent how to run a project: triage before code, write a PRD, keep task.md, changelog.md, and files.md true from git, never run a git command that destroys work, check security before you ship, and write like you. They work with Threadbear,Claude Code, Codex, Cursor, OpenCode, and any agent that reads a SKILL.md.
npx builder-skillsConvex knowledge (functions, schema, auth, crons, migrations, components) now comes from the official Convex skills and plugins. Use those for Convex APIs. Use builder-skills for everything around them.
The fastest way in is to tell your agent:
Read https://www.convex.dev/agent-setup.md and follow it.
That installs the Convex AI files (convex/_generated/ai/guidelines.md and .agents/skills) and the Convex plugin for each coding agent on your machine. To do it by hand:
npx convex ai-files install # in a Convex project
npx skills add convex/agent-skills # official Convex skills, any agent
claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install convex@claude-plugins-official --scope user
codex plugin marketplace add convex/convex-codex-plugin
codex plugin add convex@convex-codex-pluginFor Cursor, see convex/convex-agent-plugins. The full list of official skills is at docs.convex.dev/ai/agent-skills.
Run it with no arguments and pick what you want:
$ npx builder-skills
builder-skills 3.0.0
Workflow
1 workflow Triage, PRD, task.md, docs sync, lessons loop
2 create-prd Write a PRD in prds/ before non trivial work
...
Skills to add [Enter = all, or 1,3,9 or 1-6]:
Agents
1 Claude Code .claude/skills (found)
2 Codex .codex/skills
...
Install for [Enter = Claude Code]:
Add project starters (AGENTS.md, task.md, changelog.md, files.md, SECURITY.md, prds/)? [y/N]:
It finds the agent folders already in your project and selects them by default. Nothing is installed until you answer the last prompt.
Or skip the prompts:
npx builder-skills add --all
npx builder-skills add workflow create-prd update-project-docs sec-check
npx builder-skills add --all --target claude,codex
npx builder-skills init # project starters only
npx builder-skills list # what is available (--json for agents)
npx builder-skills update # refresh what you installed
npx builder-skills start # a short router an agent can follow--target takes claude (.claude/skills), codex (.codex/skills), cursor (.cursor/skills), opencode (.opencode/skills), agents (.agents/skills), a path, or a comma separated list. --link symlinks instead of copying. npx @waynesutton/builder-skills works the same as npx builder-skills.
skills.sh
npx skills add waynesutton/builder-skills
npx skills add waynesutton/builder-skills --skill sec-check --skill writeThe installer asks which skills and which agents. It writes ordinary files you can edit. Pull updates with npx skills update.
Claude Code plugin
claude plugin marketplace add waynesutton/builder-skills
claude plugin install builder-skills@waynesutton| Skill | Use when |
|---|---|
| workflow | Multi step work. Triage, PRD, task.md, docs sync, lessons loop |
| create-prd | Before a multi file feature, a schema change, or a hard bug |
| update-project-docs | A change landed. /update syncs the three docs from git and prints the commit message |
| git-safety | Any git command that could discard work |
| avoid-feature-creep | Scope is drifting past the request |
| what-i-need-from-you | Every turn. Ends with the exact asks, logged by id in prds/ |
| Skill | Use when |
|---|---|
| think-first | A bug, a fix that did not work, or a vague request. Root cause first |
| dev | Writing app code in my house style: React, Convex, Convex Auth, Resend. Edit it to make it yours |
| Skill | Use when |
|---|---|
| sec-check | Before a deploy, before a repo goes public, after AI generated code, or to verify a fix |
sec-check ships a secret scanner and a per function ledger in scripts/, then makes the agent prove an attacker path before it calls anything a finding. It covers leaked keys, client prefixed secrets, public functions with no auth, identity taken from args, paid AI spend, unsigned webhooks, open uploads, unsafe HTML, prompt injection into agent tools, and CI deploy keys. Every rule comes from a mistake that shipped.
| Skill | Use when |
|---|---|
| write | Drafting or proofing posts, docs, READMEs, emails, and commit messages |
npx builder-skills init (or y at the last picker prompt) adds these to your project root. Nothing that exists is overwritten.
| File | What it is |
|---|---|
AGENTS.md (+ CLAUDE.md symlink) |
Stack, commands, Convex rules, which skill to load when |
task.md |
To Do, In Progress, Completed, with UTC timestamps |
changelog.md |
Keep a Changelog. Dates from git log, never invented |
files.md |
One line per file. What it is for |
SECURITY.md |
What is public by design, who can do what, accepted risks. sec-check reads it first |
prds/lessons.md |
One line per lesson. Read at session start |
prds/what-i-need-from-you.md |
The asks log for what-i-need-from-you |
The loop is short. Ask for the change. The agent triages, writes a PRD in prds/, builds against it, and moves the task through task.md. When it lands, /update reads the git evidence, syncs the three docs, and prints a commit message. Before a deploy, sec-check. I commit.
A project run this way ends up with these next to the code:
prds/ one PRD per non trivial change, lessons.md, what-i-need-from-you.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
SECURITY.md the policy sec-check checks against
Convex's own skills know Convex best, so this repo no longer tries to. It covers the parts of shipping that are not Convex APIs: planning, tracking, docs that match the code, git habits, security review, and writing.
The Convex skills that used to live here moved to the official set. Each of the old folders below (except convex) still ships for one release as a short stub that names its replacement, so npx skills update tells you where to go. Run npx builder-skills add <old-name> and the CLI prints the replacement too. The old content is at commit 82d1ce2.
| Old skill | Use instead |
|---|---|
convex |
official convex |
convex-functions, convex-schema-validator, convex-realtime, convex-http-actions, convex-file-storage |
official convex-design, plus convex/_generated/ai/guidelines.md |
convex-best-practices |
official convex-reviewer, convex-optimize |
convex-cron-jobs |
official convex-crons |
convex-migrations |
official convex-migrate, convex-migrate-rehearse |
convex-agents |
official convex-agent |
convex-component-authoring |
official convex-create-component |
convex-security-check, convex-security-audit |
sec-check, plus official convex-authz |
project-workflow |
workflow and create-prd |
project-docs |
update-project-docs |
help (template) |
think-first |
Coming from the old npm package? See MIGRATING.md.
skills/sec-check/
SKILL.md under 300 lines: when to use it, the steps, the checklist
references/rules.md loaded only when the task needs it
scripts/sec-scan.sh run with bash, so file modes do not matter
agents/openai.yaml icon metadata for Codex
assets/ icons
Frontmatter is name and a quoted description only. The description says what the skill does and ends with a Use when ... sentence, because that is what the agent reads to decide whether to load it. Deep material sits one hop away in references/. This follows Anthropic's skill authoring guide and the OpenCode skills docs.
skills/manifest.json is the one list of skills, groups, and retired names. The CLI, index.js, and the lint read it.
import { listSkills, getSkill, getSkillMeta, listRetired, GROUPS } from "@waynesutton/builder-skills";
listSkills(); // ["workflow", "create-prd", ...]
getSkillMeta("sec-check"); // { name, description }
getSkill("git-safety"); // raw SKILL.md
listRetired(); // [{ name, stub, replacement }]skills/ the 10 skills, 12 retired stubs, manifest.json
templates/ starters copied by init
bin/cli.js the CLI
index.js programmatic API
packages/builder-skills/ the short npx name, forwards to the main package
scripts/ check-skills.mjs (npm run check), the redirect package for the old npm name
skills.sh.json how the skills.sh page groups skills
.claude-plugin/ plugin.json and marketplace.json
.codex/skills/ symlinks into skills/ so Codex finds them in this repo
prds/ PRDs for this repo and lessons.md
AGENTS.md agent context for this repo (CLAUDE.md symlinks here)
Read CONTRIBUTING.md. In short: keep SKILL.md under 300 lines, quote the description, link every reference file, and make sure npm run check passes.
- Convex docs and llms.txt
- convex/agent-skills, the official Convex skills
- convex/convex-agent-plugins, the official Convex plugins
- Convex agent setup
- skills.sh, the installer
- ui-skills, the CLI shape this one borrows
Apache-2.0. See LICENSE.