repository·main·Indexed 19 days ago
https://github.com/waynesutton/convexskillsA collection of unofficial AI-consumable skills following the Agent Skills open format to help AI coding agents implement Convex best practices. It includes a CLI for managing skills, programmatic JS/TS access, and templates for Claude Code, Codex, and OpenCode. Available skills cover areas such as schema validation, real-time patterns, HTTP actions, cron jobs, and security audits.
The avoid-feature-creep skill is designed to prevent scope bloat when building software, apps, or AI-powered products. Use this skill during feature planning, scope reviews, MVP development, or when managing backlogs to ensure focus on core user value and faster shipping cycles.
Key use cases:
The convex-security-audit skill provides deep security review patterns specifically designed for Convex applications. It focuses on auditing five critical areas:
This skill is intended to be used as a template or guide for performing comprehensive security reviews of Convex codebases.
name: convex-security-audit
displayName: Convex Security Audit
description: Deep security review patterns for authorization logic, data access boundaries, action isolation, rate limiting, and protecting sensitive operations
version: 1.0.0
author: Convex
tags: [convex, security, audit, authorization, rate-limiting, protection]Convex HTTP Actions allow you to build custom HTTP endpoints within your Convex application. These endpoints are primarily used for:
Convex provides different function types depending on whether you need to access the database, call external APIs, or handle HTTP requests. Choosing the correct type is critical for performance, security, and correctness.
| Type | Database Access | External APIs | Caching | Use Case |
|---|---|---|---|---|
| Query | Read-only | No | Yes, reactive | Fetching data |
| Mutation | Read/Write | No | No | Modifying data |
| Action | Via runQuery/runMutation | Yes | No | External integrations |
| HTTP Action | Via runQuery/runMutation | Yes | No | Webhooks, APIs |
The project supports multiple directory patterns for agent skills to ensure compatibility across different tools:
.claude/skills/ directory for active project context and guidelines (e.g., convex.md, dev.md, gitrules.md)..agents/skills/ directory. This is a compatibility path for tools that scan for standard agent skills. The CLI can create this directory or symlink it to the main skills/ directory..codex/ directory (refer to .codex/README.md for setup and symlink instructions).You can extend agent capabilities by defining tools using the tool function. A tool requires a name, description, parameters (using Convex v validation), and a handler function.
To use these tools, pass them in the tools array when calling agent.chat.
import { tool } from "@convex-dev/agent";
import { v } from "convex/values";
export const searchKnowledge = tool({
name: "search_knowledge",
description: "Search the knowledge base for relevant information",
parameters: v.object({
query: v.string(),
limit: v.optional(v.number()),
}),
handler: async (ctx, args) => {
// Implementation logic here
return results;
},
});
// Usage in agent.chat
const response = await agent.chat(ctx, {
threadId: args.threadId,
messages: [{ role: "user", content: args.message }],
tools: [searchKnowledge],
systemPrompt: "You are a helpful assistant.",
});convex skill acts as an index for all Convex development patterns. Instead of using a single monolithic skill, you should use specific sub-skills via their respective commands to get detailed guidance for your specific task. This umbrella skill routes to specialized skills like convex-functions, convex-realtime, and convex-agents.AI agents (like Claude, Cursor, or Copilot) often suggest improvements, refactors, or additional features that fall outside your current scope. Treat these suggestions as stakeholder requests:
Scope Decision Log to track their impact.In Convex schemas, there is a semantic difference between a field being optional and a field being nullable:
v.optional(v)): The field may be entirely absent from the document.v.union(v, v.null())): The field must exist in the document, but its value can be null.null value.export default defineSchema({
items: defineTable({
// Optional: field may not exist
description: v.optional(v.string()),
// Nullable: field exists but can be null
deletedAt: v.union(v.number(), v.null()),
// Optional and nullable
notes: v.optional(v.union(v.string(), v.null())),
}),
});When modifying a codebase, adhere to these strict boundaries regarding scope and design.
changelog.md or files.md, run git log --date=short to check history. Set release dates to match the real commit timeline; do not use placeholders or future months.Convex provides a reactive programming model based on four core principles:
useQuery creates a subscription that automatically updates the UI when the underlying data changes.