waynesutton/builder-skills

Overview

builder‑skills is a collection of agent skills that help AI coding assistants (Claude, Codex, Cursor, OpenCode, etc.) follow best‑practice conventions when building applications on Convex, a server‑less backend platform. The repo ships 17 small, self‑contained “SKILL.md” files – each a decision guide, example, checklist and references – that an LLM can load on‑demand. They cover Convex‑specific concerns (validators, indexes, migrations, security checks) and general project‑management habits (write a PRD, keep task/changelog/files docs, protect against destructive git commands).

The package can be installed via the generic skills.sh installer, a Claude Code plugin, or directly from npm. After installation a set of starter markdown files (AGENTS.md, task.md, changelog.md, etc.) is added to the user’s repo, giving the agent a structured workspace to track work and keep documentation in sync with the code.

---

Key Features

Feature	What it does	Why it matters
17 ready‑to‑use skills	Each skill is a SKILL.md (≤300 lines) with a description, usage trigger, example code and optional reference files.	Gives LLM agents concrete, vetted guidance so they don’t violate Convex conventions or break the repo.
Convex‑focused skills	Validators, indexes, idempotent mutations, HTTP actions, migrations, security checks, etc.	Keeps generated code aligned with Convex’s best practices and avoids runtime bugs.
Project‑workflow skills	project‑workflow, project‑docs, git‑safety, avoid‑feature‑creep.	Enforces a disciplined development loop: PRD → task tracking → automatic doc updates → safe git usage.
Multi‑agent installation	Supports Claude, Codex, Cursor, generic agents, or any custom folder via the npm CLI.	Lets teams use their preferred LLM assistant without rewriting the skills.
Template bootstrap	install-templates drops starter markdown files (AGENTS.md, task.md, changelog.md, files.md, prds/lessons.md).	Provides a ready‑made “knowledge base” that the agent can read/write during a session.
Programmatic API	listSkills, getSkillMeta, getSkill exported from the npm package.	Enables tooling or custom scripts to query or load a skill’s raw markdown.
Safety guardrails	git‑safety blocks destructive git commands unless explicitly approved.	Prevents accidental loss of work when an LLM tries to run a risky command.

---

Typical Use‑Case Flow

1. Install the skill set (e.g., npx skills add waynesutton/builder-skills).
2. Run npx @waynesutton/builder-skills install-templates – the repo now contains the five documentation files and editable skill stubs.
3. Ask the agent for a change. The agent first creates a PRD in prds/, adds a task entry in task.md, and then uses the appropriate Convex skill (e.g., convex-functions) to generate code.
4. After the change lands, run the project‑docs skill. It reads git log and the working tree, updates changelog.md, files.md, and task.md automatically, and scans for secrets.
5. Commit the changes using the commit message the skill prints.

The loop repeats, keeping code, documentation, and project tracking in sync while protecting against common pitfalls.

---

Installation Options

Method	How it works	When to use
skills.sh (npx skills add …)	Interactive installer writes plain files into your repo; updates later with npx skills update.	Preferred if you want editable files and a simple, agent‑agnostic setup.
Claude Code plugin (claude plugins …)	Registers the skills in Claude’s marketplace; Claude manages updates automatically.	If you primarily use Claude Code and want hands‑off updates.
npm CLI (npx @waynesutton/builder-skills install‑all …)	Copies or symlinks the skill files into a target folder (.claude/skills, .codex/skills, etc.).	For custom agents or when you need the skills in a specific directory.

---

Who Might Benefit

• Developers building Convex back‑ends who want AI assistance that respects Convex’s API contracts.
• Teams using LLM coding assistants (Claude, Codex, Cursor, OpenCode) and need a shared, enforceable set of rules.
• Project managers who want automated PRD/task tracking and documentation syncing.
• Open‑source contributors looking for a reproducible workflow that guards against accidental git data loss.

---

Limitations / Open Questions

• The skills are opinionated to the author’s workflow; they may need tweaking for different team conventions.
• They rely on the host LLM being able to read SKILL.md files; agents that don’t support this format will need a wrapper.
• No built‑in testing or CI integration – the skills generate code but you still need your own test suite.

---

Quick Start (CLI)

# Install the package globally or in a project
npm i -D @waynesutton/builder-skills

# Install all skills for Claude (default) and drop starter templates
npx @waynesutton/builder-skills install-all
npx @waynesutton/builder-skills install-templates

Now you have the markdown scaffolding and the skill files ready for your LLM assistant.

---

License

Apache‑2.0 – free for commercial and non‑commercial use.