Agent skill

Schema Builder

by waynesutton in waynesutton/markdown-site

Design and generate Convex database schemas with proper validation, indexes, and relationships.

MITAuto-check passed

Install Schema Builder

skills CLI

$ npx skills add waynesutton/markdown-site --skill schema-builder -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install waynesutton/markdown-site schema-builder --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/waynesutton/markdown-site.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/schema-builder .claude/skills/schema-builder && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "schema-builder" agent skill from https://github.com/waynesutton/markdown-site/tree/main/.claude/schema-builder into .claude/skills/schema-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "schema-builder", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/waynesutton/markdown-site/tree/main/.claude/schema-builder

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add waynesutton/markdown-site --skill schema-builder -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install waynesutton/markdown-site schema-builder --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/waynesutton/markdown-site.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.claude/schema-builder .agents/skills/schema-builder && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "schema-builder" agent skill from https://github.com/waynesutton/markdown-site/tree/main/.claude/schema-builder into .agents/skills/schema-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "schema-builder", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add waynesutton/markdown-site --skill schema-builder -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install waynesutton/markdown-site schema-builder --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/waynesutton/markdown-site.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.claude/schema-builder .cursor/skills/schema-builder && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "schema-builder" agent skill from https://github.com/waynesutton/markdown-site/tree/main/.claude/schema-builder into .cursor/skills/schema-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "schema-builder", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/waynesutton/markdown-site.git --path .claude/schema-builder

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add waynesutton/markdown-site --skill schema-builder -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install waynesutton/markdown-site schema-builder --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/waynesutton/markdown-site.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.claude/schema-builder .gemini/skills/schema-builder && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "schema-builder" agent skill from https://github.com/waynesutton/markdown-site/tree/main/.claude/schema-builder into .gemini/skills/schema-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "schema-builder", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install waynesutton/markdown-site schema-builder

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add waynesutton/markdown-site --skill schema-builder -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/waynesutton/markdown-site.git skills-src && mkdir -p .github/skills && cp -r skills-src/.claude/schema-builder .github/skills/schema-builder && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "schema-builder" agent skill from https://github.com/waynesutton/markdown-site/tree/main/.claude/schema-builder into .github/skills/schema-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "schema-builder", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add waynesutton/markdown-site --skill schema-builder -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install waynesutton/markdown-site schema-builder --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/waynesutton/markdown-site.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.claude/schema-builder .opencode/skills/schema-builder && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "schema-builder" agent skill from https://github.com/waynesutton/markdown-site/tree/main/.claude/schema-builder into .opencode/skills/schema-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "schema-builder", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: schema-builder
GitHub stars: 628
Token cost: ~872 tokens
SKILL.md length: 168 words
Files: 1
Skills in repo: 17
Repo updated: May 20, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Design and generate Convex database schemas with proper validation, indexes, and relationships.

Works in 4 steps: Document-Relational: Use flat documents… → Index Foreign Keys: Always index fields… → Limit Arrays: Only use arrays for small,… → …
Creating schema.ts
SKILL.md covers When to Use, Schema Design Principles, Schema Template and Common Patterns, plus 3 more sections
Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Schema Builder is an agent skill from waynesutton/markdown-site. Design and generate Convex database schemas with proper validation, indexes, and relationships. Use when creating schema.ts or modifying table definitions.

Its SKILL.md is about 870 tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It works with Convex. The repository describes itself as: An open-source publishing framework built for AI agents and developers to ship websites, docs, or blogs. Write markdown, sync from the terminal. Your content is instantly… The licence is MIT.

When your agent uses it

Creating schema.ts
Modifying table definitions

Example prompts

“/schema-builder”

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

Document-Relational: Use flat documents with ID references, not deep nesting
Index Foreign Keys: Always index fields used in lookups (userId, teamId, etc.)
Limit Arrays: Only use arrays for small, bounded collections (<8192 items)
Type Safety: Use strict validators with v.* types

What it can do on your machine

Read from SKILL.md and the folder at commit 3872c59. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md (its code samples are typescript).
From the folder's file list and the shell code blocks in SKILL.md.
Network
Links to these hosts (documentation or services it may open):
- github.com
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Schema Builder loads about 872 tokens when it runs. Until then it costs about 43 tokens; SKILL.md has 168 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~43
When it runs · the whole SKILL.md, loaded when a task matches: ~872

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from waynesutton/markdown-site at commit 3872c59, republished under its MIT licence (© waynesutton). 168 words, ~872 tokens.

