agentleFS
Sign inStart free
FabienGreardFabienGreard/TouchGrassBar/.agents/skills/convex-quickstart/SKILL.md

convex-quickstart

Skill5 starsChanged 54 days agoMITView on GitHub

Get a barebones Convex + web template running from a one-sentence idea.

We split this skill into the rules it gives an agent

5 rules. 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 19 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run recipe quickstart-recipe@^2 with {idea, template} (the pack fetches + caches it.

    line 14
  2. Distinctive:

    When it prints the dev URL, open it for the user.

    line 15
  3. Distinctive:

    Never re-run the recipe if it already reported success.

    line 20
  4. Very specific:

    Don't add Postgres/Redis/Express — use Convex primitives.

    line 22
  5. Distinctive:

    Don't add hosting/publish or pre-baked auth here — keep the template minimal unless the user asks for more.

    line 23

“Common” is measured: kept by at least 6 in 10 of the 19 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- GENERATED from convex-agents content/capabilities/quickstart.json — do not edit by hand. -->

Quickstart: a barebones Convex template, running

Stand up a barebones Next.js + Convex template from the idea, locally, with an anonymous dev deployment. Minimal by design: local dev servers, no publish step, no pre-baked auth.

Workflow

  1. Run recipe quickstart-recipe@^2 with {idea, template} (the pack fetches + caches it; pinned offline fallback). It creates the project, installs deps, starts the backend (anonymous) and the web dev server.
  2. When it prints the dev URL, open it for the user.
  3. Present a short plan and CONFIRM before building features beyond the template.

Rules

  • Never re-run the recipe if it already reported success.
  • Delegate any code under convex/ to the convex-expert capability.
  • Don't add Postgres/Redis/Express — use Convex primitives.
  • Don't add hosting/publish or pre-baked auth here — keep the template minimal unless the user asks for more.
  • DEGRADATION RULE — if the scaffold cannot run (non-interactive session, no network, a sandboxed temp dir, or the user just wants code, not an app): skip the recipe and write a standard Convex project directly. ALL backend code goes under convex/ (schema.ts, functions) — NEVER at the project root; Convex functions only run from the convex/ directory. Write ZERO scaffold/documentation files (no START_HERE.md, ARCHITECTURE.md, MANIFEST.txt, README walls) unless explicitly asked. "Build me a backend" means code, not ceremony.
  • Data access + imports — before writing any convex/*.ts: never an unbounded .collect() on a table that can grow — use .withIndex(...) and .paginate(...)/.take(n). Use an index, not .filter(), for anything that would be a SQL WHERE. .withIndex(...) callbacks only have eq/gt/gte/lt/lte — there is no .range(...) method. Imports: query/mutation/action/internalQuery/internalMutation/internalAction come from ./_generated/server; api/internal come from ./_generated/api; NEVER import from convex/server in application code. v.literal("exact value") for fixed string/enum members, not a bare string. "use node" only at the top of action-only modules — never in a file that also exports a query or mutation. Never import a Node builtin (crypto/fs/path/http/child_process/os, with or without the node: prefix) into a file lacking "use node" — including http.ts route handlers; use Web Crypto (crypto.subtle) instead of importing crypto where possible.
  • Reserved names — never export const <jsReservedWord> = ... (e.g. delete, new, class, function, return) as a query/mutation/action export name; esbuild fails to parse it. Never a table or index name starting with _ (e.g. _migrations: defineTable(...)) — _ is reserved and errors at push as TableNameReserved/IndexNameReserved.
  • HTTP routes — httpRouter has no Express-style :param segments (path: "/users/:id" only matches that literal string and is dead code); use pathPrefix and parse the trailing segment yourself. Every http.route({...}) handler: must be wrapped in httpAction(...) from ./_generated/server — a bare async (ctx, request) => {...} type-checks but isn't a valid HTTP action.
  • ctx.runQuery/ctx.runMutation/ctx.runAction need a codegen'd function reference (api.foo.bar/internal.foo.bar), never a raw imported module member (import * as queries from "./queries"; ctx.runQuery(queries.getX, ...) compiles but fails at runtime).
  • SELF-VERIFY RULE — before declaring backend work done, verify it compiles and pushes: run npx tsc --noEmit and, when a deployment is available (or via a local anonymous one: CONVEX_AGENT_MODE=anonymous npx convex dev --once), push it. Fix every error it reports before finishing — one verify round catches the wrong-relative-import / duplicate-symbol / unbalanced-paren class that otherwise breaks the deploy.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free