Neon AI Development Toolkit

A comprehensive Claude Code plugin with AI context rules, guided skills, and resource management tools for building with Neon Postgres. Works with Claude Code, Cursor, and other AI-powered development tools.

What's Inside

For Claude Code Users

• Claude Code Plugin - The plugin itself, which includes the 4 skills and MCP server integration
• Claude Code Skills - Interactive workflows with templates and automation scripts for Neon
• MCP Server Integration - Direct Neon resource management (projects, branches, databases)

For Cursor & Other AI Tools

• Portable .mdc Files - Standalone context rules that work anywhere
• Tool-Agnostic Format - Use with any AI assistant supporting custom rules

---

Quick Start

Claude Code

1. Add the Neon marketplace:

/plugin marketplace add neondatabase-labs/ai-rules

2. Install the plugin:

/plugin install neon-plugin@neon

3. Verify installation: Ask Claude Code: "which skills do you have access to?"

You should see the Neon skills listed.

4. Start using: Use natural language and skills activate automatically:

> Use the neon-drizzle skill to setup Drizzle ORM with Neon

Cursor

1. Create rules directory:

mkdir -p .cursor/rules

2. Copy desired .mdc files:

# Example: Copy Drizzle and Serverless rules
cp neon-drizzle.mdc .cursor/rules/
cp neon-serverless.mdc .cursor/rules/

3. Start coding: Cursor automatically applies these rules when you reference Neon.

Other AI Tools

Copy .mdc files to your AI tool's custom rules directory. The format is tool-agnostic and works with any AI assistant supporting context rules.

---

Skills Reference

Neon Drizzle - Setup Drizzle ORM with Neon

Complete workflow support for:

• New project setup
• Existing project integration
• Schema-only workflows

Includes:

• Schema generation utilities
• Migration scripts (db:generate, db:migrate, db:push, db:studio)
• HTTP and WebSocket adapter templates
• Technical references for adapters, migrations, and query patterns

Guides:

• guides/new-project.md - Starting from scratch
• guides/existing-project.md - Adding to existing codebase
• guides/schema-only.md - Schema-first development
• guides/troubleshooting.md - Common issues and solutions

Neon Serverless - Configure serverless database connections

Templates for:

• HTTP connections (single-query operations)
• WebSocket pooling (long-running processes)
• Connection validation utilities

Neon Toolkit - Manage ephemeral databases

Perfect for testing and CI/CD:

• Create temporary databases
• Run tests in isolation
• Clean up automatically

Includes:

• create-ephemeral-db.ts - Database creation
• destroy-ephemeral-db.ts - Cleanup automation
• Workflow templates

Add Neon Docs - Install documentation references

Adds Neon best practices to your project's AI configuration:

• CLAUDE.md
• AGENTS.md
• Cursor rules files

---

Testing & Quality Assurance

Our skills are tested with automated evaluations to ensure reliability and quality.

Skill	Pass Rate	Test Date	Details
neon-drizzle	95.0% (19/20)	Oct 29, 2025	View Results
add-neon-docs	91.7% (55/60)	Oct 28, 2025	View Results

Evaluation Methodology: Each skill is tested with multiple prompts across 10+ iterations using real Claude Code environments with the plugin loaded. Scorers validate build success, skill activation, and output correctness.

---

Context Rules (.mdc Files)

Getting Started - 1 file

Neon Get Started (neon-get-started.mdc)

• Interactive onboarding guide for connecting projects to Neon
• Step-by-step setup (projects, connection strings, dependencies, schema)
• Works with new or existing codebases
• Communication style guidelines for AI assistants

Core Integration Rules - 4 files

Neon Auth (neon-auth.mdc)

• Stack Auth + Neon Auth integration
• Authentication patterns for user data

Neon Serverless (neon-serverless.mdc)

• Serverless connection patterns
• Pooling and environment configuration
• Query optimization

Neon with Drizzle (neon-drizzle.mdc)

• Drizzle ORM integration
• Schema definition patterns
• Type-safe queries

Neon Toolkit (neon-toolkit.mdc)

• Ephemeral database management
• Testing and prototyping patterns

SDK Rules - 2 files

TypeScript SDK (neon-typescript-sdk.mdc)

• Programmatic database management
• TypeScript-specific patterns

Python SDK (neon-python-sdk.mdc)

• Server-side operations
• Python integration patterns

Neon API Rules - 7 files

API Guidelines (neon-api-guidelines.mdc)

• REST API best practices
• Security and authentication

API Projects (neon-api-projects.mdc)

• Project management operations

API Branches (neon-api-branches.mdc)

• Branch management and workflows

API Endpoints (neon-api-endpoints.mdc)

• Compute endpoint management

API Roles (neon-api-organizations.mdc)

• Organization and role management

API Keys (neon-api-keys.mdc)

• API key management
• Authentication configuration

API Operations (neon-api-operations.mdc)

• Operation execution
• Status monitoring

---

MCP Server Integration

Available automatically when you activate the Claude Code plugin.

Features:

• Manage Neon resources: projects, branches, endpoints, roles
• Execute SQL queries directly from Claude
• Run migrations
• Analyze query performance
• Optimize database operations

Configuration: neon-plugin/.mcp.json connects to Neon's remote MCP service (https://mcp.neon.tech/mcp)

---

Repository Structure

ai-rules/
├── .claude-plugin/
│   └── marketplace.json        # Marketplace metadata
├── neon-plugin/                # Claude Code plugin
│   ├── .claude-plugin/
│   │   └── plugin.json         # Plugin configuration
│   ├── .mcp.json               # MCP server connection
│   └── skills/                 # Guided skills
│       ├── neon-drizzle/       # Drizzle ORM skill
│       │   ├── SKILL.md
│       │   ├── guides/         # Workflow guides
│       │   ├── references/     # Technical docs
│       │   ├── scripts/        # Automation
│       │   └── templates/      # Code examples
│       ├── neon-serverless/    # Serverless skill
│       ├── neon-toolkit/       # Ephemeral DB skill
│       └── add-neon-docs/      # Docs installer skill
├── *.mdc                       # Context rules (14 files)
├── LICENSE
└── README.md

---

FAQ

What are .mdc files? Markdown Context files that provide guidance to AI tools. They contain best practices and patterns that AI assistants automatically apply when generating code.

Can I use specific rules without the full plugin? Yes! Copy individual .mdc files to your AI tool's rules directory. Each file is self-contained and doesn't require dependencies.

How do I add or update rules? Create a new .mdc file or edit existing ones. AI tools will automatically use the updated content.

Do skills work with Cursor? Skills are Claude Code-specific. For Cursor, use the .mdc context rules instead.

Can I use these rules in ChatGPT or other AI tools? Yes! The .mdc files work with any AI assistant that supports custom context rules. Copy them to your tool's configuration directory.

---

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

---

Support

• Documentation: https://neon.com/docs/ai/ai-rules
• Issues: https://github.com/neondatabase-labs/ai-rules/issues
• Discord: https://discord.com/channels/1176467419317940276/@home

---

License

MIT License - see LICENSE file for details.