railwayapp/railway-skills: Agent Skills and Plugin Packaging for Railway

What railway-skills actually distributes

The repository ships one installable skill. The README names it plainly: use-railway, stored at plugins/railway/skills/use-railway/SKILL.md. Everything else in the tree is packaging. There is a .claude-plugin directory, a .cursor-plugin directory, a .agents directory, and a plugins directory holding per-client manifests such as plugins/railway/.codex-plugin/plugin.json and plugins/railway/.cursor-plugin/plugin.json.

So the audience is narrow and specific. It is for engineers who already deploy on Railway and want an agent, whichever agent they use, to be able to act on that Railway account. It is not for someone evaluating Railway, and it is not a general infrastructure library. The README describes the skill as route-first: intent routing lives in SKILL.md, and execution details are split into action-oriented references. That is a documentation architecture decision, and it means the skill file you read is mostly a dispatcher rather than a procedure.

The plugin packages bundle two things together: the use-railway skill and Railway's hosted MCP server. That coupling is the whole point. Installing the plugin gets you both the instructions an agent reads and the transport it calls.

How the skill and the MCP server fit together

Two mechanisms are in play, and the README keeps them distinct.

The first is the Agent Skills format, which the README links to at agentskills.io. A skill is a directory containing a SKILL.md file. The agent reads it and follows the routing described inside. In this repository the routing is deliberately shallow: SKILL.md decides which reference to load for a given intent, and the references carry the execution detail. That keeps the always-loaded portion small at the cost of a second read when the agent actually acts.

The second mechanism is Railway's hosted MCP server. The README states that each plugin package includes it, and that the Claude connector uses it with OAuth, so the connector path does not require the Railway CLI. That is a real architectural split: one path goes through a locally installed CLI and its authentication state, the other goes through a remote server and an OAuth flow inside the client. Which one you end up with is determined by your client, not by a configuration choice you make in this repository.

Where the CLI is involved, the README describes the bootstrap as installing the CLI and skills, configuring the Railway MCP server for detected tools, and checking Railway authentication. The detection step is the part worth noting. It configures tools it finds, which means the outcome depends on what is already on the machine when you run it.

Installing the Railway agent setup from the CLI

The README gives one command for the CLI route. It fetches a script from agents.railway.com and pipes it to a shell, which installs the Railway CLI and the skills, configures the Railway MCP server for detected tools, and checks authentication.

curl -fsSL agents.railway.com | sh

Because it is a piped install script, read it before running it if that matters to your environment. The README does not document an uninstall step, and it does not document what the script does to tool configuration files it detects.

If the script reports that you are not authenticated, the README gives the follow-up:

railway login

If the Railway CLI is already present and you only want the agent wiring, the README offers a narrower command that skips the installer:

railway setup agent

After either path, start a new agent session. The skill is loaded at session start in most clients, so a running session will not pick it up.

Installing Railway skills for Claude Code, Cursor, Codex and Grok Build

For Claude Code, the README relies on the official Anthropic marketplace being available by default. Inside Claude Code, install the plugin and reload:

/plugin install railway@claude-plugins-official
/reload-plugins

If the plugin is not found, the README gives a refresh command before retrying:

/plugin marketplace update claude-plugins-official

This is the point where the repository's own maintenance becomes your problem. The README states that the official marketplace pins each plugin to a specific commit, and that changes in this repository become available through claude-plugins-official only after the Railway entry in anthropics/claude-plugins-official is updated to a commit that contains them. A commit landing here is not the same as a commit reaching your client.

To bypass that lag, the repository ships its own Claude Code marketplace:

/plugin marketplace add railwayapp/railway-skills
/plugin install railway@railway-skills
/reload-plugins

Cursor takes a single command from its marketplace:

/add-plugin railway

Codex users add this GitHub repository as a marketplace through the Plugins sidebar, the More dropdown, and Add more. Grok Build users run grok, open the extensions modal with /plugins, switch to the Marketplace tab, select railway, and press i. ChatGPT and Codex also have an official Railway plugin listed in the shared plugin directory, which the README says requires connecting your Railway account when prompted and then starting a new chat or task.

Where this breaks down

The repository is not archived and the last push was on 2026-09-05, so the code is recent. That does not make the distribution path simple, and there are three real constraints.

First, there is no documented rollback. The README does not describe how to remove the MCP server configuration the bootstrap writes, how to uninstall the skill, or how to revert to a previous plugin commit. If the agent starts behaving differently after an update, the README gives you nothing to reverse it with.

Second, version skew is structural rather than a bug. Claude Code, Cursor, Codex and Grok Build each resolve Railway through a marketplace that pins a commit, and the README says explicitly that the official Claude Code marketplace updates only after a separate repository is bumped. Two engineers on the same client can be running different skill content on the same day.

Third, the connector path and the CLI path are not interchangeable. The Claude connector uses Railway's hosted MCP server and OAuth and does not need the Railway CLI, while the CLI bootstrap installs the CLI and configures MCP for tools it detects. If your environment forbids a locally installed CLI, only some of these routes are open to you. The README does not say which clients support the connector approach.

This is also the wrong tool if you are not on Railway. The skill routes Railway intents; there is no generic infrastructure surface here.

Alternatives and how they differ

The closest alternative is wiring Railway's hosted MCP server into your client by hand, without this repository. The difference is what you own. A manual MCP configuration gives you one file you control, one server URL, and one place to change when something breaks. railway-skills gives you a skill file that routes intent plus a plugin manifest per client, and it takes over the configuration step for detected tools. If you want a single auditable config file, the manual route is cleaner. If you want the agent to know how to act on Railway rather than merely reach it, the skill is the part you cannot reproduce by hand without writing it yourself.

The second alternative is the Claude connector, which the README presents as a distinct path rather than a variant of the plugin. It uses Railway's hosted MCP server and OAuth and does not require the Railway CLI. That makes it the better fit for managed machines where installing a CLI is not an option, at the cost of being Claude-specific. The plugin route spans five clients; the connector spans one.

Licence and upgrade cost

The repository is MIT licensed, and the README states that as the only licence term. MIT is permissive, so redistribution and modification inside a commercial product are not restricted by the licence itself. That is not legal advice; if you are shipping a modified skill to customers, read the LICENSE file in the repository root rather than the README summary.

The upgrade cost is uneven across clients. Claude Code through claude-plugins-official requires an upstream bump in anthropics/claude-plugins-official before your users see a change, so the latency is not something the Railway repository controls. The repository's own marketplaces at .agents/plugins/marketplace.json and .cursor-plugin/marketplace.json resolve directly from this repository, so they track main more closely. Codex and Grok Build resolve through the official xAI and OpenAI listings, which the README says pin to a specific commit. In practice, expect the official listings to lag and the self-hosted marketplaces to lead, and plan your testing around that gap rather than assuming all five clients move together.

Editorial conclusion

Adopt railway-skills if you already run Railway and want your coding agent to reach it without hand-wiring an MCP server, and pick the install path that matches your client: curl -fsSL agents.railway.com | sh for the CLI route, or the marketplace route for Codex, Claude Code, Cursor and Grok Build. Do not adopt it if you are not on Railway, if you need a documented uninstall or rollback, or if you want a stable pinned version, since the Claude Code official marketplace pins each plugin to a specific commit and changes only arrive after the Railway entry in anthropics/claude-plugins-official is updated. Verify first that the plugin your client resolves is the one you expect: the repository also ships its own marketplaces at .agents/plugins/marketplace.json and .cursor-plugin/marketplace.json, and those can lag the official listings.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. railwayapp/railway-skills on GitHub
5. README