Download SKILL.mdSave it as .claude/skills/schema-builder/SKILL.md (or your agent's skills folder).

name: schema-builder
description: Design and generate Convex database schemas with proper validation, indexes, and relationships. Use when creating schema.ts or modifying table definitions.

Convex Schema Builder

Build well-structured Convex schemas following best practices for relationships, indexes, and validators.

When to Use

Creating a new convex/schema.ts file
Adding tables to existing schema
Designing data model relationships
Adding or optimizing indexes
Converting nested data to relational structure

Schema Design Principles

Document-Relational: Use flat documents with ID references, not deep nesting
Index Foreign Keys: Always index fields used in lookups (userId, teamId, etc.)
Limit Arrays: Only use arrays for small, bounded collections (<8192 items)
Type Safety: Use strict validators with v.* types

Schema Template

typescript

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  tableName: defineTable({
    field: v.string(),
    optional: v.optional(v.number()),
    userId: v.id("users"),
    status: v.union(
      v.literal("active"),
      v.literal("pending"),
      v.literal("archived")
    ),
    createdAt: v.number(),
    updatedAt: v.optional(v.number()),
  })
    .index("by_user", ["userId"])
    .index("by_user_and_status", ["userId", "status"])
    .index("by_created", ["createdAt"]),
});

Common Patterns

One-to-Many Relationship

typescript

export default defineSchema({
  users: defineTable({
    name: v.string(),
    email: v.string(),
  }).index("by_email", ["email"]),

  posts: defineTable({
    userId: v.id("users"),
    title: v.string(),
    content: v.string(),
  }).index("by_user", ["userId"]),
});

Many-to-Many with Junction Table

typescript

export default defineSchema({
  users: defineTable({ name: v.string() }),
  projects: defineTable({ name: v.string() }),
  projectMembers: defineTable({
    userId: v.id("users"),
    projectId: v.id("projects"),
    role: v.union(v.literal("owner"), v.literal("member")),
  })
    .index("by_user", ["userId"])
    .index("by_project", ["projectId"])
    .index("by_project_and_user", ["projectId", "userId"]),
});

Hierarchical Data

typescript

export default defineSchema({
  comments: defineTable({
    postId: v.id("posts"),
    parentId: v.optional(v.id("comments")),
    userId: v.id("users"),
    text: v.string(),
  })
    .index("by_post", ["postId"])
    .index("by_parent", ["parentId"]),
});

Validator Reference

typescript

v.string()
v.number()
v.boolean()
v.null()
v.id("tableName")
v.optional(v.string())
v.union(v.literal("a"), v.literal("b"))
v.object({ key: v.string(), nested: v.number() })
v.array(v.string())
v.record(v.string(), v.boolean())
v.any()

Index Strategy

Single-field indexes: For simple lookups (by_user: ["userId"])
Compound indexes: For filtered queries (by_user_and_status: ["userId", "status"])
Remove redundant: by_a_and_b usually covers by_a

Checklist

All foreign keys have indexes
Common query patterns have compound indexes
Arrays are small and bounded (or converted to relations)
All fields have proper validators
Enums use v.union(v.literal(...)) pattern
Timestamps use v.number() (milliseconds since epoch)

Source: https://github.com/get-convex/convex-agent-plugins

Files

Just SKILL.md in .claude/schema-builder of waynesutton/markdown-site.

Open the folder on GitHubat commit 3872c59

Compare with similar skills

Schema Builder next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Schema Builder compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Schema Builder this skillwaynesutton/markdown-site	628	—	~872	Automated safety check: Pass	MIT	4 mo ago
Convex Migration Helperspokvulcan/poker-planning	114	8 repos	~1.4k	Automated safety check: Pass	MIT	3 days ago
Convex Quickstartspokvulcan/poker-planning	114	6 repos	~3.5k	Automated safety check: Notes	MIT	3 days ago
Convex Agentswaynesutton/builder-skills	404	—	~2.2k	Automated safety check: Pass	Apache-2.0	9 days ago
Convex Best Practiceswaynesutton/builder-skills	404	—	~2.6k	Automated safety check: Pass	Apache-2.0	9 days ago
Convex Release Auditudecode/kitcn	450	—	~1.8k	Automated safety check: Pass	Apache-2.0	6 days ago

