From fbb8e4bcb8f5e2aae7ea661aa1216fd7e5e92e32 Mon Sep 17 00:00:00 2001
From: Mahmoud Abdelwahab <m@mahmoudw.com>
Date: Thu, 4 Jun 2026 03:00:54 +0300
Subject: [PATCH] Add AI plugin docs

---
 content/docs/agents.md                |  8 ++++
 content/docs/ai.md                    | 24 +++++-----
 content/docs/ai/agent-skills.md       |  2 +-
 content/docs/ai/claude-code-plugin.md | 12 ++---
 content/docs/ai/codex.md              | 54 ++++++++++++++++++++++
 content/docs/ai/cursor.md             | 66 +++++++++++++++++++++++++++
 content/docs/ai/plugins.md            | 43 +++++++++++++++++
 src/data/sidebar.ts                   | 15 +++++-
 8 files changed, 202 insertions(+), 22 deletions(-)
 create mode 100644 content/docs/ai/codex.md
 create mode 100644 content/docs/ai/cursor.md
 create mode 100644 content/docs/ai/plugins.md

diff --git a/content/docs/agents.md b/content/docs/agents.md
index 1c4453a44..4a140261f 100644
--- a/content/docs/agents.md
+++ b/content/docs/agents.md
@@ -35,6 +35,13 @@ railway setup agent
     icon="Monitor"
     tone="blue"
   />
+  <Card
+    title="Plugins"
+    description="Plugin packages install Railway skills and MCP configuration together for tools with plugin marketplaces."
+    href="/ai/plugins"
+    icon="Folder"
+    tone="yellow"
+  />
   <Card
     title="Agent Skills"
     description="The use-railway skill teaches AI coding agents how to operate Railway. Works with Claude Code, Cursor, Codex, OpenCode, Copilot, and Factory Droid."
@@ -49,4 +56,5 @@ railway setup agent
 - **Railway MCP (Local)** — preferred for agent-native operations on a logged-in machine: project and service discovery, deployment status, bounded logs, variables, domains, templates, metrics, and scoped mutations.
 - **Railway MCP (Remote)** — preferred when the user wants hosted OAuth MCP, or when local CLI configuration is unavailable. Also exposes the powerful `railway-agent` tool for multi-step operations.
 - **Railway CLI** — preferred when the task depends on local machine state: current-directory deploys, `railway up`, `railway run`, SSH, and local linking.
+- **Plugins** — preferred when your coding tool supports plugin marketplaces and you want host-managed installation for Railway skills and MCP configuration.
 - **Agent Skills** — install alongside any of the above so agents arrive with Railway-specific procedural knowledge instead of guessing.
diff --git a/content/docs/ai.md b/content/docs/ai.md
index 31e876cef..686b56f8a 100644
--- a/content/docs/ai.md
+++ b/content/docs/ai.md
@@ -1,6 +1,6 @@
 ---
 title: AI
-description: Integrate Railway with your AI coding assistants using Agent Skills, the Claude Code plugin, and the MCP Server.
+description: Integrate Railway with your AI coding assistants using the Railway Agent, plugins, Agent Skills, and the MCP Server.
 ---
 
 Railway provides tools for integrating with AI coding assistants, letting you manage your infrastructure through natural language.
@@ -17,6 +17,16 @@ The [Railway Agent](/ai/railway-agent) is a chat-based assistant built directly
 
 [Get started with the Railway Agent →](/ai/railway-agent)
 
+### Plugins
+
+[Railway plugins](/ai/plugins) package agent skills and MCP configuration for AI coding tools that support plugin marketplaces.
+
+- Supports Claude Code, OpenAI Codex, and Cursor
+- Includes the `use-railway` skill and MCP configuration
+- Provides tool-specific setup for [Codex](/ai/codex) and [Cursor](/ai/cursor)
+
+[Get started with plugins →](/ai/plugins)
+
 ### Agent skills
 
 [Agent Skills](/ai/agent-skills) are an open format for extending AI coding assistants with specialized knowledge about Railway. The `use-railway` skill guides AI agents to perform tasks like deploying services, managing environments, and querying metrics.
@@ -27,16 +37,6 @@ The [Railway Agent](/ai/railway-agent) is a chat-based assistant built directly
 
 [Get started with Agent Skills →](/ai/agent-skills)
 
-### Claude Code plugin
-
-The [Railway plugin for Claude Code](/ai/claude-code-plugin) provides the `use-railway` agent skill, hooks, and supporting scripts through Claude Code's plugin marketplace.
-
-- Install through the Claude Code plugin manager
-- Includes hooks and scripts alongside the agent skill
-- Auto-update support through the marketplace
-
-[Get started with the Claude Code plugin →](/ai/claude-code-plugin)
-
 ### MCP server
 
 The [Railway MCP Server](/ai/mcp-server) implements the Model Context Protocol, enabling direct communication between AI assistants and your Railway infrastructure. Choose between the local server (runs through the Railway CLI) or the hosted remote server at `mcp.railway.com` (OAuth, no local install).
@@ -45,4 +45,4 @@ The [Railway MCP Server](/ai/mcp-server) implements the Model Context Protocol,
 - Create projects, deploy templates, manage environments, pull variables
 - Works with Cursor, VS Code, Claude Code, Codex, Copilot, Factory Droid, OpenCode, Windsurf, Cline, and Devin
 
-[Get started with MCP Server →](/ai/mcp-server)
\ No newline at end of file
+[Get started with MCP Server →](/ai/mcp-server)
diff --git a/content/docs/ai/agent-skills.md b/content/docs/ai/agent-skills.md
index caa024761..579ab051a 100644
--- a/content/docs/ai/agent-skills.md
+++ b/content/docs/ai/agent-skills.md
@@ -53,7 +53,7 @@ npx skills add railwayapp/railway-skills
 
 Supports Claude Code, OpenAI Codex, OpenCode, and Cursor. Re-run to update.
 
-**Note:** For Claude Code, you can also install through the [Claude Code plugin marketplace](/ai/claude-code-plugin).
+**Note:** For Claude Code, OpenAI Codex, and Cursor, you can also install Railway through [plugin packages](/ai/plugins).
 
 ## The use-railway skill
 
diff --git a/content/docs/ai/claude-code-plugin.md b/content/docs/ai/claude-code-plugin.md
index 377756c3e..0d8f7c309 100644
--- a/content/docs/ai/claude-code-plugin.md
+++ b/content/docs/ai/claude-code-plugin.md
@@ -47,22 +47,18 @@ To update to the latest version, refresh the marketplace and reinstall:
 
 You can also enable auto-updates for the marketplace through the `/plugin` interface under the **Marketplaces** tab.
 
-## What's included
+## What is included
 
 The plugin installs the following components:
 
 - **`use-railway` skill** - A route-first agent skill that covers project setup, deployments, troubleshooting, environment configuration, networking, observability, and more. See [Agent Skills](/ai/agent-skills) for the full list of capabilities. The skill includes action-oriented reference documents and a GraphQL API helper script for authenticated Railway API requests.
 - **Auto-approve hook** - A `PreToolUse` hook that automatically approves Railway CLI commands and Railway API script calls, so Claude Code doesn't prompt for permission on every Railway operation.
 
-## Alternative installation
+## Use Claude Code without the plugin
 
-If you prefer to install the agent skill without the Claude Code plugin system, use the [`railway skills`](/cli/skills) command, which works across multiple AI coding assistants:
+Plugins are optional. If you prefer CLI-managed setup, use [Railway for Agents](/agents) to configure Claude Code with Railway skills and MCP.
 
-```bash
-railway skills install
-```
-
-See [Agent Skills](/ai/agent-skills) for more details.
+Use one setup path for Claude Code at a time. Plugin installs and CLI-managed setup can both write Railway skill or MCP configuration.
 
 ## Source
 
