docs: migrate AI Rules to Agent Skills #4399
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| --- | ||
| title: 'Agent Skills: Neon API' | ||
| subtitle: Context and guidance for AI tools to use the Neon API | ||
| enableTableOfContents: true | ||
| updatedOn: '2026-01-27T00:00:00.000Z' | ||
| redirectFrom: | ||
| - /docs/ai/ai-rules-neon-api | ||
| --- | ||
|
|
||
| <Admonition type="note" title="Agent Skills"> | ||
| Agent Skills are new and actively being improved. We'd love your feedback! Join us on [Discord](https://discord.gg/92vNTzKDGp) to share suggestions. | ||
|
Contributor
There was a problem hiding this comment. You could add that we have an agent experience channel for this! |
||
| </Admonition> | ||
|
|
||
| <InfoBlock> | ||
| <DocsList title="Related docs" theme="docs"> | ||
| <a href="/docs/reference/api-reference">Neon API Reference</a> | ||
| </DocsList> | ||
|
|
||
| <DocsList title="Repository" theme="repo"> | ||
| <a href="https://github.com/neondatabase/agent-skills">Agent Skills Repository</a> | ||
| <a href="https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres/references/neon-rest-api">View API references</a> | ||
| </DocsList> | ||
| </InfoBlock> | ||
|
|
||
| ## What's covered | ||
|
|
||
| - REST API guidelines, authentication, and rate limiting | ||
| - Core concepts (Organization, Project, Branch, Endpoint, Database, Role) | ||
| - Managing projects, branches, endpoints, databases, and roles | ||
| - API keys and async operations | ||
|
|
||
| <AISkill name="Neon API" /> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| --- | ||
| title: 'Agent Skills: Neon Auth' | ||
| subtitle: Context and guidance for AI tools to help implement authentication with Neon Auth | ||
| enableTableOfContents: true | ||
| updatedOn: '2026-01-27T00:00:00.000Z' | ||
| redirectFrom: | ||
| - /docs/ai/ai-rules-neon-auth | ||
| --- | ||
|
|
||
| <Admonition type="note" title="Agent Skills"> | ||
| Agent Skills are new and actively being improved. We'd love your feedback! Join us on [Discord](https://discord.gg/92vNTzKDGp) to share suggestions. | ||
| </Admonition> | ||
|
|
||
| <InfoBlock> | ||
|
|
||
| <DocsList title="Related docs" theme="docs"> | ||
| <a href="/docs/guides/neon-auth">Neon Auth</a> | ||
| </DocsList> | ||
|
|
||
| <DocsList title="Repository" theme="repo"> | ||
| <a href="https://github.com/neondatabase/agent-skills">Agent Skills Repository</a> | ||
| <a href="https://github.com/neondatabase/agent-skills/blob/main/skills/neon-postgres/references/neon-auth.md">View this reference</a> | ||
| </DocsList> | ||
| </InfoBlock> | ||
|
|
||
| ## What's covered | ||
|
|
||
| - Package selection (`@neondatabase/auth` vs `@neondatabase/neon-js`) | ||
| - Setup patterns for Next.js App Router, React SPA, and Node.js | ||
| - Environment variables and key imports | ||
| - Common mistakes and troubleshooting | ||
|
|
||
| <AISkill name="Neon Auth" /> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| --- | ||
| title: 'Agent Skills: Neon with Drizzle' | ||
| subtitle: Context and guidance for AI tools to help implement Drizzle ORM with Neon databases | ||
| enableTableOfContents: true | ||
| updatedOn: '2026-01-27T00:00:00.000Z' | ||
| redirectFrom: | ||
| - /docs/ai/ai-rules-neon-drizzle | ||
| --- | ||
|
|
||
| <Admonition type="note" title="Agent Skills"> | ||
| Agent Skills are new and actively being improved. We'd love your feedback! Join us on [Discord](https://discord.gg/92vNTzKDGp) to share suggestions. | ||
| </Admonition> | ||
|
|
||
| <InfoBlock> | ||
| <DocsList title="Related docs" theme="docs"> | ||
| <a href="https://orm.drizzle.team/docs/get-started/neon-new">Get started with Drizzle and Neon</a> | ||
| </DocsList> | ||
|
|
||
| <DocsList title="Repository" theme="repo"> | ||
| <a href="https://github.com/neondatabase/agent-skills">Agent Skills Repository</a> | ||
| <a href="https://github.com/neondatabase/agent-skills/blob/main/skills/neon-postgres/references/neon-drizzle.md">View this reference</a> | ||
| </DocsList> | ||
| </InfoBlock> | ||
|
|
||
| ## What's covered | ||
|
|
||
| - Driver selection for different platforms (Vercel, Cloudflare, Railway, etc.) | ||
| - Connection setup (TCP, HTTP adapter, WebSocket adapter) | ||
| - Drizzle config and migrations | ||
| - Schema definition and query patterns | ||
| - Working with Neon branches | ||
|
|
||
| <AISkill name="Neon with Drizzle" /> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| --- | ||
| title: 'Agent Skills: Neon Python SDK' | ||
| subtitle: Context and guidance for AI tools to use the Neon Python SDK | ||
| enableTableOfContents: true | ||
| updatedOn: '2026-01-27T00:00:00.000Z' | ||
| redirectFrom: | ||
| - /docs/ai/ai-rules-neon-python-sdk | ||
| --- | ||
|
|
||
| <Admonition type="note" title="Agent Skills"> | ||
| Agent Skills are new and actively being improved. We'd love your feedback! Join us on [Discord](https://discord.gg/92vNTzKDGp) to share suggestions. | ||
| </Admonition> | ||
|
|
||
| <InfoBlock> | ||
| <DocsList title="Related docs" theme="docs"> | ||
| <a href="/docs/reference/python-sdk">Get started with Neon Python SDK</a> | ||
| <a href="/docs/reference/api-reference">Neon API Reference</a> | ||
| </DocsList> | ||
|
|
||
| <DocsList title="Repository" theme="repo"> | ||
| <a href="https://github.com/neondatabase/neon-api-python">Github Repo</a> | ||
| <a href="https://neon-api-python.readthedocs.io/en/latest/">Python SDK Docs</a> | ||
| <a href="https://github.com/neondatabase/agent-skills">Agent Skills Repository</a> | ||
| <a href="https://github.com/neondatabase/agent-skills/blob/main/skills/neon-postgres/references/neon-python-sdk.md">View this reference</a> | ||
| </DocsList> | ||
| </InfoBlock> | ||
|
|
||
| ## What's covered | ||
|
|
||
| - Managing projects, branches, endpoints, databases, and roles | ||
| - API keys and operations | ||
| - Error handling patterns | ||
|
|
||
| <AISkill name="Neon Python SDK" /> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| --- | ||
| title: 'Agent Skills: Neon Serverless Driver' | ||
| subtitle: Context and guidance for AI tools to help implement the Neon Serverless driver | ||
| enableTableOfContents: true | ||
| updatedOn: '2026-01-27T00:00:00.000Z' | ||
| redirectFrom: | ||
| - /docs/ai/ai-rules-neon-serverless | ||
| --- | ||
|
|
||
| <Admonition type="note" title="Agent Skills"> | ||
| Agent Skills are new and actively being improved. We'd love your feedback! Join us on [Discord](https://discord.gg/92vNTzKDGp) to share suggestions. | ||
| </Admonition> | ||
|
|
||
| <InfoBlock> | ||
| <DocsList title="Related docs" theme="docs"> | ||
| <a href="/docs/serverless/serverless-driver">Neon Serverless Driver</a> | ||
| </DocsList> | ||
|
|
||
| <DocsList title="Repository" theme="repo"> | ||
| <a href="https://github.com/neondatabase/agent-skills">Agent Skills Repository</a> | ||
| <a href="https://github.com/neondatabase/agent-skills/blob/main/skills/neon-postgres/references/neon-serverless.md">View this reference</a> | ||
| </DocsList> | ||
| </InfoBlock> | ||
|
|
||
| ## What's covered | ||
|
|
||
| - HTTP queries with the `neon()` function | ||
| - WebSocket connections with `Pool` and `Client` | ||
| - Transactions (HTTP and interactive) | ||
| - ORM integration (Prisma, Kysely, Drizzle) | ||
| - Environment-specific optimizations (Vercel Edge, Cloudflare) | ||
|
|
||
| <AISkill name="Neon Serverless" /> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| --- | ||
| title: 'Agent Skills: Neon API TypeScript SDK' | ||
| subtitle: Context and guidance for AI tools to use the Neon API TypeScript SDK | ||
| enableTableOfContents: true | ||
| updatedOn: '2026-01-27T00:00:00.000Z' | ||
| redirectFrom: | ||
| - /docs/ai/ai-rules-neon-typescript-sdk | ||
| --- | ||
|
|
||
| <Admonition type="note" title="Agent Skills"> | ||
| Agent Skills are new and actively being improved. We'd love your feedback! Join us on [Discord](https://discord.gg/92vNTzKDGp) to share suggestions. | ||
| </Admonition> | ||
|
|
||
| <InfoBlock> | ||
| <DocsList title="Related docs" theme="docs"> | ||
| <a href="/docs/reference/typescript-sdk">Get started with Neon API TypeScript SDK</a> | ||
| <a href="/docs/reference/api-reference">Neon API Reference</a> | ||
| </DocsList> | ||
|
|
||
| <DocsList title="Repository" theme="repo"> | ||
| <a href="https://www.npmjs.com/package/@neondatabase/api-client">@neondatabase/api-client on npm</a> | ||
| <a href="https://github.com/neondatabase/agent-skills">Agent Skills Repository</a> | ||
| <a href="https://github.com/neondatabase/agent-skills/blob/main/skills/neon-postgres/references/neon-typescript-sdk.md">View this reference</a> | ||
| </DocsList> | ||
| </InfoBlock> | ||
|
|
||
| ## What's covered | ||
|
|
||
| - Managing projects, branches, endpoints, databases, and roles | ||
| - API keys and organizations | ||
| - Async operations | ||
| - Error handling patterns | ||
|
|
||
| <AISkill name="Neon TypeScript SDK" /> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| --- | ||
| title: Agent Skills | ||
| subtitle: Enhance your AI development experience with Neon-specific context and guidance | ||
| enableTableOfContents: true | ||
| updatedOn: '2026-01-27T00:00:00.000Z' | ||
| redirectFrom: | ||
| - /docs/ai/ai-rules | ||
| - /docs/ai/ai-rules-neon-toolkit | ||
| --- | ||
|
|
||
| Boost your productivity with Agent Skills for Neon. These skills help AI assistants understand Neon's features, leading to more accurate code suggestions and fewer common mistakes. | ||
|
|
||
| Install the Neon agent skill to get started: | ||
|
|
||
| ```bash | ||
| npx add-skill neondatabase/agent-skills | ||
| ``` | ||
|
|
||
| This works with **Cursor**, **Claude Code**, and other AI tools that support the [Agent Skills](https://agentskills.io) format. | ||
|
|
||
| <Admonition type="note" title="Agent Skills"> | ||
| Agent Skills are new and actively being improved. We'd love your feedback! Join us on [Discord](https://discord.gg/92vNTzKDGp) to share suggestions. | ||
| </Admonition> | ||
|
|
||
| ## What's covered | ||
|
|
||
| The Neon agent skill provides guidance across the full Neon development workflow: | ||
|
|
||
| - **Getting started** — Project setup, Neon features (branching, autoscaling, scale-to-zero) | ||
| - **Connections** — Serverless driver, connection methods, Drizzle ORM | ||
| - **Authentication & Data** — Neon Auth, neon-js Data API | ||
| - **Platform APIs & SDKs** — REST API, TypeScript SDK, Python SDK | ||
| - **Developer tools** — CLI, VS Code extension, MCP server | ||
|
|
||
| The skill automatically loads relevant context based on your task. For the complete reference, see the [Agent Skills repository](https://github.com/neondatabase/agent-skills). | ||
|
|
||
| ## How it works | ||
|
|
||
| Agent Skills use a progressive disclosure model. When you install a skill: | ||
|
|
||
| 1. **Entry point**: The agent reads the SKILL.md file to understand what guidance is available | ||
| 2. **On-demand loading**: Detailed reference files are only loaded when needed for specific tasks | ||
| 3. **Context efficiency**: Agents don't waste tokens on information they don't need | ||
|
|
||
| ### Example: Agent Skills in action | ||
|
|
||
| Here's a practical example using [Cursor](https://www.cursor.so). A developer wants to set up Neon Auth in their Next.js app: | ||
|
|
||
| **Developer prompt**: _"Set up Neon Auth for my Next.js app"_ | ||
|
|
||
| The AI assistant automatically uses the installed Neon skill to provide accurate, up-to-date guidance for authentication setup, including proper imports, configuration, and best practices. | ||
|
|
||
| ### Alternative: Browse individual references | ||
|
Contributor
There was a problem hiding this comment. I would cut this section - not sure why this would be needed :) |
||
|
|
||
| If you prefer to work with individual reference files, you can browse and download them directly from the [Agent Skills repository](https://github.com/neondatabase/agent-skills). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If I understand this correctly, these ai/agent-skills-* files would be indexes for a given topic from which the agent can then go deeper by following the references listed here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, although this is a good question. Honestly, it's repurposing the existing rules pages (rename->update) so is limited in nature (only 6) for this initial conversion.
Upon reimagining, let's discuss soon about how agent skills can integrate more closely (and become) the documentation.