Skip to content

docs: migrate AI Rules to Agent Skills#4399

Open
philip wants to merge 4 commits intomainfrom
ai-rules-to-agent-skills
Open

docs: migrate AI Rules to Agent Skills#4399
philip wants to merge 4 commits intomainfrom
ai-rules-to-agent-skills

Conversation

@philip
Copy link
Collaborator

@philip philip commented Jan 27, 2026

Transition documentation from ai-rules (.mdc) to agent-skills format. Updates navigation, internal links, and related pages.

Note: This PR is not ready to merge but is okay to review. Thinking of alternatives to our ExternalCode usage here as it can be overwhelming. One idea is to have copy/view skill options rather than insert the entire skill into the doc.

Post-MVP enhancements include integrating skills with our custom prompts, include skill references in llms.txt, and investigate adding an llms-full.txt.

@philip philip requested a review from danieltprice as a code owner January 27, 2026 20:41
@vercel
Copy link

vercel bot commented Jan 27, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
neon-next Ready Ready Preview, Comment Jan 30, 2026 3:57pm

Request Review

@danieltprice
Copy link
Collaborator

I agree that displaying the rules/prompts is a bit much. I'd prefer that we have:

  1. Copy prompt buttons where it makes sense to support that workflow of a user who like to read and grab a prompt.
  2. Skills in the skills repo (this is a different AI workflow)
    2.a. Solid docs with user & AI-friendly docs wherever the Skills are linking out (supporting the idea of progressive disclosure)

With that in mind, maybe we can turn these rules into copy prompts and/or doc examples (if the examples do not already exists in the docs). The copy prompts could be added to the most appropriate location in the docs.

philip and others added 2 commits January 30, 2026 07:44
Transition documentation from ai-rules (.mdc) to agent-skills format.
Updates navigation, internal links, and related pages.
---

<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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You could add that we have an agent experience channel for this!

@@ -0,0 +1,32 @@
---
Copy link
Contributor

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?

Copy link
Collaborator Author

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.


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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would cut this section - not sure why this would be needed :)


Once installed, your AI assistant can access {name} guidance automatically without manual configuration.

### Alternatives
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here - I don't think I understand the workflow one would use when following this section?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants