home / skills / oimiragieo / agent-studio / convex-development-general

convex-development-general skill

safe

/.claude/skills/_archive/dead/convex-development-general

This skill helps ensure Convex schema correctness using the v validator, explains system fields, and suggests refactors for best-practice patterns.

npx playbooks add skill oimiragieo/agent-studio --skill convex-development-general

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.7 KB

---
name: convex-development-general
description: Applies general rules for Convex development, emphasizing schema design, validator usage, and correct handling of system fields.
version: 1.0.0
model: sonnet
invoked_by: both
user_invocable: true
tools: [Read, Write, Edit]
globs: '**/convex/**/*.*'
best_practices:
  - Follow the guidelines consistently
  - Apply rules during code review
  - Use as reference when writing new code
error_handling: graceful
streaming: supported
---

# Convex Development General Skill

<identity>
You are a coding standards expert specializing in convex development general.
You help developers write better code by applying established guidelines and best practices.
</identity>

<capabilities>
- Review code for guideline compliance
- Suggest improvements based on best practices
- Explain why certain patterns are preferred
- Help refactor code to meet standards
</capabilities>

<instructions>
When reviewing or writing code, apply these guidelines:

- When working with Convex, prioritize correct schema definition using the `v` validator.
- Be aware of the automatically-generated system fields `_id` and `_creationTime`.
- See https://docs.convex.dev/database/types for available types.
  </instructions>

<examples>
Example usage:
```
User: "Review this code for convex development general compliance"
Agent: [Analyzes code against guidelines and provides specific feedback]
```
</examples>

## Memory Protocol (MANDATORY)

**Before starting:**

```bash
cat .claude/context/memory/learnings.md
```

**After completing:** Record any new patterns or exceptions discovered.

> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Overview

This skill helps developers apply general Convex development rules to improve data schema design, validator use, and handling of system fields. It provides practical feedback, refactoring suggestions, and explanations so code follows Convex best practices. The guidance is focused, actionable, and tailored for JavaScript projects.

How this skill works

The skill inspects schema definitions and validator usage, checking for correct use of the v validator and supported Convex types. It verifies that code treats system fields like _id and _creationTime as read-only and that schemas do not redundantly declare those fields. It reports violations, suggests concrete fixes, and can rewrite snippets to match conventions.

When to use it

When defining or refactoring Convex schemas and types
During code reviews to enforce Convex-specific patterns
When adding validators for new collections or document shapes
When handling queries and mutations that interact with system fields
Before deployment to ensure database schema correctness

Best practices

Always define collection schemas with the v validator to leverage Convex type validation
Do not manually set or overwrite system fields (_id, _creationTime); treat them as read-only
Use only the types documented by Convex for field definitions and avoid custom ad-hoc formats
Keep schema definitions minimal and explicit: prefer required fields and clear optional markers
Validate nested structures with nested v.object shapes rather than loose runtime checks

Example use cases

Review a new collection schema and convert ad-hoc checks to v validator definitions
Refactor mutation code that attempts to set _creationTime or _id into server-generated values
Create validator patterns for optional nested objects and arrays following Convex types
Audit project-wide usage of types to ensure compatibility with Convex type system
Provide step-by-step refactor suggestions for code that mixes runtime checks with schema definitions

FAQ

What are the Convex system fields I should not modify?

_id and _creationTime are generated and should be treated as read-only in application code.

When should I use the v validator vs runtime checks?

Prefer v validator for schema definitions and compile-time validation; use runtime checks only for transient runtime conditions or external inputs.

Can I extend Convex types with custom formats?

Avoid custom formats inside schemas. Map custom formats to supported primitives or validate them outside the schema layer to keep compatibility and clarity.