[!IMPORTANT] This repository has been archived. The content has moved to neondatabase/agent-skills.

Agent Skills are now a specification supported by all major agents and coding editors, providing more capabilities than rule files. We created a new repository following the agent-skills pattern introduced by Vercel.

Copy & paste — that's itCopy

npx skills add neondatabase/agent-skills

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 6 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

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

Templates for:

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

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

Complete authentication setup with @neondatabase/auth:

• Next.js App Router integration
• React SPA setup
• Auth client configuration templates
• API route handlers

Guides:

• guides/nextjs-setup.md - Next.js App Router workflow
• guides/react-spa-setup.md - React SPA workflow

Unified SDK setup with @neondatabase/neon-js:

• Combined auth + data API client
• Type-safe database operations
• Theming and customization

Guides:

• guides/setup.md - Complete setup workflow

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.

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)

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

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

• Kiro-specific onboarding guide

Neon Auth (neon-auth.mdc)

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

Neon JS (neon-js.mdc)

• Full Neon JS SDK with @neondatabase/neon-js
• Combined auth + data API client

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

TypeScript SDK (neon-typescript-sdk.mdc)

• Programmatic database management
• TypeScript-specific patterns

Python SDK (neon-python-sdk.mdc)

• Server-side operations
• Python integration patterns

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 (6 total)
│       ├── add-neon-docs/      # Docs installer skill
│       ├── neon-auth/          # Neon Auth skill
│       ├── neon-drizzle/       # Drizzle ORM skill
│       │   ├── SKILL.md
│       │   ├── guides/         # Workflow guides
│       │   ├── references/     # Technical docs
│       │   ├── scripts/        # Automation
│       │   └── templates/      # Code examples
│       ├── neon-js/            # Neon JS SDK skill
│       ├── neon-serverless/    # Serverless skill
│       └── neon-toolkit/       # Ephemeral DB skill
├── *.mdc                       # Context rules (16 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.