Skip to content
Back to search

waynesutton

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/waynesutton-builder-skills/badge.svg)](/listings/waynesutton-builder-skills)

HTML

<a href="/listings/waynesutton-builder-skills"><img src="/api/listings/waynesutton-builder-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

For Cursor, see [convex/convex-agent-plugins](https://github.com/convex/convex-agent-plugins). The full list of official skills is at [docs.convex.dev/ai/agent-skills](https://docs.convex.dev/ai/agent-skills).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 34 lines
  1. {
  2. "name": "waynesutton",
  3. "owner": {
  4. "name": "Wayne Sutton",
  5. "url": "https://waynesutton.ai"
  6. },
  7. "metadata": {
  8. "description": "Skills by Wayne Sutton for builders shipping Convex apps.",
  9. "version": "3.1.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "builder-skills",
  14. "source": "./",
  15. "description": "Workflow, security, and writing skills for builders shipping Convex apps. 11 skills.",
  16. "version": "3.1.0",
  17. "author": {
  18. "name": "Wayne Sutton",
  19. "url": "https://waynesutton.ai"
  20. },
  21. "homepage": "https://github.com/waynesutton/builder-skills",
  22. "license": "Apache-2.0",
  23. "keywords": [
  24. "convex",
  25. "skills",
  26. "prd",
  27. "workflow",
  28. "security",
  29. "writing"
  30. ],
  31. "category": "development"
  32. }
  33. ]
  34. }