Similar skills

Convex Migration Helper
spokvulcan/poker-planning
Plans Convex schema and data migrations with widen-migrate-narrow and @convex-dev/migrations.
114 GitHub starsUsed in 8 repos~1.4k tokens
Product & Project ManagementAuto-check passed
Convex Quickstart
spokvulcan/poker-planning
Creates or adds Convex to an app. An agent skill from spokvulcan/poker-planning.
114 GitHub starsUsed in 6 repos~3.5k tokens
Frontend & DesignAuto-check: notes
Convex Agents
waynesutton/builder-skills
Builds AI agents on the Convex agent component: threads, messages, tools that call queries and mutations, streaming, RAG with vector search, and workflows for multi step jobs.
404 GitHub stars~2.2k tokensUpdated 9 days ago
AI & LLM EngineeringAuto-check passed
Convex Best Practices
waynesutton/builder-skills
Production patterns for Convex apps and the rules the @convex-dev/eslint-plugin enforces: validators, indexes, idempotent mutations, avoiding OCC conflicts, thin function wrappers, error handling.
404 GitHub stars~2.6k tokensUpdated 9 days ago
DevelopmentAuto-check passed
Convex Release Audit
udecode/kitcn
Audit newer Convex npm releases against kitcn. An agent skill from udecode/kitcn.
450 GitHub stars~1.8k tokensUpdated 6 days ago
DevelopmentAuto-check passed
Convex Backend
CloudAI-X/claude-workflow-v2
Convex backend development guidelines. An agent skill from CloudAI-X/claude-workflow-v2.
1.4k GitHub stars~1.1k tokensUpdated yesterday
Backend & APIsAuto-check passed

Questions about Schema Builder

What does Schema Builder do?

Design and generate Convex database schemas with proper validation, indexes, and relationships. Schema Builder is an agent skill from waynesutton/markdown-site. Design and generate Convex database schemas with proper validation, indexes, and relationships.

When should I use Schema Builder?

Schema Builder fits situations like: creating schema.ts; modifying table definitions.

How do I install Schema Builder in Claude Code?

Run `npx skills add waynesutton/markdown-site --skill schema-builder -a claude-code`. Or copy the skill folder (.claude/schema-builder in waynesutton/markdown-site) into .claude/skills/schema-builder in your project. Claude Code loads it when a task matches its description.

How do I install Schema Builder in Codex?

Run `npx skills add waynesutton/markdown-site --skill schema-builder -a codex`. Or copy the skill folder (.claude/schema-builder in waynesutton/markdown-site) into .agents/skills/schema-builder in your project. Codex loads it when a task matches its description.

Can I use Schema Builder in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add waynesutton/markdown-site --skill schema-builder -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/schema-builder, .gemini/skills/schema-builder, .github/skills/schema-builder and .opencode/skills/schema-builder in your project.

What does Schema Builder need to run?

SKILL.md names no scripts, command-line tools or credentials: Schema Builder is instructions for the agent only.

Does Schema Builder access the network?

SKILL.md names 1 domain. As links in the text: github.com. This is read from the text; nothing was executed.

Is Schema Builder safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Schema Builder use?

Schema Builder is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Schema Builder use?

About 872 tokens (SKILL.md is roughly 3.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Schema Builder?

Skills that share tags, products or a category with Schema Builder: Convex Migration Helper (spokvulcan/poker-planning, 114 stars), Convex Quickstart (spokvulcan/poker-planning, 114 stars), Convex Agents (waynesutton/builder-skills, 404 stars) and Convex Best Practices (waynesutton/builder-skills, 404 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Schema Builder?

waynesutton (a GitHub user) maintains it in waynesutton/markdown-site, which has 628 GitHub stars. The repository holds 17 skills in this directory. The repository was last updated on May 20, 2026.

Source: waynesutton/markdown-site on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Schema Builder

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Convex Schema Builder

When to Use

Schema Design Principles

Schema Template

Common Patterns

One-to-Many Relationship

Many-to-Many with Junction Table

Hierarchical Data

Validator Reference

Index Strategy

Checklist

Files

Compare with similar skills

Similar skills

More from waynesutton/markdown-site

Related

Questions about Schema Builder