diff --git a/content/docs/ai/codex.md b/content/docs/ai/codex.md
new file mode 100644
index 000000000..009b2c447
--- /dev/null
+++ b/content/docs/ai/codex.md
@@ -0,0 +1,54 @@
+---
+title: OpenAI Codex
+description: Install and use the Railway plugin for OpenAI Codex.
+---
+
+OpenAI Codex can use Railway through the Railway plugin. The plugin packages the `use-railway` skill and Railway MCP configuration so Codex can deploy, configure, monitor, and troubleshoot Railway projects.
+
+## What the plugin includes
+
+The Railway Codex plugin is packaged from the [Railway skills repository](https://github.com/railwayapp/railway-skills). It includes:
+
+- The [`use-railway` skill](/ai/agent-skills#the-use-railway-skill)
+- Railway MCP configuration that starts `railway mcp`
+- Codex plugin metadata for marketplace discovery
+
+The plugin-provided MCP configuration uses the local [Railway CLI](/cli). Install and authenticate the CLI before using Railway MCP tools in Codex.
+
+## Install the plugin
+
+When Railway is available in your Codex plugin library:
+
+1. Open Codex.
+2. Select **Plugins**.
+3. Browse the plugin library.
+4. Search for Railway.
+5. Install the Railway plugin.
+
+After installation, ask Codex to deploy services, check project status, inspect logs, configure variables, or perform any workflow covered by the `use-railway` skill.
+
+## Example prompts
+
+Use natural language prompts that describe the Railway task you want Codex to perform:
+
+```plaintext
+Deploy this app to Railway.
+```
+
+```plaintext
+Check the Railway status for this project.
+```
+
+```plaintext
+Debug the latest Railway deployment.
+```
+
+## Use Codex without the plugin
+
+Plugins are optional. If Railway isn't available in your Codex plugin library, use [Railway for Agents](/agents) to configure Codex with Railway skills and MCP through the CLI-managed setup flow.
+
+Use one setup path for Codex at a time. Plugin installs and CLI-managed setup can both write Railway skill or MCP configuration.
+
+## Source
+
+The Railway Codex plugin is open-source and available on [GitHub](https://github.com/railwayapp/railway-skills).
diff --git a/content/docs/ai/cursor.md b/content/docs/ai/cursor.md
new file mode 100644
index 000000000..aec5d635a
--- /dev/null
+++ b/content/docs/ai/cursor.md
@@ -0,0 +1,66 @@
+---
+title: Cursor
+description: Install and use the Railway plugin for Cursor.
+---
+
+Cursor can use Railway through the Railway plugin. The plugin packages the `use-railway` skill and Cursor MCP configuration so Cursor can deploy, configure, monitor, and troubleshoot Railway projects.
+
+## What the plugin includes
+
+The Railway Cursor plugin is packaged from the [Railway skills repository](https://github.com/railwayapp/railway-skills). It includes:
+
+- The [`use-railway` skill](/ai/agent-skills#the-use-railway-skill)
+- Cursor MCP configuration that starts `railway mcp`
+- Cursor plugin metadata for marketplace discovery
+
+The plugin-provided MCP configuration uses the local [Railway CLI](/cli). Install and authenticate the CLI before using Railway MCP tools in Cursor.
+
+## Install from Cursor Marketplace
+
+When Railway is listed in the Cursor Marketplace:
+
+1. Open the marketplace panel in Cursor.
+2. Search for Railway.
+3. Install the Railway plugin.
+
+After installation, ask Cursor to deploy services, check project status, inspect logs, configure variables, or perform any workflow covered by the `use-railway` skill.
+
+## Distribute through a team marketplace
+
+Teams and Enterprise admins can distribute Railway from the GitHub repository as a team marketplace:
+
+1. Open the Cursor dashboard.
+2. Go to **Settings**.
+3. Open **Plugins**.
+4. In **Team Marketplaces**, click **Import**.
+5. Paste `https://github.com/railwayapp/railway-skills`.
+6. Review the parsed `railway` plugin.
+7. Optional: Set team access groups.
+8. Name and save the marketplace.
+9. Install the plugin from Cursor's marketplace panel, or mark it as required for a distribution group.
+
+## Example prompts
+
+Use natural language prompts that describe the Railway task you want Cursor to perform:
+
+```plaintext
+Deploy this app to Railway.
+```
+
+```plaintext
+Add a Postgres database to this Railway project.
+```
+
+```plaintext
+Check the latest deployment logs and diagnose the failure.
+```
+
+## Use Cursor without the plugin
+
+Plugins are optional. If Railway isn't available in Cursor, use [Railway for Agents](/agents) to configure Cursor with Railway skills and MCP through the CLI-managed setup flow.
+
+Use one setup path for Cursor at a time. Plugin installs and CLI-managed setup can both write Railway skill or MCP configuration.
+
+## Source
+
+The Railway Cursor plugin is open-source and available on [GitHub](https://github.com/railwayapp/railway-skills).
diff --git a/content/docs/ai/plugins.md b/content/docs/ai/plugins.md
new file mode 100644
index 000000000..b5f706812
--- /dev/null
+++ b/content/docs/ai/plugins.md
@@ -0,0 +1,43 @@
+---
+title: Plugins
+description: Install Railway plugins for AI coding tools such as Claude Code, OpenAI Codex, and Cursor.
+---
+
+Railway plugins package Railway agent skills and MCP configuration for AI coding tools that support plugin marketplaces. Use a plugin when you want the host tool to manage Railway's skill and MCP setup as one installable package.
+
+## Supported plugins
+
+The [Railway skills repository](https://github.com/railwayapp/railway-skills) packages Railway for the following plugin hosts:
+
+| Tool | Plugin support | Guide |
+|------|----------------|-------|
+| Claude Code | Claude Code plugin marketplace | [Claude Code plugin](/ai/claude-code-plugin) |
+| OpenAI Codex | Codex plugin manifest | [OpenAI Codex](/ai/codex) |
+| Cursor | Cursor plugin manifest and team marketplace support | [Cursor](/ai/cursor) |
+
+Each plugin uses the same `use-railway` skill. The skill gives agents Railway-specific guidance for project setup, deployments, troubleshooting, variables, networking, observability, and docs lookup.
+
+## What plugins include
+
+Railway plugin packages install the Railway agent surface into the host tool. The exact files depend on the host, but the package can include:
+
+- The [`use-railway` skill](/ai/agent-skills#the-use-railway-skill)
+- Railway MCP configuration that starts `railway mcp`
+- Host-specific plugin metadata for marketplace discovery
+- Supporting scripts and hooks where the host supports them
+
+The MCP configuration runs through the local [Railway CLI](/cli). Install and authenticate the CLI before using plugin-provided MCP tools.
+
+## Choose a plugin
+
+Use the page for your AI coding tool:
+
+- [Claude Code plugin](/ai/claude-code-plugin) explains the Claude Code marketplace install flow.
+- [OpenAI Codex](/ai/codex) explains how the Railway Codex plugin is packaged and installed.
+- [Cursor](/ai/cursor) explains Cursor marketplace and team marketplace installation.
+
+## Use skills or MCP without plugins
+
+Plugins are optional. If your tool doesn't support plugins, or you prefer CLI-managed setup, use [Railway for Agents](/agents). That page covers the `railway setup agent` flow for installing skills, configuring MCP, and checking Railway authentication.
+
+Use one setup path for a tool at a time. Plugin installs and CLI-managed setup can both write skill or MCP configuration for the same host.
diff --git a/src/data/sidebar.ts b/src/data/sidebar.ts
index fa4f164fe..9301bc63b 100644
--- a/src/data/sidebar.ts
+++ b/src/data/sidebar.ts
@@ -102,7 +102,20 @@ export const sidebarContent: ISidebarContent = [
   {
     title: "AI",
     slug: "/ai",
-    content: [makePage("Railway Agent", "ai"), makePage("Agent skills", "ai"), makePage("Claude Code plugin", "ai"), makePage("MCP server", "ai")],
+    content: [
+      makePage("Railway Agent", "ai"),
+      {
+        subTitle: "Plugins",
+        pages: [
+          makePage("Plugins", "ai"),
+          makePage("Claude Code plugin", "ai"),
+          makePage("OpenAI Codex", "ai", "/ai/codex"),
+          makePage("Cursor", "ai"),
+        ],
+      },
+      makePage("Agent skills", "ai"),
+      makePage("MCP server", "ai"),
+    ],
   },
   {
     title: "Templates & open source",