README.md · README · 245 lines
  1. # builder-skills
  2. [![skills.sh](https://skills.sh/b/waynesutton/builder-skills)](https://skills.sh/waynesutton/builder-skills)
  3. [![npm](https://img.shields.io/npm/v/@waynesutton/builder-skills)](https://www.npmjs.com/package/@waynesutton/builder-skills)
  4. [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
  5. Workflow, building, and writing skills for builders shipping Convex apps. By [Wayne Sutton](https://waynesutton.ai).
  6. Eleven 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`.
  7. ```bash
  8. npx builder-skills
  9. ```
  10. ## Set up Convex first
  11. Convex 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.
  12. The fastest way in is to tell your agent:
  13. ```
  14. Read https://www.convex.dev/agent-setup.md and follow it.
  15. ```
  16. 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:
  17. ```bash
  18. npx convex ai-files install # in a Convex project
  19. npx skills add convex/agent-skills # official Convex skills, any agent
  20. claude plugin marketplace add anthropics/claude-plugins-official
  21. claude plugin install convex@claude-plugins-official --scope user
  22. codex plugin marketplace add convex/convex-codex-plugin
  23. codex plugin add convex@convex-codex-plugin
  24. ```
  25. For Cursor, see [convex/convex-agent-plugins](https://github.com/convex/convex-agent-plugins). The full list of official skills is at [docs.convex.dev/ai/agent-skills](https://docs.convex.dev/ai/agent-skills).
  26. ## Install
  27. Run it with no arguments and pick what you want:
  28. ```
  29. $ npx builder-skills
  30. builder-skills 3.0.0
  31. Workflow
  32. 1 workflow Triage, PRD, task.md, docs sync, lessons loop
  33. 2 create-prd Write a PRD in prds/ before non trivial work
  34. ...
  35. Skills to add [Enter = all, or 1,3,9 or 1-6]:
  36. Agents
  37. 1 Claude Code .claude/skills (found)
  38. 2 Codex .codex/skills
  39. ...
  40. Install for [Enter = Claude Code]:
  41. Add project starters (AGENTS.md, task.md, changelog.md, files.md, SECURITY.md, prds/)? [y/N]:
  42. ```
  43. It finds the agent folders already in your project and selects them by default. Nothing is installed until you answer the last prompt.
  44. Or skip the prompts:
  45. ```bash
  46. npx builder-skills add --all
  47. npx builder-skills add workflow create-prd update-project-docs sec-check
  48. npx builder-skills add --all --target claude,codex
  49. npx builder-skills init # project starters only
  50. npx builder-skills list # what is available (--json for agents)
  51. npx builder-skills update # refresh what you installed
  52. npx builder-skills start # a short router an agent can follow
  53. ```
  54. `--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`.
  55. <details>
  56. <summary><strong>skills.sh</strong></summary>
  57. ```bash
  58. npx skills add waynesutton/builder-skills
  59. npx skills add waynesutton/builder-skills --skill sec-check --skill write
  60. ```
  61. The installer asks which skills and which agents. It writes ordinary files you can edit. Pull updates with `npx skills update`.
  62. </details>
  63. <details>
  64. <summary><strong>Claude Code plugin</strong></summary>
  65. ```bash
  66. claude plugin marketplace add waynesutton/builder-skills
  67. claude plugin install builder-skills@waynesutton
  68. ```
  69. </details>
  70. ## Skills
  71. ### Workflow
  72. | Skill | Use when |
  73. | --- | --- |
  74. | [workflow](skills/workflow/SKILL.md) | Multi step work. Triage, PRD, `task.md`, docs sync, lessons loop |
  75. | [create-prd](skills/create-prd/SKILL.md) | Before a multi file feature, a schema change, or a hard bug |
  76. | [update-project-docs](skills/update-project-docs/SKILL.md) | A change landed. `/update` syncs the three docs from git and prints the commit message |
  77. | [git-safety](skills/git-safety/SKILL.md) | Any git command that could discard work |
  78. | [avoid-feature-creep](skills/avoid-feature-creep/SKILL.md) | Scope is drifting past the request |
  79. | [what-i-need-from-you](skills/what-i-need-from-you/SKILL.md) | Every turn. Ends with the exact asks, logged by id in `prds/` |
  80. ### Coding
  81. | Skill | Use when |
  82. | --- | --- |
  83. | [think-first](skills/think-first/SKILL.md) | A bug, a fix that did not work, or a vague request. Root cause first |
  84. | [dev](skills/dev/SKILL.md) | Writing app code in my house style: React, Convex, Convex Auth, Resend. Edit it to make it yours |
  85. | [state-machines](skills/state-machines/SKILL.md) | Auditing status fields and flows. Reports every state, every move, who can make it, and what is wrong |
  86. ### Security
  87. | Skill | Use when |
  88. | --- | --- |
  89. | [sec-check](skills/sec-check/SKILL.md) | Before a deploy, before a repo goes public, after AI generated code, or to verify a fix |
  90. `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.
  91. ### Writing
  92. | Skill | Use when |
  93. | --- | --- |
  94. | [write](skills/write/SKILL.md) | Drafting or proofing posts, docs, READMEs, emails, and commit messages |
  95. ## Project starters
  96. `npx builder-skills init` (or `y` at the last picker prompt) adds these to your project root. Nothing that exists is overwritten.
  97. | File | What it is |
  98. | --- | --- |
  99. | `AGENTS.md` (+ `CLAUDE.md` symlink) | Stack, commands, Convex rules, which skill to load when |
  100. | `task.md` | To Do, In Progress, Completed, with UTC timestamps |
  101. | `changelog.md` | Keep a Changelog. Dates from `git log`, never invented |
  102. | `files.md` | One line per file. What it is for |
  103. | `SECURITY.md` | What is public by design, who can do what, accepted risks. `sec-check` reads it first |
  104. | `prds/lessons.md` | One line per lesson. Read at session start |
  105. | `prds/what-i-need-from-you.md` | The asks log for `what-i-need-from-you` |
  106. ## How I build with these
  107. 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.
  108. A project run this way ends up with these next to the code:
  109. ```
  110. prds/ one PRD per non trivial change, lessons.md, what-i-need-from-you.md
  111. task.md what is queued, in flight, and done, with UTC timestamps
  112. changelog.md what shipped, dated from git log
  113. files.md what every file is for
  114. SECURITY.md the policy sec-check checks against
  115. ```
  116. ## Why this exists next to the official Convex skills
  117. 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.
  118. ## Moved in 3.0
  119. 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](https://github.com/waynesutton/builder-skills/tree/82d1ce2/skills).
  120. | Old skill | Use instead |
  121. | --- | --- |
  122. | `convex` | official `convex` |
  123. | `convex-functions`, `convex-schema-validator`, `convex-realtime`, `convex-http-actions`, `convex-file-storage` | official `convex-design`, plus `convex/_generated/ai/guidelines.md` |
  124. | `convex-best-practices` | official `convex-reviewer`, `convex-optimize` |
  125. | `convex-cron-jobs` | official `convex-crons` |
  126. | `convex-migrations` | official `convex-migrate`, `convex-migrate-rehearse` |
  127. | `convex-agents` | official `convex-agent` |
  128. | `convex-component-authoring` | official `convex-create-component` |
  129. | `convex-security-check`, `convex-security-audit` | `sec-check`, plus official `convex-authz` |
  130. | `project-workflow` | `workflow` and `create-prd` |
  131. | `project-docs` | `update-project-docs` |
  132. | `help` (template) | `think-first` |
  133. Coming from the old npm package? See [MIGRATING.md](MIGRATING.md).
  134. ## How a skill is built
  135. ```
  136. skills/sec-check/
  137. SKILL.md under 300 lines: when to use it, the steps, the checklist
  138. references/rules.md loaded only when the task needs it
  139. scripts/sec-scan.sh run with bash, so file modes do not matter
  140. agents/openai.yaml icon metadata for Codex
  141. assets/ icons
  142. ```
  143. 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](https://github.com/anthropics/skills/tree/main/skills/skill-creator) and the [OpenCode skills docs](https://opencode.ai/docs/skills/).
  144. `skills/manifest.json` is the one list of skills, groups, and retired names. The CLI, `index.js`, and the lint read it.
  145. ## Programmatic use
  146. ```js
  147. import { listSkills, getSkill, getSkillMeta, listRetired, GROUPS } from "@waynesutton/builder-skills";
  148. listSkills(); // ["workflow", "create-prd", ...]
  149. getSkillMeta("sec-check"); // { name, description }
  150. getSkill("git-safety"); // raw SKILL.md
  151. listRetired(); // [{ name, stub, replacement }]
  152. ```
  153. ## Repo layout
  154. ```
  155. skills/ the 11 skills, 12 retired stubs, manifest.json
  156. templates/ starters copied by init
  157. bin/cli.js the CLI
  158. index.js programmatic API
  159. packages/builder-skills/ the short npx name, forwards to the main package
  160. scripts/ check-skills.mjs (npm run check), the redirect package for the old npm name
  161. skills.sh.json how the skills.sh page groups skills
  162. .claude-plugin/ plugin.json and marketplace.json
  163. .codex/skills/ symlinks into skills/ so Codex finds them in this repo
  164. prds/ PRDs for this repo and lessons.md
  165. AGENTS.md agent context for this repo (CLAUDE.md symlinks here)
  166. ```
  167. ## Contributing
  168. Read [CONTRIBUTING.md](CONTRIBUTING.md). In short: keep `SKILL.md` under 300 lines, quote the description, link every reference file, and make sure `npm run check` passes.
  169. ## Related
  170. - [Convex docs](https://docs.convex.dev) and [llms.txt](https://docs.convex.dev/llms.txt)
  171. - [convex/agent-skills](https://github.com/convex/agent-skills), the official Convex skills
  172. - [convex/convex-agent-plugins](https://github.com/convex/convex-agent-plugins), the official Convex plugins
  173. - [Convex agent setup](https://www.convex.dev/agent-setup.md)
  174. - [skills.sh](https://skills.sh), the installer
  175. - [ui-skills](https://www.ui-skills.com), the CLI shape this one borrows
  176. ## License
  177. Apache-2.0. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.