Convex (unofficial) Skills v1

A collection of AI-consumable skills for building production-ready applications with Convex, following the Agent Skills open format.

Overview

This repository contains skills that help AI assistants understand and implement Convex best practices. Each skill provides structured guidance for specific aspects of Convex development.

Installation

npm (recommended)

# Install globally for CLI access
npm install -g @waynesutton/convex-skills

# List available skills
convex-skills list

# Install a specific skill to your project
convex-skills install convex-best-practices

# Install all skills
convex-skills install-all

# Install templates (CLAUDE.md + skill templates)
convex-skills install-templates

Or use npx without installing:

npx @waynesutton/convex-skills list
npx @waynesutton/convex-skills install-all

Programmatic Usage

npm install @waynesutton/convex-skills

import { listSkills, getSkill, SKILLS } from "@waynesutton/convex-skills";

// List all skills
console.log(listSkills());

// Get a specific skill's content
const content = getSkill("convex-best-practices");

Claude Code (from local clone)

git clone https://github.com/waynesutton/convexskills.git
cd convexskills
# Point Claude Code to this directory

Codex

Follow the Codex skills guide and place the skill under $CODEX_HOME/skills:

# From the repo root
# Defaults to ~/.codex if CODEX_HOME is unset
cp -r skills/convex-best-practices "$CODEX_HOME/skills/"

Codex will auto-discover SKILL.md files in that directory on the next start.

OpenCode

OpenCode discovers skills from ~/.claude/skills/<name>/SKILL.md automatically. See OpenCode Skills docs for more details.

Slash Command

This repo includes a /convex slash command for OpenCode. Install the command by copying command/convex.md to your OpenCode commands directory:

# Copy the slash command
cp command/convex.md ~/.opencode/command/

# Usage in OpenCode
/convex create a schema with users and posts
/convex set up file uploads
/convex add a Stripe webhook endpoint

The slash command provides decision trees to route to the appropriate skill based on your task.

Manual Installation

Copy the desired skill's SKILL.md file to your project's .claude/skills/ directory.

Available Skills

| Skill | Description | | ------------------------------------------------------------------------ | ----------------------------------------------------- | | convex-best-practices | Guidelines for building production-ready Convex apps | | convex-functions | Writing queries, mutations, actions, and HTTP actions | | convex-realtime | Patterns for building reactive applications | | convex-schema-validator | Database schema definition and validation | | convex-file-storage | File upload, storage, and serving | | convex-agents | Building AI agents with Convex | | convex-cron-jobs | Scheduled functions and background tasks | | convex-http-actions | HTTP endpoints and webhook handling | | convex-migrations | Schema evolution and data migrations | | convex-security-check | Quick security audit checklist | | convex-security-audit | Deep security review patterns | | convex-component-authoring | Creating reusable Convex components |

Repository Structure

convex-skills/
├── skills/                   # Core Convex skills for AI agents
│   ├── convex-best-practices/
│   │   └── SKILL.md
│   ├── convex-functions/
│   │   └── SKILL.md
│   ├── convex-cron-jobs/
│   │   └── SKILL.md
│   └── ...
├── command/                  # Slash command definitions (OpenCode)
│   └── convex.md             # /convex command entrypoint
├── templates/                # Templates for forking developers
│   ├── CLAUDE.md             # Project context template
│   └── skills/               # Claude Code skill templates
│       ├── dev.md            # Full-stack development practices
│       ├── help.md           # Problem-solving methodology
│       └── gitrules.md       # Git safety protocols
├── .claude/skills/           # Active skills for this repo
├── prds/                     # Planning documents
├── AGENTS.md                 # Agent-facing documentation
├── CLAUDE.md                 # Claude configuration
├── GEMINI.md                 # Gemini CLI integration
├── README.md                 # This file
└── LICENSE                   # Apache-2.0

Templates for Forking

When you fork this repository, you can copy the templates to set up Claude Code skills for your project:

# Copy skill templates to your project
cp -r templates/skills/* .claude/skills/

# Or copy specific skills
cp templates/skills/dev.md .claude/skills/
cp templates/skills/help.md .claude/skills/
cp templates/skills/gitrules.md .claude/skills/

| Template | Description | | ------------------------------------------------------------ | -------------------------------------------- | | templates/CLAUDE.md | Project context template for Convex projects | | templates/skills/dev.md | Full-stack development practices | | templates/skills/help.md | Problem-solving methodology | | templates/skills/gitrules.md | Git safety protocols |

See templates/skills/README.md for detailed installation instructions.

Skill Format

Each skill follows the Agent Skills specification:

---
name: Skill Name
description: Brief description
version: 1.0.0
author: Convex
tags: [convex, ...]
---

# Skill Name

## Documentation Sources

## Instructions

## Examples

## Best Practices

## References

Usage

Skills are automatically available once installed. The agent will use them when relevant tasks are detected.

Examples:

Help me set up file uploads in Convex

Create a cron job to clean up expired sessions

Add a webhook endpoint for Stripe

Creating New Skills

Skills follow the Agent Skills specification. Each skill requires a SKILL.md file with YAML frontmatter.

Skill Template

Create a new directory under skills/:

skills/my-skill/
└── SKILL.md

SKILL.md format:

---
name: my-skill
description: A clear description of what this skill does
version: 1.0.0
author: Convex
tags: [convex, relevant-tags]
---

# My Skill Name

## Documentation Sources

Links to official documentation

## Instructions

Step-by-step guidance for the agent

## Examples

Concrete examples showing expected code patterns

## Best Practices

Specific rules to follow

## References

Additional resources

AI Integration Files

• AGENTS.md - Agent-facing documentation
• CLAUDE.md - Claude configuration for Convex projects
• GEMINI.md - Gemini CLI integration for Convex projects

License

Apache-2.0 License - see LICENSE for details.

References

• npm Package
• Convex Documentation
• Convex LLMs.txt
• Agent Skills Specification